Run MCP servers
This guide explains how to run Model Context Protocol (MCP) servers using ToolHive. It covers how to run servers from the ToolHive registry, customize server settings, and run custom servers using Docker images or protocol schemes.
Run a server from the registry
To run an MCP server from the ToolHive registry, use the
thv run
command with the name of the server you
want to run. The server name is the same as its name in the registry.
thv run <server-name>
For example:
thv run fetch
When you run an MCP server from the registry, ToolHive:
- Pulls the image and launches a container using the configuration from the registry.
- Launches an HTTP proxy on a random port to forward client requests to the container.
- Labels the container so it can be tracked by ToolHive:
toolhive: true
toolhive-name: <server-name>
See Running custom MCP servers to run a server that is not in the registry.
Customize server settings
You might need to customize the behavior of an MCP server, such as changing the port, mounting a local directory, or passing secrets. ToolHive provides several options to customize the server's configuration when you run it.
For a complete list of options, run
thv run --help
or see the
thv run
command reference.
Run a server with a custom name
By default, the container name matches the MCP server's name in the registry or
is automatically generated from the image name when you run a custom server. To
give your server instance a custom name, use the --name
option:
thv run --name my-custom-name <server-name>
For example:
thv run --name my-fetch fetch
Run a server with secrets
Many MCP servers require secrets or other configuration variables to function correctly. ToolHive lets you pass these secrets as environment variables when starting the server.
To pass a secret to an MCP server, use the --secret
option:
thv run --secret <secret-name>,target=<env-var-name> <server-name>
The target
parameter specifies the name of the environment variable in the MCP
server's container. This is useful for passing secrets like API tokens or other
sensitive information.
For example:
thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github
See Secrets management to learn how to manage secrets in ToolHive.
Mount a local directory
To let an MCP server access files on your host machine, you can mount a local directory into the container:
thv run --volume <host-path>:<container-path>[:ro] <server-name>
The optional :ro
suffix makes the volume read-only in the container. This is
useful for sharing files without letting the MCP server modify them.
ToolHive automatically adds mounted paths to the MCP server's permissions profile.
For example, to mount a local directory to the Filesystem MCP server:
thv run --volume ~/code/toolhive:/projects/toolhive filesystem
The filesystem server can now access the contents of ~/code/toolhive
as
/projects/toolhive
in the container (the filesystem MCP server expects
directories to be mounted at /projects
by default).
Pass additional arguments
Some MCP servers require additional arguments to run correctly. You can pass
these arguments after the server name in the
thv run
command:
thv run <server-name> -- <additional-args>
For example, to run the fetch
server with custom arguments:
thv run fetch -- --arg1 value1 --arg2 value2
Check the MCP server's documentation for the required arguments.
Run a server on a specific port
ToolHive creates a reverse proxy on a random port that forwards requests to the container. To specify the port for an MCP server:
thv run --port <port-number> <server-name>
Run a custom MCP server
To run an MCP server that isn't in the registry, you can use a Docker image or a protocol scheme to dynamically build the server.
ToolHive supports the following transport methods:
-
Standard I/O (
stdio
), default:
ToolHive redirects SSE traffic from the client to the container's standard input and output. This acts as a secure proxy, ensuring that the container doesn't have direct access to the network or the host machine. -
HTTP with SSE (server-sent events) (
sse
):
ToolHive creates a reverse proxy that forwards requests to the container. This means the container itself doesn't directly expose any ports. -
Streamable HTTP - coming soon!
The March 2025 revision of the MCP specification replaced the HTTP+SSE transport with Streamable HTTP. Follow the GitHub issue to be notified when this feature is available in ToolHive.
Run a server from a Docker image
To run an MCP server from a Docker image, specify the image name and tag in the
thv run
command. You can also specify a custom
name for the server instance, the transport method, and any additional arguments
required by the MCP server.
thv run [--name <friendly-name>] [--transport <stdio/sse>] <image-name:tag> -- <server-args>
For example, to run an MCP server from a Docker image named
my-mcp-server-image
that uses the SSE transport method and takes additional
arguments:
thv run --name my-mcp-server --transport sse my-mcp-server-image:latest -- --arg1 value1 --arg2 value2
Check your MCP server's documentation for the required arguments.
When you run an MCP server from a Docker image, ToolHive:
- Pulls the image (
my-mcp-server-image:latest
) and launches a container with the options and arguments you specified. - Launches an HTTP proxy on a random port (optionally, add
--port <port-number>
to specify the port). - Labels the container so it can be tracked by ToolHive:
toolhive: true
toolhive-name: my-mcp-server - Sets up the specified transport method (
--transport stdio
or--transport sse
).
See thv run --help
for more options.
Run a server using protocol schemes
ToolHive also supports running MCP servers directly from package managers. This means you can launch MCP servers without building or publishing a Docker image, and without installing language-specific build tools on your machine.
Currently, three protocol schemes are supported:
uvx://
: For Python-based MCP servers using the uv package managernpx://
: For Node.js-based MCP servers using npmgo://
: For Go-based MCP servers
thv run <protocol>://<package-name>@<version>
You'll likely need to specify additional arguments like the transport method,
volumes, and environment variables. Check your MCP server's documentation and
see thv run --help
for more options.
When you use a protocol scheme, ToolHive:
- Detects the protocol scheme and extracts the package reference
- Generates a Dockerfile based on the appropriate template
- Builds a Docker image with the package installed
- Runs the MCP server using the new image (see Run a server from a Docker image for details)
Examples
- Python (uvx)
- Node.js (npx)
- Go
The uvx://
protocol is used for Python-based MCP servers. The package name
must be a valid package in the PyPI registry. The
@<version>
suffix is optional and defaults to the latest version if omitted.
thv run --name aws-docs uvx://awslabs.aws-documentation-mcp-server@latest
The npx://
protocol is used for Node.js-based MCP servers. The package name
must be a valid package in the npm registry. The
@<version>
suffix is optional and defaults to the latest version if omitted.
thv run --name pulumi npx://@pulumi/mcp-server@latest
The go://
protocol is used for Go-based MCP servers. The package name must be
a valid Go module repo URI referencing the main
package. The @<version>
suffix is required.
thv run --name grafana go://github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
You can also run a local Go module by specifying the path to the module:
# Run from a relative path
thv run go://./cmd/my-mcp-server
# Run from the current directory
cd my-go-mcp-project
thv run go://.
# Run from an absolute path
thv run go:///path/to/my-go-project
Add a custom CA certificate
In corporate environments with TLS inspection or custom certificate authorities,
you may need to configure a CA certificate for ToolHive to use when building
containers from protocol schemes like uvx://
, npx://
, and go://
.
ToolHive provides both global configuration and per-command options for CA certificates.
Configure a global CA certificate
To set a CA certificate that ToolHive will use for all container builds:
thv config set-ca-cert /path/to/corporate-ca.crt
To view the currently configured CA certificate:
thv config get-ca-cert
To remove the CA certificate configuration:
thv config unset-ca-cert
Override CA certificate per command
You can override the global CA certificate configuration for a specific run
using the --ca-cert
flag:
thv run --ca-cert /path/to/other-ca.crt uvx://some-package
This is useful when you need to use different CA certificates for different servers or when testing with a specific certificate.
Priority order
ToolHive uses the following priority order for CA certificates:
- Command-line flag (
--ca-cert
) - Global configuration (
thv config set-ca-cert
) - No custom CA certificate (default behavior)
For example:
# Set a global CA certificate
thv config set-ca-cert /path/to/corporate-ca.crt
# This uses the configured CA certificate
thv run uvx://some-package
# This overrides the configured CA certificate
thv run --ca-cert /path/to/special-ca.crt uvx://other-package
Next steps
See Monitor and manage MCP servers to monitor and control your servers.
Related information
Troubleshooting
Server fails to start
If a server fails to start:
- Check if Docker/Podman is running
- Verify you have internet access to pull images
- Check if the port is already in use
- Look at the error message for specific issues
Server starts but isn't accessible
If a server starts but isn't accessible:
-
Check the server logs:
thv logs <server-name>
-
Verify the port isn't blocked by a firewall
-
Make sure clients are properly configured (see Client configuration)
Server crashes or exits unexpectedly
If a server crashes or exits unexpectedly:
-
List all MCP servers including stopped ones:
thv list --all
-
Check the logs for error messages:
thv logs <server-name>
-
Try running with a different permission profile:
thv run --permission-profile network <server-name>
-
Check if the server requires any secrets or environment variables