Skip to content

Update ToolHive reference docs for v0.2.10 #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 21, 2025
Merged

Update ToolHive reference docs for v0.2.10 #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv_proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,9 +91,9 @@ thv proxy [flags] SERVER_NAME
--oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com)
--oidc-jwks-url string URL to fetch the JWKS from
--port int Port for the HTTP proxy to listen on (host port)
--remote-auth Enable OAuth authentication to remote MCP server
--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) (default 8666)
--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)
Expand Down
109 changes: 64 additions & 45 deletions docs/toolhive/reference/cli/thv_run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Run an MCP server

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

ToolHive supports four ways to run an MCP server:
ToolHive supports five ways to run an MCP server:

1. From the registry:

Expand Down Expand Up @@ -50,6 +50,14 @@ ToolHive supports four ways to run an MCP server:

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.

The container will be started with the specified transport mode and
permission profile. Additional configuration can be provided via flags.

Expand All @@ -60,50 +68,61 @@ 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-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)
--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)
--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)
--transport string Transport mode (sse, streamable-http or stdio)
-v, --volume stringArray Mount a volume into the container (format: host-path:container-path[:ro])
--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-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)
--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)
--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
Expand Down
104 changes: 104 additions & 0 deletions static/api-specs/toolhive-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,6 +459,11 @@ components:
AuthorizeURL is the OAuth authorization endpoint URL
Used for non-OIDC OAuth flows when issuer is not provided
type: string
callback_port:
description: |-
CallbackPort is the specific port to use for the OAuth callback server
If not specified, a random available port will be used
type: integer
client_id:
description: ClientID is the OAuth client ID for authentication
type: string
Expand All @@ -467,6 +472,13 @@ components:
Issuer is the OAuth/OIDC issuer URL (e.g., https://accounts.google.com)
Used for OIDC discovery to find authorization and token endpoints
type: string
oauth_params:
additionalProperties:
type: string
description: |-
OAuthParams contains additional OAuth parameters to include in the authorization request
These are server-specific parameters like "prompt", "response_mode", etc.
type: object
scopes:
description: |-
Scopes are the OAuth scopes to request
Expand Down Expand Up @@ -605,6 +617,51 @@ components:
predicate_type:
type: string
type: object
runner.RemoteAuthConfig:
description: RemoteAuthConfig contains OAuth configuration for remote MCP servers
properties:
authorizeURL:
type: string
callbackPort:
type: integer
clientID:
type: string
clientSecret:
type: string
clientSecretFile:
type: string
enableRemoteAuth:
type: boolean
envVars:
description: Environment variables for the client
items:
$ref: '#/components/schemas/registry.EnvVar'
type: array
headers:
description: Headers for HTTP requests
items:
$ref: '#/components/schemas/registry.Header'
type: array
issuer:
description: OAuth endpoint configuration (from registry)
type: string
oauthParams:
additionalProperties:
type: string
description: OAuth parameters for server-specific customization
type: object
scopes:
items:
type: string
type: array
skipBrowser:
type: boolean
timeout:
example: 5m
type: string
tokenURL:
type: string
type: object
runner.RunConfig:
properties:
audit_config:
Expand Down Expand Up @@ -692,6 +749,11 @@ components:
type: integer
proxy_mode:
$ref: '#/components/schemas/types.ProxyMode'
remote_auth_config:
$ref: '#/components/schemas/runner.RemoteAuthConfig'
remote_url:
description: RemoteURL is the URL of the remote MCP server (if running remotely)
type: string
schema_version:
description: SchemaVersion is the version of the RunConfig schema
type: string
Expand Down Expand Up @@ -1342,6 +1404,22 @@ components:
type: array
uniqueItems: false
type: object
v1.workloadStatusResponse:
description: Response containing workload status information
properties:
status:
description: Current status of the workload
type: string
x-enum-varnames:
- WorkloadStatusRunning
- WorkloadStatusStopped
- WorkloadStatusError
- WorkloadStatusStarting
- WorkloadStatusStopping
- WorkloadStatusUnhealthy
- WorkloadStatusRemoving
- WorkloadStatusUnknown
type: object
externalDocs:
description: ""
url: ""
Expand Down Expand Up @@ -2309,6 +2387,32 @@ paths:
summary: Restart a workload
tags:
- workloads
/api/v1beta/workloads/{name}/status:
get:
description: Get the current status of a specific workload
parameters:
- description: Workload name
in: path
name: name
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/v1.workloadStatusResponse'
description: OK
"404":
content:
application/json:
schema:
type: string
description: Not Found
summary: Get workload status
tags:
- workloads
/api/v1beta/workloads/{name}/stop:
post:
description: Stop a running workload
Expand Down