---
title: thv run
hide_title: true
description: Reference for ToolHive CLI command `thv run`
last_update:
  author: autogenerated
slug: thv_run
mdx:
  format: md
---

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

#### Network Configuration

You can specify the network mode for the container using the --network flag:

- Host networking: $ thv run --network host <image>
- Custom network: $ thv run --network my-network <image>
- Default (bridge): $ thv run <image>

The --network flag accepts any Docker-compatible network mode.

Examples:
  # Run a server from the registry
  thv run filesystem

  # Run a server with custom arguments and toolsets
  thv run github -- --toolsets repos

  # Run from a container image
  thv run ghcr.io/github/github-mcp-server

  # Run using a protocol scheme (Python with uv)
  thv run uvx://mcp-server-git

  # Run using npx (Node.js)
  thv run npx://@modelcontextprotocol/server-everything

  # Run a server in a specific group
  thv run filesystem --group production

# Run a remote GitHub MCP server with authentication
thv run github-remote --remote-auth \
  --remote-auth-client-id <oauth-client-id> \
  --remote-auth-client-secret <oauth-client-secret>

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

### Options

```
      --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)
```

### Options inherited from parent commands

```
      --debug   Enable debug mode
```

### SEE ALSO

* [thv](thv.md)	 - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers

