Skip to main content

Quickstart: ToolHive CLI

In this tutorial, you'll install the ToolHive command-line application and run your first MCP server. By the end, you'll have a working MCP server that can answer questions about ToolHive and be used by AI applications like GitHub Copilot or Cursor.

What you'll learn​

  • How to install ToolHive on your system
  • How to find available MCP servers
  • How to run an MCP server
  • How to verify the server is working
  • How to use the server with an AI client application

Prerequisites​

Before starting this tutorial, make sure you have:

  • Docker or Podman or Colima installed and running
  • (Optional) A supported MCP client such as GitHub Copilot in VS Code, Cursor, or Claude Code. Needed only if you want to test end-to-end client integration.

Step 1: Install ToolHive​

First, install ToolHive on your system. ToolHive provides the thv command-line tool that manages MCP servers in secure containers.

For detailed installation instructions, see the installing ToolHive guide. Here's a quick summary:

brew tap stacklok/tap
brew install thv

Verify your installation​

After installing, verify that ToolHive is working correctly:

thv version

You should see output similar to this:

ToolHive v0.1.1
Commit: 18956ca1710e11c9952d13a8dde039d5d1d147d6
Built: 2025-06-30 13:59:34 UTC
Go version: go1.24.1
Platform: darwin/arm64

This confirms ToolHive is installed and ready to use.

Step 2: Find an MCP server to run​

See what MCP servers are available in the registry:

thv registry list

You'll see output similar to this:

NAME                                          TYPE        DESCRIPTION                                          TIER        STARS
io.github.stacklok/atlassian                  container   Connect to Atlassian products like Confluence, ...   Community   5002
io.github.stacklok/fetch                      container   A Model Context Protocol server that provides ...    Community   56714
io.github.stacklok/github                     container   The GitHub MCP Server provides seamless integr...    Official    16578
io.github.stacklok/notion                     container   Official Notion MCP server.                          Official    2358
io.github.stacklok/toolhive-doc-mcp           container   Search ToolHive docs for help with using and c...    Official    3
io.github.stacklok/toolhive-doc-mcp-remote    remote      Search ToolHive docs for help with using and c...    Official    3
...

The TYPE column shows whether the server runs as a local container or is a hosted remote endpoint that ToolHive proxies to.

This shows all the MCP servers available in the ToolHive registry.

What's happening?

ToolHive maintains a curated registry of MCP servers that have been verified to work correctly. This built-in registry is the default catalog that the CLI uses to help you find and launch servers.

For this tutorial, you'll use the toolhive-doc-mcp server, which lets AI agents search the ToolHive documentation. To learn more about the server before running it, run:

thv registry info toolhive-doc-mcp

This shows you detailed information about the server, including what tools it provides and any configuration options.

Step 3: Run the toolhive-doc-mcp server​

Now, run the server:

thv run toolhive-doc-mcp

ToolHive pulls the container image and starts the server in the background. You'll see a log line similar to this:

{"time":"2026-05-18T09:49:14-04:00","level":"INFO","msg":"logging to","path":"~/Library/Application Support/toolhive/logs/toolhive-doc-mcp.log"}

The full server logs are written to the file shown in the logging to line.

What's happening?

When you run an MCP server, ToolHive:

  • Downloads the container image
  • Sets up the container with the necessary security settings and starts it in the background
  • Sets up a reverse proxy that lets your AI client applications communicate with the server
Prefer not to run a container?

ToolHive also ships a hosted version of the docs server. Run thv run toolhive-doc-mcp-remote instead to connect to the hosted endpoint at https://toolhive-doc-mcp.stacklok.com/mcp without pulling an image. ToolHive sets up the same kind of proxy, so the rest of this tutorial works the same way, but commands that reference the workload name should use toolhive-doc-mcp-remote.

Step 4: Verify the server is running​

Check that the server is running:

thv list

You should see output similar to this:

NAME               PACKAGE                                                  STATUS    URL                          PORT    GROUP     CREATED
toolhive-doc-mcp   ghcr.io/stackloklabs/toolhive-doc-mcp:v0.0.14-20260518   running   http://127.0.0.1:19767/mcp   19767   default   2026-05-18 09:49:14 -0400 EDT

This confirms that the server is running. ToolHive picks a free local port at startup, so your port number will be different.

What's happening?

ToolHive keeps track of all the MCP servers it's managing. The list command shows you which servers are running and how they're configured.

Step 5: Connect an AI client​

To see the full payoff of the tutorial, have ToolHive configure a supported MCP client for you now:

thv client setup

Select one or more clients from the list using the spacebar to toggle selection. Press Enter to confirm your selection.

Confirm that your client is registered successfully:

thv client status

You should see output similar to this:

┌────────────────┬───────────┬────────────┐
│ CLIENT TYPE    │ INSTALLED │ REGISTERED │
├────────────────┼───────────┼────────────┤
│ vscode         │ ✅ Yes    │ ✅ Yes     │
└────────────────┴───────────┴────────────┘
What's happening?

When you run the setup command, ToolHive automatically finds supported clients on your system. When you register a client, ToolHive automatically configures it to use MCP servers that you run.

Step 6: Use the MCP server with your AI client​

If you completed Step 5, you can now use the MCP server with your AI client application. Open your supported client (VS Code, Cursor, etc.) and ask the AI a question about ToolHive. Note that you might need to restart your client for the changes to take effect.

For example, try asking: "What is a Virtual MCP Server and how do I use it with ToolHive?"

The AI calls the query_docs tool to search the ToolHive documentation and uses the results to compose an answer.

What's happening?

When you ask a question about ToolHive, the AI client discovers the query_docs and get_chunk tools your MCP server exposes, calls them to search the official ToolHive documentation, then uses the returned passages to construct a grounded answer instead of relying on its training data alone.

Step 7: Stop the server when you're done​

When you're finished using the server, you can stop it:

thv stop toolhive-doc-mcp

If you want to remove it completely:

thv rm toolhive-doc-mcp
What's happening?

Stopping a server pauses it and terminates the associated proxy process but keeps the container around so you can start it quickly later using thv start or thv run. Removing a server completely deletes the container, freeing up resources.

Next steps​

Congratulations! You've successfully installed ToolHive and run your first MCP server. Here are some next steps to explore:

Using ToolHive with a team?

ToolHive Community is great for individual use. When your organization needs centralized governance, IdP integration (Okta, Entra ID), and hardened production-ready MCP servers, that's where Stacklok Enterprise comes in.

See what's included in Stacklok Enterprise →

Troubleshooting​

If something doesn't work as expected, the Run MCP servers troubleshooting section covers the common failure modes (server fails to start, no tools showing up in the client, port conflicts, etc.).

A few quick checks specific to this tutorial:

  • Confirm Docker, Podman, or Colima is running before thv run toolhive-doc-mcp (or use the toolhive-doc-mcp-remote variant, which doesn't need a container runtime).
  • ToolHive picks a free local port for the proxy at startup. If you need a specific port, pass --proxy-port, for example thv run --proxy-port 8081 toolhive-doc-mcp.
  • After running thv client setup, restart your AI client so it picks up the new configuration.

If you're still stuck, please join our Discord community for help.