Skip to main content

Quickstart: ToolHive UI

In this tutorial, you'll install the ToolHive desktop 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 use the server with an AI client application

Prerequisites​

Before starting this tutorial, make sure you have:

Step 1: Install the ToolHive UI​

First, download and run the ToolHive installer for your system.

  • macOS: download the DMG installer for Apple silicon or Intel-based Macs and copy the ToolHive application to your Applications folder

  • Windows: download and run the installer

  • Linux: download the RPM or DEB package from the releases page and install it using your package manager.

For more detailed installation instructions, see the installing ToolHive guide.

Step 2: Find an MCP server to run​

Open the Registry page from the top menu bar. This page lists the MCP servers in ToolHive's built-in registry, the default catalog that ships with the UI.

What is this?

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 ToolHive Docs server (listed as toolhive-doc-mcp in the registry), which lets AI agents search the ToolHive documentation. Click on the ToolHive Docs entry to start the installation process.

Step 3: Install the ToolHive Docs server​

The ToolHive Docs server doesn't require any special configuration, so you can install it with the default settings. Click the Install server button to start the installation.

Once installed, the server appears on the MCP Servers page.

What's happening?

ToolHive downloads the container image for the server, creates a container with the appropriate security settings, and starts it. ToolHive also sets up a proxy process that lets your AI agent communicate with the server.

Prefer not to run a container?

The registry also includes ToolHive Docs (Remote), a hosted version of the same server at https://toolhive-doc-mcp.stacklok.com/mcp. Install that entry instead to skip the container pull. The rest of the tutorial works the same way.

Step 4: Connect an AI client​

On the Clients page, you'll see the supported AI clients that ToolHive can manage for you. When you connect a client, ToolHive configures it to use the MCP servers you have installed.

Click the toggle switch to connect the client you want to use.

What's happening?

When you connect a supported client, ToolHive automatically configures it to use MCP servers that you install. This means you don't have to manually configure the client each time you run an MCP server.

Step 5: Use the MCP server with your client​

Now that your MCP server is running and your client is connected to ToolHive, you can use the MCP server's tools. Open your client 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 large language model (LLM) determines that it needs reference material. It discovers the query_docs and get_chunk tools provided by your MCP server, 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.

Next steps​

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

Ready to go further?

Stacklok Enterprise extends ToolHive with centralized management, IdP integration, and hardened images for teams deploying MCP at scale.

Learn about Stacklok Enterprise →

Troubleshooting​

Server fails to start

If the server fails to start:

  • Confirm Docker, Podman, or Colima is running.
  • Confirm you have internet access to pull the container image.

For more startup issues, see the Install ToolHive troubleshooting section.

Client can't use the server

If your AI client can't use the server:

  • Make sure your client is connected to ToolHive (see Step 4).
  • Restart your client to pick up the new configuration.
  • Verify the server is running on the MCP Servers page.
  • Disconnect and reconnect the client in ToolHive to refresh the configuration.

For other issues, join the Discord community for help.