Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://docs.stacklok.com/toolhive/guides-cli/run-mcp-servers below:

Run MCP servers | Stacklok Docs

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.

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.

For example, to run the fetch server, which is a simple MCP server that fetches website contents:

What's happening?

When you run an MCP server from the registry, ToolHive:

1. Pulls the image and launches a container using the configuration from the registry.
2. Starts an HTTP proxy process on a random port to forward client requests to the container.
3. Labels the container so it can be tracked by ToolHive:

   toolhive: true
   toolhive-name: <SERVER_NAME>
   

See Run a custom MCP server to run a server that is not in the registry.

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.

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

For example:

thv run --name my-fetch fetch

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>

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.

To enable file system access for an MCP server, you can either use the --volume flag to mount specific paths or create a custom permission profile that defines read and write permissions.

See File system access for detailed examples.

To restrict an MCP server's network access, use the --isolate-network flag. This enforces network access rules from either the server's default registry permissions or a custom permission profile you create.

See Network isolation for network architecture details and examples.

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

For example:

thv run my-mcp-server:latest -- --arg1 value1 --arg2 value2

Check the MCP server's documentation for the required arguments.

ToolHive creates a reverse proxy on a random port that forwards requests to the container. This is the port that client applications connect to. To set a specific proxy port instead, use the --proxy-port flag:

thv run --proxy-port <PORT_NUMBER> <SERVER>

ToolHive can filter the tools returned to the client as result of a tools/list command as well as block calls to tools that you don't want to expose.

This can help reduce the amount of tools sent to the LLM while still using the same MCP server, but it is not meant as a security feature.

To filter the list of tools, use the --tools flag either once

thv run --tools <TOOL_1> <SERVER>

Or multiple times

thv run --tools <TOOL_1> --tools <TOOL_2> <SERVER>

For example:

thv run --tools list_issues --tools get_issue github

If the server comes from the registry, ToolHive can validate the tool names against the list advertised in the image reference. An error is returned in case ToolHive cannot find one of the specified tools.

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 or Streamable HTTP 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 using the HTTP/SSE protocol.

• Streamable HTTP (streamable-http):
  ToolHive creates a reverse proxy that forwards requests to the container using the Streamable HTTP protocol, which replaced SSE in the MCP specification as of the 2025-03-26 revision.

info

We are actively monitoring the adoption of the Streamable HTTP protocol across the client ecosystem. Once we confirm that ToolHive's supported clients support Streamable HTTP, we will make it the default proxy transport method for stdio servers.

Currently, you can add the --proxy-mode streamable-http flag to the thv run command to use Streamable HTTP for stdio servers. This will ensure that the server is compatible with the latest MCP specification and can be used with clients that support Streamable HTTP.

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/streamable-http>] <IMAGE_REFERENCE> -- <ARGS>

For example, to run an MCP server from a Docker image named my-mcp-server-image that uses the Streamable HTTP transport method and takes additional arguments:

thv run --name my-mcp-server --transport streamable-http my-mcp-server-image:latest -- --arg1 value1 --arg2 value2

Check your MCP server's documentation for the required arguments.

What's happening?

When you run an MCP server from a Docker image, ToolHive:

1. Pulls the image (my-mcp-server-image:latest) and launches a container with the options and arguments you specified.
2. Launches an HTTP proxy on a random port (optionally, add --proxy-port <PORT_NUMBER> to specify the port).
3. Labels the container so it can be tracked by ToolHive:

   toolhive: true
   toolhive-name: my-mcp-server
   

4. Sets up the specified --transport method (stdio, sse, or streamable-http).

See thv run --help for more options.

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 manager
• npx://: For Node.js-based MCP servers using npm
• go://: For Go-based MCP servers

thv run <uvx|npx|go>://<PACKAGE_NAME>@<VERSION|latest>

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.

What's happening?

When you use a protocol scheme, ToolHive:

1. Detects the protocol scheme and extracts the package reference
2. Generates a Dockerfile based on the appropriate template
3. Builds a Docker image with the package installed
4. Runs the MCP server using the new image (see Run a server from a Docker image for details)

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

thv run go://./cmd/my-mcp-server


cd my-go-mcp-project
thv run go://.


thv run go:///path/to/my-go-project

When you run custom MCP servers using the SSE (--transport sse) or Streamable HTTP (--transport streamable-http) transport method, ToolHive automatically selects a random port to expose from the container to the host and sets the MCP_PORT and FASTMCP_PORT environment variables in the container.

This is equivalent to running a Docker container with docker run -p <random_host_port>:<random_container_port> ...

For MCP servers that use a specific port or don't recognize those environment variables, specify the container port for ToolHive to expose using the --target-port flag:

thv run --transport streamable-http --target-port <PORT_NUMBER> <SERVER>

ToolHive still maps the container port to a random port on the host to avoid conflicts with commonly used ports. This is equivalent to running a Docker container with docker run -p <random_port>:<PORT_NUMBER> ...

Some MCP servers use command-line arguments to specify their transport and port. For example, if your server expects the transport type as a positional argument and requires the --port flag, you can pass it like this:

thv run --transport streamable-http --target-port <PORT_NUMBER> <SERVER> -- http --port <PORT_NUMBER>

Check your MCP server's documentation for the required transport and port configuration.

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.

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:

To remove the CA certificate configuration:

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.

ToolHive uses the following priority order for CA certificates:

1. Command-line flag (--ca-cert)
2. Global configuration (thv config set-ca-cert)
3. No custom CA certificate (default behavior)

For example:

thv config set-ca-cert /path/to/corporate-ca.crt


thv run uvx://some-package


thv run --ca-cert /path/to/special-ca.crt uvx://other-package

See Monitor and manage MCP servers to monitor and control your servers.

• thv run command reference
• Client configuration
• Secrets management
• Custom permissions
• File system access
• Network isolation

If a server fails to start:

1. Check if Docker/Podman is running
2. Verify you have internet access to pull images
3. Check if the port is already in use
4. Look at the error message for specific issues

If a server starts but isn't accessible:

1. Check the server logs:

2. Verify the port isn't blocked by a firewall

3. Make sure clients are properly configured (see Client configuration)

If a server crashes or exits unexpectedly:

1. List all MCP servers including stopped ones:

2. Check the logs for error messages:

3. Check if the server requires any secrets or environment variables

4. Verify the server's configuration and arguments

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4