Skip to main content

thv_run

thv run​

Run an MCP server

Synopsis​

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

ToolHive supports three 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.

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​

      --authz-config string         Path to the authorization configuration file
      --ca-cert string              Path to a custom CA certificate file to use for container builds
  -e, --env stringArray             Environment variables to pass to the MCP server (format: KEY=VALUE)
  -f, --foreground                  Run in foreground mode (block until container exits)
  -h, --help                        help for run
      --host string                 Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1")
      --image-verification string   Set image verification mode (warn, enabled, disabled) (default "warn")
      --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-issuer string          OIDC issuer URL (e.g., https://accounts.google.com)
      --oidc-jwks-url string        URL to fetch the JWKS from
      --permission-profile string   Permission profile to use (none, network, or path to JSON file) (default "network")
      --port int                    Port for the HTTP proxy to listen on (host port)
      --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 transport) (default "127.0.0.1")
      --target-port int             Port for the container to expose (only applicable to SSE transport)
      --transport string            Transport mode (sse or stdio) (default "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