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 fetch content from websites 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:

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: Register your client​

Next, run the ToolHive client setup command to register your MCP client:

thv client setup

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

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. This means you don't have to manually configure the client to connect to the MCP server.

Confirm that your client is registered successfully:

thv client status

You should see output similar to this:

┌────────────────┬───────────┬────────────┐
│ CLIENT TYPE    │ INSTALLED │ REGISTERED │
├────────────────┼───────────┼────────────┤
│ vscode         │ ✅ Yes    │ ❌ No      │
└────────────────┴───────────┴────────────┘

Step 3: 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       DESCRIPTION                                                    TIER        STARS   PULLS
atlassian  Model Context Protocol (MCP) server for Atlassian product...   Community   2194    7789
fetch      A Model Context Protocol server that provides web content...   Community   56714   9078
github     The GitHub MCP Server provides seamless integration with ...   Official    16578   5000
notion     Official Notion MCP server.                                    Official    2358    1109
...

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. The registry includes information about what each server does and how to use it.

For this tutorial, you'll use the "fetch" server, which is a simple MCP server that lets AI agents get the contents of a website. To learn more about the server before running it, run:

thv registry info fetch

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

Step 4: Run the Fetch MCP server​

Now, run the Fetch server:

thv run fetch

ToolHive will pull the container image and start the server. You'll see output similar to this:

8:41AM INF MCP server ghcr.io/stackloklabs/gofetch/server:latest is verified successfully
8:41AM INF Image ghcr.io/stackloklabs/gofetch/server:latest has 'latest' tag, pulling to ensure we have the most recent version...
8:41AM INF Pulling image: ghcr.io/stackloklabs/gofetch/server:latest
Pulling from stackloklabs/gofetch/server: latest
Digest: sha256:b9cbe3a8367f39e584d3fdd96d9c5046643c5f4798c3372b0c9049ece202cdef
Status: Image is up to date for ghcr.io/stackloklabs/gofetch/server:latest
8:41AM INF Successfully pulled image: ghcr.io/stackloklabs/gofetch/server:latest
8:41AM INF Using target port: 15266
8:41AM INF Logging to: ~/Library/Application Support/toolhive/logs/fetch.log
8:41AM INF MCP server is running in the background (PID: 16834)
8:41AM INF Use 'thv stop fetch' to stop the server
What's happening?

When you run an MCP server, ToolHive:

  • Verifies the MCP server image provenance (if attestation information is available in the registry)
  • 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

Step 5: 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    TOOL TYPE   CREATED AT
fetch   ghcr.io/stackloklabs/gofetch/server:latest   running   http://127.0.0.1:15266/sse#fetch   15266   mcp         2025-07-10 08:41:56 -0400 EDT

This confirms that the fetch server is running and available on port 49226.

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 6: Use the MCP server with your AI client​

Now that your MCP server is running, you can use it with your AI client application. Open your supported client (VS Code, Cursor, etc.) and ask the AI to fetch content from a website. Note that you might need to restart your client for the changes to take effect.

For example, try asking: "Can you fetch the content from https://toolhive.dev and summarize it for me?"

The AI should be able to use the Fetch MCP server to retrieve the content and provide a summary.

What's happening?

When you ask the AI to fetch content, it detects that it needs external data. It discovers the fetch tool provided by your MCP server, calls the tool with the URL you specified, receives the webpage content, and then processes that content to create a summary.

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

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

thv stop fetch

If you want to remove it completely:

thv rm fetch
What's happening?

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

What's next?​

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

Troubleshooting​

Server fails to start

If the server fails to start, check:

  • Is Docker or Podman running?
  • Do you have internet access to pull the container image?
  • Is the port already in use by another application?

Try running with a specific port:

thv run --proxy-port 8081 fetch
Client can't use the server

If your AI client application can't use the server:

  • Make sure your client is registered with ToolHive (see Step 2)
  • Check that your client is supported
  • Restart your client to pick up the new configuration
  • Verify the server is running with thv list

If you encounter any problems, please join our Discord community for help.