Skip to content

Commit 60c197d

Browse files
github-actions[bot]github-actions[bot]
authored
Update ToolHive reference docs for v0.2.10 (#130)
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent fb16648 commit 60c197d

File tree

3 files changed

+170
-47
lines changed

3 files changed

+170
-47
lines changed

‎docs/toolhive/reference/cli/thv_proxy.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@ thv proxy [flags] SERVER_NAME
9191
--oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com)
9292
--oidc-jwks-url string URL to fetch the JWKS from
9393
--port int Port for the HTTP proxy to listen on (host port)
94-
--remote-auth Enable OAuth authentication to remote MCP server
94+
--remote-auth Enable OAuth/OIDC authentication to remote MCP server
9595
--remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
96-
--remote-auth-callback-port int Port for OAuth callback server during remote authentication (default: 8666) (default 8666)
96+
--remote-auth-callback-port int Port for OAuth callback server during remote authentication (default 8666)
9797
--remote-auth-client-id string OAuth client ID for remote server authentication
9898
--remote-auth-client-secret string OAuth client secret for remote server authentication (optional for PKCE)
9999
--remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret)

‎docs/toolhive/reference/cli/thv_run.md‎

Lines changed: 64 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Run an MCP server
1717

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

20-
ToolHive supports four ways to run an MCP server:
20+
ToolHive supports five ways to run an MCP server:
2121

2222
1. From the registry:
2323

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

5151
Runs an MCP server using a previously exported configuration file.
5252

53+
5. Remote MCP server:
54+
55+
$ thv run <URL> [--name <name>]
56+
57+
Runs a remote MCP server as a workload, proxying requests to the specified URL.
58+
This allows remote MCP servers to be managed like local workloads with full
59+
support for client configuration, tool filtering, import/export, etc.
60+
5361
The container will be started with the specified transport mode and
5462
permission profile. Additional configuration can be provided via flags.
5563

@@ -60,50 +68,61 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
6068
### Options
6169

6270
```
63-
--audit-config string Path to the audit configuration file
64-
--authz-config string Path to the authorization configuration file
65-
--ca-cert string Path to a custom CA certificate file to use for container builds
66-
--enable-audit Enable audit logging with default configuration
67-
-e, --env stringArray Environment variables to pass to the MCP server (format: KEY=VALUE)
68-
--env-file string Load environment variables from a single file
69-
--env-file-dir string Load environment variables from all files in a directory
70-
-f, --foreground Run in foreground mode (block until container exits)
71-
--from-config string Load configuration from exported file
72-
--group string Name of the group this workload belongs to (defaults to 'default' if not specified) (default "default")
73-
-h, --help help for run
74-
--host string Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1")
75-
--ignore-globally Load global ignore patterns from ~/.config/toolhive/thvignore (default true)
76-
--image-verification string Set image verification mode (warn, enabled, disabled) (default "warn")
77-
--isolate-network Isolate the container network from the host (default: false)
78-
--jwks-allow-private-ip Allow JWKS/OIDC endpoints on private IP addresses (use with caution)
79-
--jwks-auth-token-file string Path to file containing bearer token for authenticating JWKS/OIDC requests
80-
-l, --label stringArray Set labels on the container (format: key=value)
81-
--name string Name of the MCP server (auto-generated from image if not provided)
82-
--oidc-audience string Expected audience for the token
83-
--oidc-client-id string OIDC client ID
84-
--oidc-client-secret string OIDC client secret (optional, for introspection)
85-
--oidc-introspection-url string URL for token introspection endpoint
86-
--oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com)
87-
--oidc-jwks-url string URL to fetch the JWKS from
88-
--otel-enable-prometheus-metrics-path Enable Prometheus-style /metrics endpoint on the main transport port
89-
--otel-endpoint string OpenTelemetry OTLP endpoint URL (e.g., https://api.honeycomb.io)
90-
--otel-env-vars stringArray Environment variable names to include in OpenTelemetry spans (comma-separated: ENV1,ENV2)
91-
--otel-headers stringArray OpenTelemetry OTLP headers in key=value format (e.g., x-honeycomb-team=your-api-key)
92-
--otel-insecure Connect to the OpenTelemetry endpoint using HTTP instead of HTTPS
93-
--otel-sampling-rate float OpenTelemetry trace sampling rate (0.0-1.0) (default 0.1)
94-
--otel-service-name string OpenTelemetry service name (defaults to toolhive-mcp-proxy)
95-
--permission-profile string Permission profile to use (none, network, or path to JSON file)
96-
--print-resolved-overlays Debug: show resolved container paths for tmpfs overlays
97-
--proxy-mode string Proxy mode for stdio transport (sse or streamable-http) (default "sse")
98-
--proxy-port int Port for the HTTP proxy to listen on (host port)
99-
--resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728)
100-
--secret stringArray Specify a secret to be fetched from the secrets manager and set as an environment variable (format: NAME,target=TARGET)
101-
--target-host string Host to forward traffic to (only applicable to SSE or Streamable HTTP transport) (default "127.0.0.1")
102-
--target-port int Port for the container to expose (only applicable to SSE or Streamable HTTP transport)
103-
--thv-ca-bundle string Path to CA certificate bundle for ToolHive HTTP operations (JWKS, OIDC discovery, etc.)
104-
--tools stringArray Filter MCP server tools (comma-separated list of tool names)
105-
--transport string Transport mode (sse, streamable-http or stdio)
106-
-v, --volume stringArray Mount a volume into the container (format: host-path:container-path[:ro])
71+
--audit-config string Path to the audit configuration file
72+
--authz-config string Path to the authorization configuration file
73+
--ca-cert string Path to a custom CA certificate file to use for container builds
74+
--enable-audit Enable audit logging with default configuration
75+
-e, --env stringArray Environment variables to pass to the MCP server (format: KEY=VALUE)
76+
--env-file string Load environment variables from a single file
77+
--env-file-dir string Load environment variables from all files in a directory
78+
-f, --foreground Run in foreground mode (block until container exits)
79+
--from-config string Load configuration from exported file
80+
--group string Name of the group this workload belongs to (defaults to 'default' if not specified) (default "default")
81+
-h, --help help for run
82+
--host string Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1")
83+
--ignore-globally Load global ignore patterns from ~/.config/toolhive/thvignore (default true)
84+
--image-verification string Set image verification mode (warn, enabled, disabled) (default "warn")
85+
--isolate-network Isolate the container network from the host (default: false)
86+
--jwks-allow-private-ip Allow JWKS/OIDC endpoints on private IP addresses (use with caution)
87+
--jwks-auth-token-file string Path to file containing bearer token for authenticating JWKS/OIDC requests
88+
-l, --label stringArray Set labels on the container (format: key=value)
89+
--name string Name of the MCP server (auto-generated from image if not provided)
90+
--oidc-audience string Expected audience for the token
91+
--oidc-client-id string OIDC client ID
92+
--oidc-client-secret string OIDC client secret (optional, for introspection)
93+
--oidc-introspection-url string URL for token introspection endpoint
94+
--oidc-issuer string OIDC issuer URL (e.g., https://accounts.google.com)
95+
--oidc-jwks-url string URL to fetch the JWKS from
96+
--otel-enable-prometheus-metrics-path Enable Prometheus-style /metrics endpoint on the main transport port
97+
--otel-endpoint string OpenTelemetry OTLP endpoint URL (e.g., https://api.honeycomb.io)
98+
--otel-env-vars stringArray Environment variable names to include in OpenTelemetry spans (comma-separated: ENV1,ENV2)
99+
--otel-headers stringArray OpenTelemetry OTLP headers in key=value format (e.g., x-honeycomb-team=your-api-key)
100+
--otel-insecure Connect to the OpenTelemetry endpoint using HTTP instead of HTTPS
101+
--otel-sampling-rate float OpenTelemetry trace sampling rate (0.0-1.0) (default 0.1)
102+
--otel-service-name string OpenTelemetry service name (defaults to toolhive-mcp-proxy)
103+
--permission-profile string Permission profile to use (none, network, or path to JSON file)
104+
--print-resolved-overlays Debug: show resolved container paths for tmpfs overlays
105+
--proxy-mode string Proxy mode for stdio transport (sse or streamable-http) (default "sse")
106+
--proxy-port int Port for the HTTP proxy to listen on (host port)
107+
--remote-auth Enable OAuth/OIDC authentication to remote MCP server
108+
--remote-auth-authorize-url string OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
109+
--remote-auth-callback-port int Port for OAuth callback server during remote authentication (default 8666)
110+
--remote-auth-client-id string OAuth client ID for remote server authentication
111+
--remote-auth-client-secret string OAuth client secret for remote server authentication (optional for PKCE)
112+
--remote-auth-client-secret-file string Path to file containing OAuth client secret (alternative to --remote-auth-client-secret)
113+
--remote-auth-issuer string OAuth/OIDC issuer URL for remote server authentication (e.g., https://accounts.google.com)
114+
--remote-auth-scopes strings OAuth scopes to request for remote server authentication (defaults: OIDC uses 'openid,profile,email')
115+
--remote-auth-skip-browser Skip opening browser for remote server OAuth flow
116+
--remote-auth-timeout duration Timeout for OAuth authentication flow (e.g., 30s, 1m, 2m30s) (default 30s)
117+
--remote-auth-token-url string OAuth token endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)
118+
--resource-url string Explicit resource URL for OAuth discovery endpoint (RFC 9728)
119+
--secret stringArray Specify a secret to be fetched from the secrets manager and set as an environment variable (format: NAME,target=TARGET)
120+
--target-host string Host to forward traffic to (only applicable to SSE or Streamable HTTP transport) (default "127.0.0.1")
121+
--target-port int Port for the container to expose (only applicable to SSE or Streamable HTTP transport)
122+
--thv-ca-bundle string Path to CA certificate bundle for ToolHive HTTP operations (JWKS, OIDC discovery, etc.)
123+
--tools stringArray Filter MCP server tools (comma-separated list of tool names)
124+
--transport string Transport mode (sse, streamable-http or stdio)
125+
-v, --volume stringArray Mount a volume into the container (format: host-path:container-path[:ro])
107126
```
108127

109128
### Options inherited from parent commands

‎static/api-specs/toolhive-api.yaml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -459,6 +459,11 @@ components:
459459
AuthorizeURL is the OAuth authorization endpoint URL
460460
Used for non-OIDC OAuth flows when issuer is not provided
461461
type: string
462+
callback_port:
463+
description: |-
464+
CallbackPort is the specific port to use for the OAuth callback server
465+
If not specified, a random available port will be used
466+
type: integer
462467
client_id:
463468
description: ClientID is the OAuth client ID for authentication
464469
type: string
@@ -467,6 +472,13 @@ components:
467472
Issuer is the OAuth/OIDC issuer URL (e.g., https://accounts.google.com)
468473
Used for OIDC discovery to find authorization and token endpoints
469474
type: string
475+
oauth_params:
476+
additionalProperties:
477+
type: string
478+
description: |-
479+
OAuthParams contains additional OAuth parameters to include in the authorization request
480+
These are server-specific parameters like "prompt", "response_mode", etc.
481+
type: object
470482
scopes:
471483
description: |-
472484
Scopes are the OAuth scopes to request
@@ -605,6 +617,51 @@ components:
605617
predicate_type:
606618
type: string
607619
type: object
620+
runner.RemoteAuthConfig:
621+
description: RemoteAuthConfig contains OAuth configuration for remote MCP servers
622+
properties:
623+
authorizeURL:
624+
type: string
625+
callbackPort:
626+
type: integer
627+
clientID:
628+
type: string
629+
clientSecret:
630+
type: string
631+
clientSecretFile:
632+
type: string
633+
enableRemoteAuth:
634+
type: boolean
635+
envVars:
636+
description: Environment variables for the client
637+
items:
638+
$ref: '#/components/schemas/registry.EnvVar'
639+
type: array
640+
headers:
641+
description: Headers for HTTP requests
642+
items:
643+
$ref: '#/components/schemas/registry.Header'
644+
type: array
645+
issuer:
646+
description: OAuth endpoint configuration (from registry)
647+
type: string
648+
oauthParams:
649+
additionalProperties:
650+
type: string
651+
description: OAuth parameters for server-specific customization
652+
type: object
653+
scopes:
654+
items:
655+
type: string
656+
type: array
657+
skipBrowser:
658+
type: boolean
659+
timeout:
660+
example: 5m
661+
type: string
662+
tokenURL:
663+
type: string
664+
type: object
608665
runner.RunConfig:
609666
properties:
610667
audit_config:
@@ -692,6 +749,11 @@ components:
692749
type: integer
693750
proxy_mode:
694751
$ref: '#/components/schemas/types.ProxyMode'
752+
remote_auth_config:
753+
$ref: '#/components/schemas/runner.RemoteAuthConfig'
754+
remote_url:
755+
description: RemoteURL is the URL of the remote MCP server (if running remotely)
756+
type: string
695757
schema_version:
696758
description: SchemaVersion is the version of the RunConfig schema
697759
type: string
@@ -1342,6 +1404,22 @@ components:
13421404
type: array
13431405
uniqueItems: false
13441406
type: object
1407+
v1.workloadStatusResponse:
1408+
description: Response containing workload status information
1409+
properties:
1410+
status:
1411+
description: Current status of the workload
1412+
type: string
1413+
x-enum-varnames:
1414+
- WorkloadStatusRunning
1415+
- WorkloadStatusStopped
1416+
- WorkloadStatusError
1417+
- WorkloadStatusStarting
1418+
- WorkloadStatusStopping
1419+
- WorkloadStatusUnhealthy
1420+
- WorkloadStatusRemoving
1421+
- WorkloadStatusUnknown
1422+
type: object
13451423
externalDocs:
13461424
description: ""
13471425
url: ""
@@ -2309,6 +2387,32 @@ paths:
23092387
summary: Restart a workload
23102388
tags:
23112389
- workloads
2390+
/api/v1beta/workloads/{name}/status:
2391+
get:
2392+
description: Get the current status of a specific workload
2393+
parameters:
2394+
- description: Workload name
2395+
in: path
2396+
name: name
2397+
required: true
2398+
schema:
2399+
type: string
2400+
responses:
2401+
"200":
2402+
content:
2403+
application/json:
2404+
schema:
2405+
$ref: '#/components/schemas/v1.workloadStatusResponse'
2406+
description: OK
2407+
"404":
2408+
content:
2409+
application/json:
2410+
schema:
2411+
type: string
2412+
description: Not Found
2413+
summary: Get workload status
2414+
tags:
2415+
- workloads
23122416
/api/v1beta/workloads/{name}/stop:
23132417
post:
23142418
description: Stop a running workload

0 commit comments

Comments
 (0)