| title | thv run | ||
|---|---|---|---|
| hide_title | true | ||
| description | Reference for ToolHive CLI command `thv run` | ||
| last_update |
|
||
| slug | thv_run | ||
| mdx |
|
Run an MCP server
Run an MCP server with the specified name, image, or protocol scheme.
ToolHive supports five ways to run an MCP server:
-
From the registry:
$ thv run server-name [-- args...]Looks up the server in the registry and uses its predefined settings (transport, permissions, environment variables, etc.)
-
From a container image:
$ thv run ghcr.io/example/mcp-server:latest [-- args...]Runs the specified container image directly with the provided arguments
-
Using a protocol scheme:
$ thv run uvx://package-name [-- args...] $ thv run npx://package-name [-- args...] $ thv run go://package-name [-- args...] $ thv run go://./local-path [-- args...]Automatically generates a container that runs the specified package using either uvx (Python with uv package manager), npx (Node.js), or go (Golang). For Go, you can also specify local paths starting with './' or '../' to build and run local Go projects.
-
From an exported configuration:
$ thv run --from-config <path>Runs an MCP server using a previously exported configuration file.
-
Remote MCP server:
$ thv run <URL> [--name <name>]Runs a remote MCP server as a workload, proxying requests to the specified URL. This allows remote MCP servers to be managed like local workloads with full support for client configuration, tool filtering, import/export, etc.
When no client credentials are provided, ToolHive automatically registers an OAuth client with the authorization server using RFC 7591 dynamic client registration:
- No need to pre-configure client ID and secret
- Automatically discovers registration endpoint via OIDC
- Supports PKCE flow for enhanced security
The container will be started with the specified transport mode and permission profile. Additional configuration can be provided via flags.
You can specify the network mode for the container using the --network flag:
- Host networking: $ thv run --network host
- Custom network: $ thv run --network my-network
- Default (bridge): $ thv run
The --network flag accepts any Docker-compatible network mode.
Examples:
thv run filesystem
thv run github -- --toolsets repos
thv run ghcr.io/github/github-mcp-server
thv run uvx://mcp-server-git
thv run npx://@modelcontextprotocol/server-everything
thv run filesystem --group production
thv run github-remote --remote-auth
--remote-auth-client-id
--remote-auth-client-secret
thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
--audit-config string Path to the audit configuration file
--authz-config string Path to the authorization configuration file
--ca-cert string Path to a custom CA certificate file to use for container builds
--enable-audit Enable audit logging with default configuration (default false)
--endpoint-prefix string Path prefix to prepend to SSE endpoint URLs (e.g., /playwright)
-e, --env stringArray Environment variables to pass to the MCP server (format: KEY=VALUE)
--env-file string Load environment variables from a single file
--env-file-dir string Load environment variables from all files in a directory
-f, --foreground Run in foreground mode (block until container exits) (default false)
--from-config string Load configuration from exported file
--group string Name of the group this workload should belong to (default "default")
-h, --help help for run
--host string Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1")
--ignore-globally Load global ignore patterns from ~/.config/toolhive/thvignore (default true)
--image-verification string Set image verification mode (warn, enabled, disabled) (default "warn")
--isolate-network Isolate the container network from the host (default false)
--jwks-allow-private-ip Allow JWKS/OIDC endpoints on private IP addresses (use with caution) (default false)
--jwks-auth-token-file string Path to file containing bearer token for authenticating JWKS/OIDC requests
-l, --label stringArray Set labels on the container (format: key=value)
--name string Name of the MCP server (default to auto-generated from image)
--network string Connect the container to a network (e.g., 'host' for host networking)
--oidc-audience string Expected audience for the token
--oidc-client-id string OIDC client ID
--oidc-client-secret string OIDC client secret (optional, for introspection)
--oidc-insecure-allow-http Allow HTTP (non-HTTPS) OIDC issuers for local development/testing (WARNING: Insecure!) (default false)
--oidc-introspection-url string URL for token introspection endpoint
--oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com)
--oidc-jwks-url string URL to fetch the JWKS from
--oidc-scopes strings OAuth scopes to advertise in the well-known endpoint (RFC 9728, defaults to 'openid' if not specified)
--otel-custom-attributes string Custom resource attributes for OpenTelemetry in key=value format (e.g., server_type=prod,region=us-east-1,team=platform)
--otel-enable-prometheus-metrics-path Enable Prometheus-style /metrics endpoint on the main transport port (default false)
--otel-endpoint string OpenTelemetry OTLP endpoint URL (e.g., https://api.honeycomb.io)
--otel-env-vars stringArray Environment variable names to include in OpenTelemetry spans (comma-separated: ENV1,ENV2)
--otel-headers stringArray OpenTelemetry OTLP headers in key=value format (e.g., x-honeycomb-team=your-api-key)
--otel-insecure Connect to the OpenTelemetry endpoint using HTTP instead of HTTPS (default false)
--otel-metrics-enabled Enable OTLP metrics export (when OTLP endpoint is configured) (default true)
--otel-sampling-rate float OpenTelemetry trace sampling rate (0.0-1.0) (default 0.1)
--otel-service-name string OpenTelemetry service name (defaults to toolhive-mcp-proxy)
--otel-tracing-enabled Enable distributed tracing (when OTLP endpoint is configured) (default true)
--permission-profile string Permission profile to use (none, network, or path to JSON file) (default is to use the permission profile from the registry or "network" if not part of the registry)
--print-resolved-overlays Debug: show resolved container paths for tmpfs overlays (default false)
--proxy-mode string Proxy mode for stdio (streamable-http or sse (deprecated, will be removed)) (default "streamable-http")
--proxy-port int Port for the HTTP proxy to listen on (host port)
--remote-auth Enable OAuth/OIDC authentication to remote MCP server (default false)
--remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
--remote-auth-bearer-token string Bearer token for remote server authentication (alternative to OAuth)
--remote-auth-bearer-token-file string Path to file containing bearer token (alternative to --remote-auth-bearer-token)
--remote-auth-callback-port int Port for OAuth callback server during remote authentication (default 8666)
--remote-auth-client-id string OAuth client ID for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591))
--remote-auth-client-secret string OAuth client secret for remote server authentication (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE)
--remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret) (optional if the authorization server supports dynamic client registration (RFC 7591) or if using PKCE)
--remote-auth-issuer string OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com)
--remote-auth-resource string OAuth 2.0 resource indicator (RFC 8707)
--remote-auth-scopes strings OAuth scopes to request for remote server authentication (defaults: OIDC uses 'openid,profile,email')
--remote-auth-skip-browser Skip opening browser for remote server OAuth flow (default false)
--remote-auth-timeout duration Timeout for OAuth authentication flow (e.g., 30s, 1m, 2m30s) (default 30s)
--remote-auth-token-url string OAuth token endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
--resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728)
--secret stringArray Specify a secret to be fetched from the secrets manager and set as an environment variable (format: NAME,target=TARGET)
--target-host string Host to forward traffic to (only applicable to SSE or Streamable HTTP transport) (default "127.0.0.1")
--target-port int Port for the container to expose (only applicable to SSE or Streamable HTTP transport)
--thv-ca-bundle string Path to CA certificate bundle for ToolHive HTTP operations (JWKS, OIDC discovery, etc.)
--token-exchange-audience string Target audience for exchanged tokens
--token-exchange-client-id string OAuth client ID for token exchange operations
--token-exchange-client-secret string OAuth client secret for token exchange operations
--token-exchange-client-secret-file string Path to file containing OAuth client secret for token exchange (alternative to --token-exchange-client-secret)
--token-exchange-header-name string Custom header name for injecting exchanged token (default: replaces Authorization header)
--token-exchange-scopes strings Scopes to request for exchanged tokens
--token-exchange-subject-token-type string Type of subject token to exchange. Accepts: access_token (default), id_token (required for Google STS)
--token-exchange-url string OAuth 2.0 token exchange endpoint URL (enables token exchange when provided)
--tools stringArray Filter MCP server tools (comma-separated list of tool names)
--tools-override string Path to a JSON file containing overrides for MCP server tools names and descriptions
--transport string Transport mode (sse, streamable-http or stdio)
--trust-proxy-headers Trust X-Forwarded-* headers from reverse proxies (X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Prefix) (default false)
-v, --volume stringArray Mount a volume into the container (format: host-path:container-path[:ro])
--debug Enable debug mode
- thv - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers