Skip to main content

Quickstart - run your first MCP server

In this tutorial, you'll install ToolHive 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.0.38
Commit: c321ba873f5dcb1d33035d4f8496eb3e22f8b37e
Built: 2025-05-29 12:03:02 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                                                    TRANSPORT   STARS   PULLS
fetch     A Model Context Protocol server that provides web content...   stdio       49668   7062
github    The GitHub MCP Server provides seamless integration with ...   stdio       14545   5000
postgres  A Model Context Protocol server that provides read-only a...   stdio       49668   9095
...

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:

Image [mcp/fetch:latest] has 'latest' tag, pulling to ensure we have the most recent version...
Pulling image: [mcp/fetch:latest]
...
Successfully pulled image: [mcp/fetch:latest]
Using host port: [49226]
Logging to: [~/Library/Application Support/toolhive/logs/fetch.log]
MCP server is running in the background (PID: [80087])
Use 'thv stop [fetch]' to stop the server
What's happening?

ToolHive downloads the container image for the fetch server (if you don't already have it), creates a container with the appropriate security settings, and starts the server. It also sets up a proxy that lets your AI agent 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:

CONTAINER ID   NAME    IMAGE              STATE     TRANSPORT   PORT    URL
f01ed0263286   fetch   mcp/fetch:latest   running   stdio       49226   http://localhost:49226/sse#fetch

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://stacklok.com 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 --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