thv run

Run an MCP server

Synopsis

Run an MCP server with the specified name, image, or protocol scheme.

ToolHive supports five ways to run an MCP server:

1. 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.)

2. From a container image:

   $ thv run ghcr.io/example/mcp-server:latest [-- args...]

   Runs the specified container image directly with the provided arguments

3. 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.

4. From an exported configuration:

   $ thv run --from-config <path>

   Runs an MCP server using a previously exported configuration file.

5. 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.

Dynamic client registration

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.

thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]

Options

      --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
  -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)
      --from-config string                      Load configuration from exported file
      --group string                            Name of the group this workload belongs to (defaults to 'default' if not specified) (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)
      --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 (auto-generated from image if not provided)
      --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-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
      --otel-enable-prometheus-metrics-path     Enable Prometheus-style /metrics endpoint on the main transport port
      --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
      --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)
      --print-resolved-overlays                 Debug: show resolved container paths for tmpfs overlays
      --proxy-mode string                       Proxy mode for stdio transport (sse or streamable-http) (default "sse")
      --proxy-port int                          Port for the HTTP proxy to listen on (host port)
      --remote-auth                             Enable OAuth/OIDC authentication to remote MCP server
      --remote-auth-authorize-url string        OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
      --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
      --remote-auth-client-secret string        OAuth client secret for remote server authentication (optional for PKCE)
      --remote-auth-client-secret-file string   Path to file containing OAuth client secret (alternative to --remote-auth-client-secret)
      --remote-auth-issuer string               OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com)
      --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
      --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.)
      --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)
  -v, --volume stringArray                      Mount a volume into the container (format: host-path:container-path[:ro])

Options inherited from parent commands

      --debug   Enable debug mode

SEE ALSO

• thv - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers