| 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...]
--allow-docker-gateway Allow outbound connections to Docker gateway addresses (host.docker.internal, gateway.docker.internal, 172.17.0.1). Only applies when --isolate-network is set. These are blocked by default even when insecure_allow_all is enabled.
--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 thv-<workload-name>)
--otel-tracing-enabled Enable distributed tracing (when OTLP endpoint is configured) (default true)
--otel-use-legacy-attributes Emit legacy attribute names alongside new OTEL semantic convention names (default true) (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)
-p, --publish stringArray Publish a container's port(s) to the host (format: hostPort:containerPort)
--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-scope-param-name string Override the query parameter name for scopes in the authorization URL (e.g., 'user_scope' for Slack OAuth)
--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)
--remote-forward-headers stringArray Headers to inject into requests to remote MCP server (format: Name=Value, can be repeated)
--remote-forward-headers-secret stringArray Headers with secret values from ToolHive secrets manager (format: Name=secret-name, can be repeated)
--resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728)
--runtime-add-package stringArray Add additional packages to install in the builder and runtime stages (can be repeated)
--runtime-image string Override the default base image for protocol schemes (e.g., golang:1.24-alpine, node:20-alpine, python:3.11-slim)
--secret stringArray Specify a secret to be fetched from the secrets manager and set as an environment variable (format: NAME,target=TARGET)
--stateless Declare the server as stateless (POST-only, no SSE). Use for MCP servers implementing streamable-HTTP stateless mode.
--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])
--webhook-config stringArray Path to webhook configuration file (can be specified multiple times to merge configs)
--debug Enable debug mode
- thv - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers