diff --git a/docs/toolhive/reference/cli/thv_proxy.md b/docs/toolhive/reference/cli/thv_proxy.md index cd38f232..1a393721 100644 --- a/docs/toolhive/reference/cli/thv_proxy.md +++ b/docs/toolhive/reference/cli/thv_proxy.md @@ -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) diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index f0532d38..5f06f510 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -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: @@ -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 [--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. @@ -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 diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 6ec8e3ed..e637ea8d 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -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 @@ -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 @@ -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: @@ -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 @@ -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: "" @@ -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