Skip to main content

Configure MCP servers

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 a server's configuration when you run it.

These options apply whether you run a server from the registry, from a custom image or protocol scheme, or as a remote server - but not all options apply to every mode. They fall into two groups:

  • Options for all servers operate at the proxy or workload level, so they work for registry, custom, and remote servers.
  • Options for local servers configure the container that ToolHive runs on your machine. They have no effect on remote servers, which proxy to a URL instead of running a local container.

For a complete list of options, run thv run --help or see the thv run command reference.

Options for all servers​

These options apply to every run mode, including remote servers.

Run a server with a custom name​

By default, the workload 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

Run a server within a group​

To run an MCP server within a specific group, use the --group option. This allows you to organize your servers and manage them collectively.

thv run --group <GROUP_NAME> <SERVER>
note

The group must exist before you can run a server in it.

See Organize servers into groups to learn more about organizing servers and configuring client access.

Run a server on a specific port​

ToolHive creates a reverse proxy on a random port that forwards requests to the server. 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>

For local servers, you can also publish the container's own port directly to the host (separate from the proxy port) with --publish (-p) using hostPort:containerPort. Repeat the flag for multiple ports:

thv run --publish 8090:8080 <SERVER>

Most servers only need the proxy port; use --publish when a container exposes an additional port you need to reach directly.

Override the session timeout​

ToolHive's proxy evicts idle MCP sessions after 2 hours by default. To raise or lower this inactivity timeout for a workload, pass --session-ttl with a Go duration string:

thv run --session-ttl 4h <SERVER>

Set a longer value when clients hold sessions open for long-running operations, or a shorter value to free resources faster.

Run a server in the foreground​

By default, ToolHive runs the server in the background and returns control to your shell. To keep the process attached to your terminal until the server stops, use the --foreground (-f) flag:

thv run --foreground <SERVER>

This is useful for debugging or when you want the server's lifecycle tied to the current shell session.

Run a server exposing only selected tools​

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.

Override tool names and descriptions​

With ToolHive you can modify how tools exposed by an MCP server are exposed to clients. In particular, tool names and descriptions can be changed.

This is useful when you want to guide an agent toward calling a specific tool for particular questions.

One common use case is running multiple copies of the same MCP server with different network access levels, one for internal resources and another for public internet access. By overriding the tool names and descriptions, you can help your agent choose the right server for each task.

For example, the fetch MCP server exposes a single fetch tool with a description like:

"Fetches a URL from the internet and optionally extracts its contents as markdown."

To override this, create a configuration file with one entry under toolsOverride for each tool you want to modify:

{
  "toolsOverride": {
    "fetch": {
      "name": "toolhive-docs-fetch",
      "description": "Fetches a URL from https://docs.stacklok.com/toolhive website."
    }
  }
}

Then pass this file to thv run:

thv run --tools-override override.json fetch

The key in the override object is the original tool name, while the name field contains the new name that clients will see.

info

Take care when using --tools and --tools-override together in the same command.

Tool filtering and tool overrides work independently: filtering limits access to a subset of tools, while overrides change how those tools appear to clients.

When using both options, --tools must reference the overridden names (the new names you define) since those are what clients will see.

Enable audit logging​

ToolHive can record an audit trail of the MCP activity that flows through a server's proxy. Audit events capture interactions such as client initialization, tools/list and tools/call requests, resource reads, prompt requests, and notifications, along with metadata like the timestamp, component name, and outcome.

To turn on audit logging with ToolHive's built-in defaults, use the --enable-audit flag:

thv run --enable-audit <SERVER>

The default configuration records each event type but omits the request and response payloads to protect potentially sensitive data.

The audit middleware runs in the ToolHive proxy process, not in the MCP server container, so audit events are written to the proxy's logs. Pass the --proxy flag to thv logs to view them:

thv logs <SERVER_NAME> --proxy

Each event is emitted as a JSON object on its own line, which makes the output easy to filter or forward to a log aggregator.

For finer control, supply your own configuration file with the --audit-config flag instead:

thv run --audit-config ./audit.json <SERVER>

A configuration file lets you select which event types to record with eventTypes (or exclude specific types with excludeEventTypes), choose whether to include request or response data, and set where to send the audit log. For example:

audit.json
{
  "component": "fetch-server",
  "eventTypes": ["mcp_tool_call", "mcp_resource_read"],
  "includeRequestData": true,
  "includeResponseData": false,
  "maxDataSize": 2048,
  "logFile": "./fetch-audit.log"
}

When you set logFile, ToolHive appends audit events to that file instead of the proxy logs. Use a path that the user running thv can write to. Leave it unset to keep events in the proxy logs viewed by thv logs --proxy.

note

Use either flag to turn on audit logging: --enable-audit for the built-in defaults, or --audit-config to load your own settings. --audit-config enables auditing on its own, so you don't need to pass --enable-audit as well.

Setting includeRequestData or includeResponseData to true can capture sensitive arguments or results in the audit log. Enable these options only when you understand the privacy implications, and adjust maxDataSize to limit how much of each payload is recorded.

Options for local servers​

These options configure the container that ToolHive runs on your machine for registry and custom servers. They have no effect on remote servers, which proxy to a URL instead of running a local container.

Pass environment variables​

Many MCP servers read non-sensitive configuration from environment variables. Pass them individually with -e / --env:

thv run -e <KEY>=<VALUE> -e <KEY2>=<VALUE2> <SERVER>

To load variables from a file instead, use --env-file. To load every file in a directory, use --env-file-dir:

thv run --env-file ./server.env <SERVER>
thv run --env-file-dir ./env.d <SERVER>

For sensitive values such as API tokens, use --secret instead, so the value is resolved from your secrets provider rather than passed in plaintext.

Run a server with secrets​

Many MCP servers require secrets such as API tokens to function correctly. ToolHive resolves these from your secrets provider and injects them into the container as environment variables.

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.

For example:

thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github

See Secrets management to learn how to manage secrets in ToolHive. To supply credentials to a remote server, see authentication setup.

Mount a local file or directory​

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 prevent sensitive files from being exposed when mounting a project, use .thvignore.

Restrict network access​

ToolHive enables network isolation by default, restricting an MCP server's outbound traffic to the hosts and ports declared in its permission profile. Override the default profile with --permission-profile, or opt out entirely with --isolate-network=false.

See Network isolation for network architecture details and examples.

Add command-line 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> -- <ARGS>

For example:

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

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

warning

Some MCP servers in the ToolHive registry include default arguments that are essential for proper operation. When you provide custom arguments using -- <ARGS>, these replace the registry defaults entirely rather than adding to them.

Before adding custom arguments, check the server's registry entry:

thv registry info <SERVER> --format json | jq '.args'

If default arguments are listed, include them along with your custom arguments to ensure the server functions correctly.

Verify container image signatures​

For MCP servers that run from a container image, ToolHive can check the image's signature and provenance before launching it. Some registry servers publish provenance information that ToolHive uses to confirm the image was built and signed as expected. To see whether a given server has it, check the Has Provenance field in the output of thv registry info <SERVER_NAME>.

Use the --image-verification flag to control this behavior. It accepts three values:

  • warn (default): verify the image and log a warning if verification fails or the server has no provenance information, but run the server anyway.
  • enabled: verify the image and refuse to run the server if verification fails or no provenance information is available.
  • disabled: skip image verification entirely.
thv run --image-verification enabled <SERVER>

For example, to enforce verification when running the fetch server:

thv run --image-verification enabled fetch
note

Verification succeeds only for servers that include provenance information, and not every server does. When a server has no provenance data, warn runs it with a warning while enabled declines to run it. If you set enabled, keep in mind that it stops servers without provenance, not only servers that fail verification.

Next steps​