Skip to main content

Run MCP servers

ToolHive makes it easy to run and manage Model Context Protocol (MCP) servers. This guide walks you through installing MCP servers from the registry and adding your own custom servers from Docker images, source packages, or remote URLs.

Each install flow ends at a configuration form. For a description of every setting on that form, see Configure MCP servers.

Install from the registry​

ToolHive includes a built-in registry of MCP servers that meet a minimum quality standard, allowing you to discover and deploy high-quality tools effortlessly. Select one from the list to run it securely with just a few clicks.

The registry includes both local servers, which run as containers on your machine, and remote servers, which connect to a hosted service. Each server's entry in the registry is labeled with a local or remote icon.

Select an MCP server​

  1. Open the Registry page from the menu bar.
  2. Browse or search for the MCP server you want to install.
  3. Click on the desired MCP server to open its details page. Here you can review more information about the server like its:
    • Description
    • Available tools
    • Tier (community or official)
    • Popularity (GitHub stars)
    • A link to the GitHub repository for more details and usage documentation
  4. Click the Install server button to start the installation process.

Configure and start the server​

The configuration form is pre-filled with defaults from the registry. Enter the remaining required information and adjust any optional settings as needed:

  • For a local server, review the name, group, command arguments, secrets and environment variables, storage volumes, and network isolation.
  • For a remote server, review the URL, transport protocol, and authorization method.

For a description of each setting, see Configure MCP servers.

note

Refer to the MCP server's documentation for the required configuration information, permissions, and authentication details. A link to the GitHub repository is provided on each server's details page.

Click Install server to install and start the MCP server. For local servers, ToolHive downloads the Docker image, creates a container, and starts it with the specified configuration. For remote servers, ToolHive connects to the hosted service.

Once the server is running, you can see its status on the MCP Servers page. See Manage MCP servers below for details on server states.

Install a custom MCP server​

You're not limited to the MCP servers in the registry. You can run your own local custom MCP servers using Docker images or source packages, or connect to remote MCP servers by providing a URL.

For a description of every setting referenced below, see Configure MCP servers.

Custom local servers​

On the MCP Servers page, click Add an MCP server, then choose Add custom local server in the drop-down menu (or, if this is your first MCP server, use the option on the introductory screen).

In the Custom MCP server dialog, choose Docker image or Package manager.

From a Docker image​

Select the Docker image option. This allows you to run any MCP server that is available as a Docker image in a remote registry or locally on your system.

On the configuration form, enter the Docker image name and tag (for example, my-mcp-server:latest), then set the transport protocol and any other settings the server needs. You can use any valid Docker image, including those hosted on Docker Hub or other registries.

Click Install server to create and start the MCP server container.

From a source package​

Select the Package manager option. This allows you to run an MCP server from a source package. ToolHive downloads the package and builds a Docker image on-the-fly. The following package formats are supported:

  • Node.js-based MCP servers using npm
  • Python-based MCP servers available on PyPI, using the uv package manager
  • Go-based MCP servers available on GitHub

On the configuration form, enter:

  1. The package protocol (npx, uvx, or go). [Required]
  2. The name of the package to run. [Required]
    • For npx, use the npm package name and version, for example my-mcp-package@latest.
    • For uvx, use the PyPI package name and version, for example my-mcp-package@latest.
    • For go, use the GitHub repository URL with the full path to the main package and version, for example go://github.com/orgname/my-mcp-server/cmd/server@latest.

Set the transport protocol and any other settings the server needs, then click Install server to build and start the MCP server container.

Custom remote servers​

On the MCP Servers page, click Add an MCP server, then choose Add a remote MCP server in the drop-down menu.

On the configuration form, enter the URL of the remote server and choose an authorization method. Click Install server to connect to the remote MCP server.

Manage MCP servers​

On the MCP Servers page, you can manage your installed MCP servers. Each server's card includes:

  • The server name
  • Its status (Running or Stopped) with a toggle button to start or stop it
  • A menu (︙) with additional options

Use the Start/Stop toggle to start or stop the MCP server. When you stop a server, it remains in the list but is no longer running. ToolHive removes the server from connected AI clients while stopped.

Click the menu (︙) on the server card to access these options:

  • Copy URL (⧉): Copy the MCP server's URL to your clipboard. This URL is used by AI clients to connect to the MCP server.
  • Edit configuration: Modify the server's settings, such as command arguments, environment variables, secrets, storage volumes, and network isolation. The dialog is pre-filled with your existing configuration, so you only need to change the specific settings you want to update.
  • GitHub repository: View the MCP server's source code and documentation on GitHub. (Only available for servers installed from the registry using the default name.)
  • Logs: View the server's output. For local servers, this shows the container logs. For remote servers, it shows logs from the proxy process.
  • Remove: Stop and remove the MCP server from ToolHive. This deletes the container and any associated configuration, so use with caution.
  • Copy server to a group: Duplicate the server configuration to a different group. See Organize servers into groups for details.

When you quit the application, ToolHive prompts you to stop all running MCP servers. The running servers are recorded and ToolHive restarts them automatically the next time you launch the application.

Upgrade registry image versions​

For MCP servers installed locally from the registry, ToolHive shows an upgrade option on the server card when a newer image tag is available in the registry. The option appears only when all of the following are true:

  • The server runs locally, not as a remote MCP server.
  • The server was installed from a registry that includes an image field.
  • The local image tag differs from the registry image tag.

When an upgrade is available, the server card shows an upgrade icon control next to the start and stop actions. The same action is available in the server's overflow (⋮) menu as Update to <TAG>, where <TAG> is the registry image tag.

The control's tooltip reads:

Update available: <LOCAL_TAG> → <REGISTRY_TAG>

ToolHive disables the menu item while the server is being removed or updated.

Selecting the upgrade control opens the Update to latest version dialog. ToolHive compares the local server's environment variables against the registry definition for the new tag and shows one of two outcomes:

  • No configuration drift: ToolHive shows the message:

    No configuration changes detected between versions.

    The dialog offers Update and Cancel. Click Update to pull the new image and restart the server with your existing configuration, or Cancel to dismiss the dialog.

  • Configuration drift: ToolHive lists changes under New variables in this version: (with secret, env, and required badges where applicable) and Variables no longer in registry:. The dialog offers Edit and review and Cancel instead of Update, because new values may be required.

    • Click Edit and review to open the edit flow with the new image tag and any added variables prefilled.
    • Supply values, adjust secrets, and remove obsolete variables, then save.
    • Click Cancel to keep the current version.

The Edit and review flow only updates the server when you save the edit form. If you cancel out of the edit flow, the server keeps its current image tag and configuration.

tip

Upgrading the image tag does not reconcile drift in the server's tool list. If the new image adds, removes, or renames tools, review the changes on the Customize tools page. See Drift and registry mismatches for details.

Next steps​