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 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 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

    note

    The Windows installer is not digitally signed yet, so you will need to accept the warning from Windows Defender SmartScreen. We're working on getting a signed installer published soon.

  • 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​

On the initial splash screen, click Browse registry, or open the Registry page from the top menu bar. This page lists the MCP servers in ToolHive's built-in registry.

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 "fetch" server, which is a simple MCP server that lets AI agents get the contents of a website. Click on the "fetch" server to start the installation process.

Step 3: Install the Fetch MCP server​

The Fetch MCP 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 the server is installed, it will appear on the MCP Servers page.

What's happening?

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

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 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 agent to fetch content, the large language model (LLM) determines that it needs external data. It discovers the fetch tool provided by your MCP server, instructs the agent to execute the tool with the URL you specified, then receives and processes the webpage content to create a summary.

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?
Client can't use the server

If your AI client application 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

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