diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md index 5bbfa186..ec51ae8d 100644 --- a/docs/toolhive/reference/cli/thv.md +++ b/docs/toolhive/reference/cli/thv.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv` last_update: author: autogenerated slug: thv +mdx: + format: md --- ## thv @@ -35,6 +37,7 @@ thv [flags] * [thv client](thv_client.md) - Manage MCP clients * [thv config](thv_config.md) - Manage application configuration +* [thv export](thv_export.md) - Export a workload's run configuration to a file * [thv inspector](thv_inspector.md) - Launches the MCP Inspector UI and connects it to the specified MCP server * [thv list](thv_list.md) - List running MCP servers * [thv logs](thv_logs.md) - Output the logs of an MCP server or manage log files @@ -44,6 +47,8 @@ thv [flags] * [thv restart](thv_restart.md) - Restart a tooling server * [thv rm](thv_rm.md) - Remove an MCP server * [thv run](thv_run.md) - Run an MCP server +* [thv runtime](thv_runtime.md) - Commands related to the container runtime +* [thv runtime](thv_runtime.md) - Commands related to the container runtime * [thv search](thv_search.md) - Search for MCP servers * [thv secret](thv_secret.md) - Manage secrets * [thv serve](thv_serve.md) - Start the ToolHive API server diff --git a/docs/toolhive/reference/cli/thv_client.md b/docs/toolhive/reference/cli/thv_client.md index f6985605..6271d798 100644 --- a/docs/toolhive/reference/cli/thv_client.md +++ b/docs/toolhive/reference/cli/thv_client.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv client` last_update: author: autogenerated slug: thv_client +mdx: + format: md --- ## thv client diff --git a/docs/toolhive/reference/cli/thv_client_list-registered.md b/docs/toolhive/reference/cli/thv_client_list-registered.md index 15b55cf7..af3eb3af 100644 --- a/docs/toolhive/reference/cli/thv_client_list-registered.md +++ b/docs/toolhive/reference/cli/thv_client_list-registered.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv client list-registered` last_update: author: autogenerated slug: thv_client_list-registered +mdx: + format: md --- ## thv client list-registered diff --git a/docs/toolhive/reference/cli/thv_client_register.md b/docs/toolhive/reference/cli/thv_client_register.md index f83e5c50..aeccb9a3 100644 --- a/docs/toolhive/reference/cli/thv_client_register.md +++ b/docs/toolhive/reference/cli/thv_client_register.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv client register` last_update: author: autogenerated slug: thv_client_register +mdx: + format: md --- ## thv client register @@ -14,13 +16,16 @@ Register a client for MCP server configuration ### Synopsis Register a client for MCP server configuration. -Valid clients are: + +Valid clients: - claude-code: Claude Code CLI - cline: Cline extension for VS Code - cursor: Cursor editor - roo-code: Roo Code extension for VS Code - vscode: Visual Studio Code - vscode-insider: Visual Studio Code Insiders edition + - windsurf: Windsurf IDE + - windsurf-jetbrains: Windsurf for JetBrains IDEs ``` thv client register [client] [flags] diff --git a/docs/toolhive/reference/cli/thv_client_remove.md b/docs/toolhive/reference/cli/thv_client_remove.md index ee7391d1..7fb7e9bc 100644 --- a/docs/toolhive/reference/cli/thv_client_remove.md +++ b/docs/toolhive/reference/cli/thv_client_remove.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv client remove` last_update: author: autogenerated slug: thv_client_remove +mdx: + format: md --- ## thv client remove @@ -14,13 +16,16 @@ Remove a client from MCP server configuration ### Synopsis Remove a client from MCP server configuration. -Valid clients are: + +Valid clients: - claude-code: Claude Code CLI - cline: Cline extension for VS Code - cursor: Cursor editor - roo-code: Roo Code extension for VS Code - vscode: Visual Studio Code - vscode-insider: Visual Studio Code Insiders edition + - windsurf: Windsurf IDE + - windsurf-jetbrains: Windsurf for JetBrains IDEs ``` thv client remove [client] [flags] diff --git a/docs/toolhive/reference/cli/thv_client_setup.md b/docs/toolhive/reference/cli/thv_client_setup.md index 5b990a49..09b6ed3f 100644 --- a/docs/toolhive/reference/cli/thv_client_setup.md +++ b/docs/toolhive/reference/cli/thv_client_setup.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv client setup` last_update: author: autogenerated slug: thv_client_setup +mdx: + format: md --- ## thv client setup diff --git a/docs/toolhive/reference/cli/thv_client_status.md b/docs/toolhive/reference/cli/thv_client_status.md index b6b5f3c1..730afbb1 100644 --- a/docs/toolhive/reference/cli/thv_client_status.md +++ b/docs/toolhive/reference/cli/thv_client_status.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv client status` last_update: author: autogenerated slug: thv_client_status +mdx: + format: md --- ## thv client status diff --git a/docs/toolhive/reference/cli/thv_config.md b/docs/toolhive/reference/cli/thv_config.md index 82eac9a1..a8c7388f 100644 --- a/docs/toolhive/reference/cli/thv_config.md +++ b/docs/toolhive/reference/cli/thv_config.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config` last_update: author: autogenerated slug: thv_config +mdx: + format: md --- ## thv config diff --git a/docs/toolhive/reference/cli/thv_config_get-ca-cert.md b/docs/toolhive/reference/cli/thv_config_get-ca-cert.md index 437a588e..755e519e 100644 --- a/docs/toolhive/reference/cli/thv_config_get-ca-cert.md +++ b/docs/toolhive/reference/cli/thv_config_get-ca-cert.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config get-ca-cert` last_update: author: autogenerated slug: thv_config_get-ca-cert +mdx: + format: md --- ## thv config get-ca-cert diff --git a/docs/toolhive/reference/cli/thv_config_get-registry-url.md b/docs/toolhive/reference/cli/thv_config_get-registry-url.md index 4d324732..72b187fc 100644 --- a/docs/toolhive/reference/cli/thv_config_get-registry-url.md +++ b/docs/toolhive/reference/cli/thv_config_get-registry-url.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config get-registry-url` last_update: author: autogenerated slug: thv_config_get-registry-url +mdx: + format: md --- ## thv config get-registry-url diff --git a/docs/toolhive/reference/cli/thv_config_otel.md b/docs/toolhive/reference/cli/thv_config_otel.md index 3f4264cd..bd991240 100644 --- a/docs/toolhive/reference/cli/thv_config_otel.md +++ b/docs/toolhive/reference/cli/thv_config_otel.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel` last_update: author: autogenerated slug: thv_config_otel +mdx: + format: md --- ## thv config otel diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-endpoint.md b/docs/toolhive/reference/cli/thv_config_otel_get-endpoint.md index 36aab7b8..f3d4f7ad 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_get-endpoint.md +++ b/docs/toolhive/reference/cli/thv_config_otel_get-endpoint.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel get-endpoint` last_update: author: autogenerated slug: thv_config_otel_get-endpoint +mdx: + format: md --- ## thv config otel get-endpoint diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-env-vars.md b/docs/toolhive/reference/cli/thv_config_otel_get-env-vars.md index b8a87d20..bfb107e3 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_get-env-vars.md +++ b/docs/toolhive/reference/cli/thv_config_otel_get-env-vars.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel get-env-vars` last_update: author: autogenerated slug: thv_config_otel_get-env-vars +mdx: + format: md --- ## thv config otel get-env-vars diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-sampling-rate.md b/docs/toolhive/reference/cli/thv_config_otel_get-sampling-rate.md index ab81a6b4..adc9b44d 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_get-sampling-rate.md +++ b/docs/toolhive/reference/cli/thv_config_otel_get-sampling-rate.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel get-sampling-ra last_update: author: autogenerated slug: thv_config_otel_get-sampling-rate +mdx: + format: md --- ## thv config otel get-sampling-rate diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-endpoint.md b/docs/toolhive/reference/cli/thv_config_otel_set-endpoint.md index c4e79725..49cf5a4e 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_set-endpoint.md +++ b/docs/toolhive/reference/cli/thv_config_otel_set-endpoint.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel set-endpoint` last_update: author: autogenerated slug: thv_config_otel_set-endpoint +mdx: + format: md --- ## thv config otel set-endpoint @@ -14,10 +16,12 @@ Set the OpenTelemetry endpoint URL ### Synopsis Set the OpenTelemetry OTLP endpoint URL for tracing and metrics. + This endpoint will be used by default when running MCP servers unless overridden by the --otel-endpoint flag. Example: - thv config otel set-endpoint https://api.honeycomb.io + + thv config otel set-endpoint https://api.honeycomb.io ``` thv config otel set-endpoint [flags] diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-env-vars.md b/docs/toolhive/reference/cli/thv_config_otel_set-env-vars.md index 867d59bc..cc84588a 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_set-env-vars.md +++ b/docs/toolhive/reference/cli/thv_config_otel_set-env-vars.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel set-env-vars` last_update: author: autogenerated slug: thv_config_otel_set-env-vars +mdx: + format: md --- ## thv config otel set-env-vars @@ -14,10 +16,12 @@ Set the OpenTelemetry environment variables ### Synopsis Set the list of environment variable names to include in OpenTelemetry spans. + These environment variables will be used by default when running MCP servers unless overridden by the --otel-env-vars flag. Example: - thv config otel set-env-vars USER,HOME,PATH + + thv config otel set-env-vars USER,HOME,PATH ``` thv config otel set-env-vars [flags] diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-sampling-rate.md b/docs/toolhive/reference/cli/thv_config_otel_set-sampling-rate.md index dfd4f4ee..f8a73471 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_set-sampling-rate.md +++ b/docs/toolhive/reference/cli/thv_config_otel_set-sampling-rate.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel set-sampling-ra last_update: author: autogenerated slug: thv_config_otel_set-sampling-rate +mdx: + format: md --- ## thv config otel set-sampling-rate @@ -14,10 +16,12 @@ Set the OpenTelemetry sampling rate ### Synopsis Set the OpenTelemetry trace sampling rate (between 0.0 and 1.0). + This sampling rate will be used by default when running MCP servers unless overridden by the --otel-sampling-rate flag. Example: - thv config otel set-sampling-rate 0.1 + + thv config otel set-sampling-rate 0.1 ``` thv config otel set-sampling-rate [flags] diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-endpoint.md b/docs/toolhive/reference/cli/thv_config_otel_unset-endpoint.md index e84f1418..391a64de 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_unset-endpoint.md +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-endpoint.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel unset-endpoint` last_update: author: autogenerated slug: thv_config_otel_unset-endpoint +mdx: + format: md --- ## thv config otel unset-endpoint diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-env-vars.md b/docs/toolhive/reference/cli/thv_config_otel_unset-env-vars.md index a3a2cddf..561a52f5 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_unset-env-vars.md +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-env-vars.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel unset-env-vars` last_update: author: autogenerated slug: thv_config_otel_unset-env-vars +mdx: + format: md --- ## thv config otel unset-env-vars diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-sampling-rate.md b/docs/toolhive/reference/cli/thv_config_otel_unset-sampling-rate.md index f182610f..56de17cf 100644 --- a/docs/toolhive/reference/cli/thv_config_otel_unset-sampling-rate.md +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-sampling-rate.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config otel unset-sampling- last_update: author: autogenerated slug: thv_config_otel_unset-sampling-rate +mdx: + format: md --- ## thv config otel unset-sampling-rate diff --git a/docs/toolhive/reference/cli/thv_config_set-ca-cert.md b/docs/toolhive/reference/cli/thv_config_set-ca-cert.md index b606bb58..9985113f 100644 --- a/docs/toolhive/reference/cli/thv_config_set-ca-cert.md +++ b/docs/toolhive/reference/cli/thv_config_set-ca-cert.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config set-ca-cert` last_update: author: autogenerated slug: thv_config_set-ca-cert +mdx: + format: md --- ## thv config set-ca-cert diff --git a/docs/toolhive/reference/cli/thv_config_set-registry-url.md b/docs/toolhive/reference/cli/thv_config_set-registry-url.md index 629457a3..d56f819f 100644 --- a/docs/toolhive/reference/cli/thv_config_set-registry-url.md +++ b/docs/toolhive/reference/cli/thv_config_set-registry-url.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config set-registry-url` last_update: author: autogenerated slug: thv_config_set-registry-url +mdx: + format: md --- ## thv config set-registry-url diff --git a/docs/toolhive/reference/cli/thv_config_unset-ca-cert.md b/docs/toolhive/reference/cli/thv_config_unset-ca-cert.md index e89a5597..40a9c787 100644 --- a/docs/toolhive/reference/cli/thv_config_unset-ca-cert.md +++ b/docs/toolhive/reference/cli/thv_config_unset-ca-cert.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config unset-ca-cert` last_update: author: autogenerated slug: thv_config_unset-ca-cert +mdx: + format: md --- ## thv config unset-ca-cert diff --git a/docs/toolhive/reference/cli/thv_config_unset-registry-url.md b/docs/toolhive/reference/cli/thv_config_unset-registry-url.md index b8ffc353..4a4668ea 100644 --- a/docs/toolhive/reference/cli/thv_config_unset-registry-url.md +++ b/docs/toolhive/reference/cli/thv_config_unset-registry-url.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv config unset-registry-url` last_update: author: autogenerated slug: thv_config_unset-registry-url +mdx: + format: md --- ## thv config unset-registry-url diff --git a/docs/toolhive/reference/cli/thv_export.md b/docs/toolhive/reference/cli/thv_export.md new file mode 100644 index 00000000..ff9a2d70 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_export.md @@ -0,0 +1,50 @@ +--- +title: thv export +hide_title: true +description: Reference for ToolHive CLI command `thv export` +last_update: + author: autogenerated +slug: thv_export +mdx: + format: md +--- + +## thv export + +Export a workload's run configuration to a file + +### Synopsis + +Export a workload's run configuration to a file for sharing or backup. + +The exported configuration can be used with 'thv run --from-config ' to recreate +the same workload with identical settings. + +Examples: + + # Export a workload configuration to a file + thv export my-server ./my-server-config.json + + # Export to a specific directory + thv export github-mcp /tmp/configs/github-config.json + +``` +thv export [flags] +``` + +### Options + +``` + -h, --help help for export +``` + +### 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 + diff --git a/docs/toolhive/reference/cli/thv_inspector.md b/docs/toolhive/reference/cli/thv_inspector.md index 1f0fdc29..660af6ab 100644 --- a/docs/toolhive/reference/cli/thv_inspector.md +++ b/docs/toolhive/reference/cli/thv_inspector.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv inspector` last_update: author: autogenerated slug: thv_inspector +mdx: + format: md --- ## thv inspector diff --git a/docs/toolhive/reference/cli/thv_list.md b/docs/toolhive/reference/cli/thv_list.md index 99d2a814..d76ac61a 100644 --- a/docs/toolhive/reference/cli/thv_list.md +++ b/docs/toolhive/reference/cli/thv_list.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv list` last_update: author: autogenerated slug: thv_list +mdx: + format: md --- ## thv list diff --git a/docs/toolhive/reference/cli/thv_logs.md b/docs/toolhive/reference/cli/thv_logs.md index 674d7a8d..f6ae1f0e 100644 --- a/docs/toolhive/reference/cli/thv_logs.md +++ b/docs/toolhive/reference/cli/thv_logs.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv logs` last_update: author: autogenerated slug: thv_logs +mdx: + format: md --- ## thv logs diff --git a/docs/toolhive/reference/cli/thv_logs_prune.md b/docs/toolhive/reference/cli/thv_logs_prune.md index b0cb45ef..93a5dc36 100644 --- a/docs/toolhive/reference/cli/thv_logs_prune.md +++ b/docs/toolhive/reference/cli/thv_logs_prune.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv logs prune` last_update: author: autogenerated slug: thv_logs_prune +mdx: + format: md --- ## thv logs prune diff --git a/docs/toolhive/reference/cli/thv_mcp.md b/docs/toolhive/reference/cli/thv_mcp.md index fdd3db85..d2c6b5b1 100644 --- a/docs/toolhive/reference/cli/thv_mcp.md +++ b/docs/toolhive/reference/cli/thv_mcp.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv mcp` last_update: author: autogenerated slug: thv_mcp +mdx: + format: md --- ## thv mcp diff --git a/docs/toolhive/reference/cli/thv_mcp_list.md b/docs/toolhive/reference/cli/thv_mcp_list.md index fc4619c3..43db120b 100644 --- a/docs/toolhive/reference/cli/thv_mcp_list.md +++ b/docs/toolhive/reference/cli/thv_mcp_list.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv mcp list` last_update: author: autogenerated slug: thv_mcp_list +mdx: + format: md --- ## thv mcp list @@ -26,6 +28,7 @@ thv mcp list [tools|resources|prompts] [flags] -h, --help help for list --server string MCP server URL (required) --timeout duration Connection timeout (default 30s) + --transport string Transport type (auto, sse, streamable-http) (default "auto") ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_mcp_list_prompts.md b/docs/toolhive/reference/cli/thv_mcp_list_prompts.md index 39426177..2d762fc1 100644 --- a/docs/toolhive/reference/cli/thv_mcp_list_prompts.md +++ b/docs/toolhive/reference/cli/thv_mcp_list_prompts.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv mcp list prompts` last_update: author: autogenerated slug: thv_mcp_list_prompts +mdx: + format: md --- ## thv mcp list prompts @@ -26,6 +28,7 @@ thv mcp list prompts [flags] -h, --help help for prompts --server string MCP server URL (required) --timeout duration Connection timeout (default 30s) + --transport string Transport type (auto, sse, streamable-http) (default "auto") ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_mcp_list_resources.md b/docs/toolhive/reference/cli/thv_mcp_list_resources.md index ebb2f8c2..14ebee0c 100644 --- a/docs/toolhive/reference/cli/thv_mcp_list_resources.md +++ b/docs/toolhive/reference/cli/thv_mcp_list_resources.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv mcp list resources` last_update: author: autogenerated slug: thv_mcp_list_resources +mdx: + format: md --- ## thv mcp list resources @@ -26,6 +28,7 @@ thv mcp list resources [flags] -h, --help help for resources --server string MCP server URL (required) --timeout duration Connection timeout (default 30s) + --transport string Transport type (auto, sse, streamable-http) (default "auto") ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_mcp_list_tools.md b/docs/toolhive/reference/cli/thv_mcp_list_tools.md index c1772a70..5227aebb 100644 --- a/docs/toolhive/reference/cli/thv_mcp_list_tools.md +++ b/docs/toolhive/reference/cli/thv_mcp_list_tools.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv mcp list tools` last_update: author: autogenerated slug: thv_mcp_list_tools +mdx: + format: md --- ## thv mcp list tools @@ -26,6 +28,7 @@ thv mcp list tools [flags] -h, --help help for tools --server string MCP server URL (required) --timeout duration Connection timeout (default 30s) + --transport string Transport type (auto, sse, streamable-http) (default "auto") ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_proxy.md b/docs/toolhive/reference/cli/thv_proxy.md index b5dcbba4..2bd0d446 100644 --- a/docs/toolhive/reference/cli/thv_proxy.md +++ b/docs/toolhive/reference/cli/thv_proxy.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv proxy` last_update: author: autogenerated slug: thv_proxy +mdx: + format: md --- ## thv proxy @@ -14,15 +16,17 @@ Create a transparent proxy for an MCP server with authentication support ### Synopsis Create a transparent HTTP proxy that forwards requests to an MCP server endpoint. + This command starts a standalone proxy without creating a workload, providing: -• Transparent request forwarding to the target MCP server -• Optional OAuth/OIDC authentication to remote MCP servers -• Automatic authentication detection via WWW-Authenticate headers -• OIDC-based access control for incoming proxy requests -• Secure credential handling via files or environment variables +- Transparent request forwarding to the target MCP server +- Optional OAuth/OIDC authentication to remote MCP servers +- Automatic authentication detection via WWW-Authenticate headers +- OIDC-based access control for incoming proxy requests +- Secure credential handling via files or environment variables + +#### Authentication modes -AUTHENTICATION MODES: The proxy supports multiple authentication scenarios: 1. No Authentication: Simple transparent forwarding @@ -30,30 +34,37 @@ The proxy supports multiple authentication scenarios: 3. Incoming Authentication: Protect the proxy endpoint with OIDC validation 4. Bidirectional: Both incoming and outgoing authentication -OAUTH CLIENT SECRET SOURCES: +#### OAuth client secret sources + OAuth client secrets can be provided via (in order of precedence): + 1. --remote-auth-client-secret flag (not recommended for production) 2. --remote-auth-client-secret-file flag (secure file-based approach) 3. TOOLHIVE_REMOTE_OAUTH_CLIENT_SECRET environment variable -EXAMPLES: - # Basic transparent proxy - thv proxy my-server --target-uri http://localhost:8080 +#### Examples + +Basic transparent proxy: + + thv proxy my-server --target-uri http://localhost:8080 + +Proxy with OAuth authentication to remote server: + + thv proxy my-server --target-uri https://api.example.com \ + --remote-auth --remote-auth-issuer https://auth.example.com \ + --remote-auth-client-id my-client-id \ + --remote-auth-client-secret-file /path/to/secret + +Proxy with OIDC protection for incoming requests: - # Proxy with OAuth authentication to remote server - thv proxy my-server --target-uri https://api.example.com \ - --remote-auth --remote-auth-issuer https://auth.example.com \ - --remote-auth-client-id my-client-id \ - --remote-auth-client-secret-file /path/to/secret + thv proxy my-server --target-uri http://localhost:8080 \ + --oidc-issuer https://auth.example.com \ + --oidc-audience my-audience - # Proxy with OIDC protection for incoming requests - thv proxy my-server --target-uri http://localhost:8080 \ - --oidc-issuer https://auth.example.com \ - --oidc-audience my-audience +Auto-detect authentication requirements: - # Auto-detect authentication requirements - thv proxy my-server --target-uri https://protected-api.com \ - --remote-auth-client-id my-client-id + thv proxy my-server --target-uri https://protected-api.com \ + --remote-auth-client-id my-client-id ``` thv proxy [flags] SERVER_NAME diff --git a/docs/toolhive/reference/cli/thv_registry.md b/docs/toolhive/reference/cli/thv_registry.md index 63e78457..c0283add 100644 --- a/docs/toolhive/reference/cli/thv_registry.md +++ b/docs/toolhive/reference/cli/thv_registry.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv registry` last_update: author: autogenerated slug: thv_registry +mdx: + format: md --- ## thv registry diff --git a/docs/toolhive/reference/cli/thv_registry_info.md b/docs/toolhive/reference/cli/thv_registry_info.md index 276ae38a..cb50bd2d 100644 --- a/docs/toolhive/reference/cli/thv_registry_info.md +++ b/docs/toolhive/reference/cli/thv_registry_info.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv registry info` last_update: author: autogenerated slug: thv_registry_info +mdx: + format: md --- ## thv registry info diff --git a/docs/toolhive/reference/cli/thv_registry_list.md b/docs/toolhive/reference/cli/thv_registry_list.md index a085aca1..a2f9dfe2 100644 --- a/docs/toolhive/reference/cli/thv_registry_list.md +++ b/docs/toolhive/reference/cli/thv_registry_list.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv registry list` last_update: author: autogenerated slug: thv_registry_list +mdx: + format: md --- ## thv registry list diff --git a/docs/toolhive/reference/cli/thv_restart.md b/docs/toolhive/reference/cli/thv_restart.md index 64ca80c9..c2c42804 100644 --- a/docs/toolhive/reference/cli/thv_restart.md +++ b/docs/toolhive/reference/cli/thv_restart.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv restart` last_update: author: autogenerated slug: thv_restart +mdx: + format: md --- ## thv restart diff --git a/docs/toolhive/reference/cli/thv_rm.md b/docs/toolhive/reference/cli/thv_rm.md index 620d3ae5..9db5b43c 100644 --- a/docs/toolhive/reference/cli/thv_rm.md +++ b/docs/toolhive/reference/cli/thv_rm.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv rm` last_update: author: autogenerated slug: thv_rm +mdx: + format: md --- ## thv rm diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index efbb7bbf..89e1ecec 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv run` last_update: author: autogenerated slug: thv_run +mdx: + format: md --- ## thv run @@ -15,27 +17,39 @@ Run an MCP server Run an MCP server with the specified name, image, or protocol scheme. -ToolHive supports three ways to run an MCP server: +ToolHive supports four ways to run an MCP server: 1. From the registry: - $ thv run server-name [-- args...] + + $ 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...] + + $ 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...] + + $ 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 + + Runs an MCP server using a previously exported configuration file. + The container will be started with the specified transport mode and permission profile. Additional configuration can be provided via flags. @@ -52,8 +66,10 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --enable-audit Enable audit logging with default configuration -e, --env stringArray Environment variables to pass to the MCP server (format: KEY=VALUE) -f, --foreground Run in foreground mode (block until container exits) + --from-config string Load configuration from exported file -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) @@ -73,12 +89,14 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --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) --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]) ``` diff --git a/docs/toolhive/reference/cli/thv_runtime.md b/docs/toolhive/reference/cli/thv_runtime.md new file mode 100644 index 00000000..059143ba --- /dev/null +++ b/docs/toolhive/reference/cli/thv_runtime.md @@ -0,0 +1,33 @@ +--- +title: thv runtime +hide_title: true +description: Reference for ToolHive CLI command `thv runtime` +last_update: + author: autogenerated +slug: thv_runtime +mdx: + format: md +--- + +## thv runtime + +Commands related to the container runtime + +### Options + +``` + -h, --help help for runtime +``` + +### 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 +* [thv runtime check](thv_runtime_check.md) - Ping the container runtime +* [thv runtime check](thv_runtime_check.md) - Ping the container runtime + diff --git a/docs/toolhive/reference/cli/thv_runtime_check.md b/docs/toolhive/reference/cli/thv_runtime_check.md new file mode 100644 index 00000000..6bfc6c22 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_runtime_check.md @@ -0,0 +1,40 @@ +--- +title: thv runtime check +hide_title: true +description: Reference for ToolHive CLI command `thv runtime check` +last_update: + author: autogenerated +slug: thv_runtime_check +mdx: + format: md +--- + +## thv runtime check + +Ping the container runtime + +### Synopsis + +Ensure the container runtime is responsive. + +``` +thv runtime check [flags] +``` + +### Options + +``` + -h, --help help for check + --timeout int Timeout in seconds for runtime checks (default: 30 seconds) (default 30) +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv runtime](thv_runtime.md) - Commands related to the container runtime + diff --git a/docs/toolhive/reference/cli/thv_search.md b/docs/toolhive/reference/cli/thv_search.md index 4a2a71d7..047969bc 100644 --- a/docs/toolhive/reference/cli/thv_search.md +++ b/docs/toolhive/reference/cli/thv_search.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv search` last_update: author: autogenerated slug: thv_search +mdx: + format: md --- ## thv search diff --git a/docs/toolhive/reference/cli/thv_secret.md b/docs/toolhive/reference/cli/thv_secret.md index 739f30d9..a98c1675 100644 --- a/docs/toolhive/reference/cli/thv_secret.md +++ b/docs/toolhive/reference/cli/thv_secret.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv secret` last_update: author: autogenerated slug: thv_secret +mdx: + format: md --- ## thv secret @@ -13,7 +15,11 @@ Manage secrets ### Synopsis -The secret command provides subcommands to set, get, delete, and list secrets. +Manage secrets using the configured secrets provider. + +The secret command provides subcommands to configure, store, retrieve, and manage secrets securely. + +Run "thv secret setup" first to configure a secrets provider before using any secret operations. ### Options @@ -33,8 +39,8 @@ The secret command provides subcommands to set, get, delete, and list secrets. * [thv secret delete](thv_secret_delete.md) - Delete a secret * [thv secret get](thv_secret_get.md) - Get a secret * [thv secret list](thv_secret_list.md) - List all available secrets -* [thv secret provider](thv_secret_provider.md) - Configure the secrets provider directly -* [thv secret reset-keyring](thv_secret_reset-keyring.md) - Reset the keyring secret +* [thv secret provider](thv_secret_provider.md) - Set the secrets provider directly +* [thv secret reset-keyring](thv_secret_reset-keyring.md) - Reset the keyring password * [thv secret set](thv_secret_set.md) - Set a secret * [thv secret setup](thv_secret_setup.md) - Set up secrets provider diff --git a/docs/toolhive/reference/cli/thv_secret_delete.md b/docs/toolhive/reference/cli/thv_secret_delete.md index 205d6085..2296ae67 100644 --- a/docs/toolhive/reference/cli/thv_secret_delete.md +++ b/docs/toolhive/reference/cli/thv_secret_delete.md @@ -5,12 +5,24 @@ description: Reference for ToolHive CLI command `thv secret delete` last_update: author: autogenerated slug: thv_secret_delete +mdx: + format: md --- ## thv secret delete Delete a secret +### Synopsis + +Remove a secret from the configured secrets provider. + +This command permanently deletes the specified secret from your secrets provider. +Once you delete a secret, you cannot recover it unless you have a backup. + +Note that some secrets providers may not support deletion operations. +If your provider is read-only or doesn't support deletion, this command returns an error. + ``` thv secret delete [flags] ``` diff --git a/docs/toolhive/reference/cli/thv_secret_get.md b/docs/toolhive/reference/cli/thv_secret_get.md index d1c4f8bc..1a2f1f81 100644 --- a/docs/toolhive/reference/cli/thv_secret_get.md +++ b/docs/toolhive/reference/cli/thv_secret_get.md @@ -5,12 +5,24 @@ description: Reference for ToolHive CLI command `thv secret get` last_update: author: autogenerated slug: thv_secret_get +mdx: + format: md --- ## thv secret get Get a secret +### Synopsis + +Retrieve and display the value of a secret by name. + +This command fetches the specified secret from your configured secrets provider +and displays its value. The secret value prints to stdout, making it +suitable for use in scripts or command substitution. + +The secret must exist in your configured secrets provider, otherwise the command returns an error. + ``` thv secret get [flags] ``` diff --git a/docs/toolhive/reference/cli/thv_secret_list.md b/docs/toolhive/reference/cli/thv_secret_list.md index 68b659fe..8ffefa0c 100644 --- a/docs/toolhive/reference/cli/thv_secret_list.md +++ b/docs/toolhive/reference/cli/thv_secret_list.md @@ -5,12 +5,21 @@ description: Reference for ToolHive CLI command `thv secret list` last_update: author: autogenerated slug: thv_secret_list +mdx: + format: md --- ## thv secret list List all available secrets +### Synopsis + +Display all secrets available in the configured secrets provider. + +This command shows the names of all secrets stored in your secrets provider. +If descriptions exist for the secrets, the command displays them alongside the names. + ``` thv secret list [flags] ``` diff --git a/docs/toolhive/reference/cli/thv_secret_provider.md b/docs/toolhive/reference/cli/thv_secret_provider.md index fdfbe8d6..868617ca 100644 --- a/docs/toolhive/reference/cli/thv_secret_provider.md +++ b/docs/toolhive/reference/cli/thv_secret_provider.md @@ -5,19 +5,27 @@ description: Reference for ToolHive CLI command `thv secret provider` last_update: author: autogenerated slug: thv_secret_provider +mdx: + format: md --- ## thv secret provider -Configure the secrets provider directly +Set the secrets provider directly ### Synopsis -For most users, it is recommended to use "thv secret setup" instead. -Configure the secrets provider. -Valid secrets providers are: - - encrypted: Full read-write secrets provider - - 1password: Read-only secrets provider +Configure the secrets provider directly. + +Note: The "thv secret setup" command is recommended for interactive configuration. + +Use this command to set the secrets provider directly without interactive prompts, +making it suitable for scripted deployments and automation. + +Valid secrets providers: + - encrypted: Full read-write secrets provider using AES-256-GCM encryption + - 1password: Read-only secrets provider (requires OP_SERVICE_ACCOUNT_TOKEN) + - none: Disables secrets functionality ``` thv secret provider [flags] diff --git a/docs/toolhive/reference/cli/thv_secret_reset-keyring.md b/docs/toolhive/reference/cli/thv_secret_reset-keyring.md index 8389864e..7116d801 100644 --- a/docs/toolhive/reference/cli/thv_secret_reset-keyring.md +++ b/docs/toolhive/reference/cli/thv_secret_reset-keyring.md @@ -5,11 +5,31 @@ description: Reference for ToolHive CLI command `thv secret reset-keyring` last_update: author: autogenerated slug: thv_secret_reset-keyring +mdx: + format: md --- ## thv secret reset-keyring -Reset the keyring secret +Reset the keyring password + +### Synopsis + +Reset the keyring password used to encrypt secrets. + +This command resets the master password stored in your OS keyring that +encrypts and decrypts secrets when using the 'encrypted' secrets provider. + +Use this command if: + - You've forgotten your keyring password + - You want to change your encryption password + - Your keyring has become corrupted + +Warning: Resetting the keyring password makes any existing encrypted secrets +inaccessible unless you remember the previous password. You will need to set up +your secrets again after resetting. + +This command only works with the 'encrypted' secrets provider. ``` thv secret reset-keyring [flags] diff --git a/docs/toolhive/reference/cli/thv_secret_set.md b/docs/toolhive/reference/cli/thv_secret_set.md index 1cead135..1d839f76 100644 --- a/docs/toolhive/reference/cli/thv_secret_set.md +++ b/docs/toolhive/reference/cli/thv_secret_set.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv secret set` last_update: author: autogenerated slug: thv_secret_set +mdx: + format: md --- ## thv secret set @@ -13,21 +15,29 @@ Set a secret ### Synopsis -Set a secret with the given name. - -Input Methods: - - Piped Input: If data is piped to the command, the secret value will be read from stdin. - Examples: - echo "my-secret-value" | thv secret set my-secret - cat secret-file.txt | thv secret set my-secret - - - Interactive Input: If no data is piped, you will be prompted to enter the secret value securely - (input will be hidden). - Example: - thv secret set my-secret - Enter secret value (input will be hidden): _ - -The secret will be stored securely using the configured secrets provider. +Create or update a secret with the specified name. + +This command supports two input methods for maximum flexibility: + +Piped input: + +When you pipe data to the command, it reads the secret value from stdin. +Examples: + + $ echo "my-secret-value" | thv secret set my-secret + $ cat secret-file.txt | thv secret set my-secret + +Interactive input: + +When you don't pipe data, the command prompts you to enter the secret value securely. +The input remains hidden for security. +Example: + + $ thv secret set my-secret + Enter secret value (input will be hidden): _ + +The command stores the secret securely using your configured secrets provider. +Note that some providers (like 1Password) are read-only and do not support setting secrets. ``` thv secret set [flags] diff --git a/docs/toolhive/reference/cli/thv_secret_setup.md b/docs/toolhive/reference/cli/thv_secret_setup.md index 8b0d0e9a..b51fc81d 100644 --- a/docs/toolhive/reference/cli/thv_secret_setup.md +++ b/docs/toolhive/reference/cli/thv_secret_setup.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv secret setup` last_update: author: autogenerated slug: thv_secret_setup +mdx: + format: md --- ## thv secret setup @@ -14,15 +16,17 @@ Set up secrets provider ### Synopsis Interactive setup for configuring a secrets provider. -This command will guide you through selecting and configuring -a secrets provider for storing and retrieving secrets. + +This command guides you through selecting and configuring a secrets provider +for storing and retrieving secrets. The setup process validates your +configuration and ensures the selected provider initializes properly. Available providers: - - encrypted: Stores secrets in an encrypted file using AES-256-GCM using the OS Keyring - - 1password: Read-only access to 1Password secrets (requires OP_SERVICE_ACCOUNT_TOKEN) + - encrypted: Stores secrets in an encrypted file using AES-256-GCM using the OS keyring + - 1password: Read-only access to 1Password secrets (requires OP_SERVICE_ACCOUNT_TOKEN environment variable) - none: Disables secrets functionality -You must run this command before using any other secrets functionality. +Run this command before using any other secrets functionality. ``` thv secret setup [flags] diff --git a/docs/toolhive/reference/cli/thv_serve.md b/docs/toolhive/reference/cli/thv_serve.md index a09a8236..ef0d525e 100644 --- a/docs/toolhive/reference/cli/thv_serve.md +++ b/docs/toolhive/reference/cli/thv_serve.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv serve` last_update: author: autogenerated slug: thv_serve +mdx: + format: md --- ## thv serve diff --git a/docs/toolhive/reference/cli/thv_stop.md b/docs/toolhive/reference/cli/thv_stop.md index b488384e..93b7ad35 100644 --- a/docs/toolhive/reference/cli/thv_stop.md +++ b/docs/toolhive/reference/cli/thv_stop.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv stop` last_update: author: autogenerated slug: thv_stop +mdx: + format: md --- ## thv stop diff --git a/docs/toolhive/reference/cli/thv_version.md b/docs/toolhive/reference/cli/thv_version.md index 01b65a0d..9640c8a3 100644 --- a/docs/toolhive/reference/cli/thv_version.md +++ b/docs/toolhive/reference/cli/thv_version.md @@ -5,6 +5,8 @@ description: Reference for ToolHive CLI command `thv version` last_update: author: autogenerated slug: thv_version +mdx: + format: md --- ## thv version diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 8041d1bf..ce52beae 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -1,5 +1,105 @@ components: schemas: + audit.Config: + description: AuditConfig contains the audit logging configuration + properties: + component: + description: Component is the component name to use in audit events + type: string + event_types: + description: EventTypes specifies which event types to audit. If empty, + all events are audited. + items: + type: string + type: array + uniqueItems: false + exclude_event_types: + description: |- + ExcludeEventTypes specifies which event types to exclude from auditing. + This takes precedence over EventTypes. + items: + type: string + type: array + uniqueItems: false + include_request_data: + description: IncludeRequestData determines whether to include request data + in audit logs + type: boolean + include_response_data: + description: IncludeResponseData determines whether to include response + data in audit logs + type: boolean + log_file: + description: LogFile specifies the file path for audit logs. If empty, logs + to stdout. + type: string + max_data_size: + description: MaxDataSize limits the size of request/response data included + in audit logs (in bytes) + type: integer + type: object + auth.TokenValidatorConfig: + description: OIDCConfig contains OIDC configuration + properties: + allowOpaqueTokens: + description: AllowOpaqueTokens indicates whether to allow opaque tokens + (non-JWT) + type: boolean + allowPrivateIP: + description: AllowPrivateIP allows JWKS/OIDC endpoints on private IP addresses + type: boolean + audience: + description: Audience is the expected audience for the token + type: string + authTokenFile: + description: AuthTokenFile is the path to file containing bearer token for + authentication + type: string + cacertPath: + description: CACertPath is the path to the CA certificate bundle for HTTPS + requests + type: string + clientID: + description: ClientID is the OIDC client ID + type: string + issuer: + description: Issuer is the OIDC issuer URL (e.g., https://accounts.google.com) + type: string + jwksurl: + description: JWKSURL is the URL to fetch the JWKS from + type: string + type: object + authz.CedarConfig: + description: |- + Cedar is the Cedar-specific configuration. + This is only used when Type is ConfigTypeCedarV1. + properties: + entities_json: + description: EntitiesJSON is the JSON string representing Cedar entities + type: string + policies: + description: Policies is a list of Cedar policy strings + items: + type: string + type: array + uniqueItems: false + type: object + authz.Config: + description: AuthzConfig contains the authorization configuration + properties: + cedar: + $ref: '#/components/schemas/authz.CedarConfig' + type: + $ref: '#/components/schemas/authz.ConfigType' + version: + description: Version is the version of the configuration format. + type: string + type: object + authz.ConfigType: + description: Type is the type of authorization configuration. + type: string + x-enum-varnames: + - ConfigTypeCedarV1 client.Client: properties: name: @@ -14,6 +114,8 @@ components: - VSCodeInsider - VSCode - ClaudeCode + - Windsurf + - WindsurfJetBrains client.MCPClientStatus: properties: client_type: @@ -26,6 +128,8 @@ components: - VSCodeInsider - VSCode - ClaudeCode + - Windsurf + - WindsurfJetBrains installed: description: Installed indicates whether the client is installed on the system @@ -35,6 +139,16 @@ components: ToolHive configuration type: boolean type: object + ignore.Config: + description: IgnoreConfig contains configuration for ignore processing + properties: + loadGlobal: + description: Whether to load global ignore patterns + type: boolean + printOverlays: + description: Whether to print resolved overlay paths for debugging + type: boolean + type: object permissions.NetworkPermissions: description: Network defines network permissions properties: @@ -61,7 +175,7 @@ components: type: boolean type: object permissions.Profile: - description: Permission profile to apply + description: PermissionProfile is the permission profile to use properties: name: description: Name is the name of the profile @@ -251,6 +365,146 @@ components: predicate_type: type: string type: object + runner.RunConfig: + properties: + audit_config: + $ref: '#/components/schemas/audit.Config' + audit_config_path: + description: AuditConfigPath is the path to the audit configuration file + type: string + authz_config: + $ref: '#/components/schemas/authz.Config' + authz_config_path: + description: AuthzConfigPath is the path to the authorization configuration + file + type: string + base_name: + description: BaseName is the base name used for the container (without prefixes) + type: string + cmd_args: + description: CmdArgs are the arguments to pass to the container + items: + type: string + type: array + uniqueItems: false + container_labels: + additionalProperties: + type: string + description: ContainerLabels are the labels to apply to the container + type: object + container_name: + description: ContainerName is the name of the container + type: string + debug: + description: Debug indicates whether debug mode is enabled + type: boolean + env_vars: + additionalProperties: + type: string + description: EnvVars are the parsed environment variables as key-value pairs + type: object + group: + description: Group is the name of the group this workload belongs to, if + any + type: string + host: + description: Host is the host for the HTTP proxy + type: string + ignore_config: + $ref: '#/components/schemas/ignore.Config' + image: + description: Image is the Docker image to run + type: string + isolate_network: + description: IsolateNetwork indicates whether to isolate the network for + the container + type: boolean + jwks_allow_private_ip: + description: JWKSAllowPrivateIP allows JWKS/OIDC endpoints on private IP + addresses + type: boolean + jwks_auth_token_file: + description: JWKSAuthTokenFile is the path to file containing auth token + for JWKS/OIDC requests + type: string + k8s_pod_template_patch: + description: |- + K8sPodTemplatePatch is a JSON string to patch the Kubernetes pod template + Only applicable when using Kubernetes runtime + type: string + name: + description: Name is the name of the MCP server + type: string + oidc_config: + $ref: '#/components/schemas/auth.TokenValidatorConfig' + permission_profile: + $ref: '#/components/schemas/permissions.Profile' + permission_profile_name_or_path: + description: PermissionProfileNameOrPath is the name or path of the permission + profile + type: string + port: + description: Port is the port for the HTTP proxy to listen on (host port) + type: integer + proxy_mode: + $ref: '#/components/schemas/types.ProxyMode' + secrets: + description: |- + Secrets are the secret parameters to pass to the container + Format: ",target=" + items: + type: string + type: array + uniqueItems: false + target_host: + description: TargetHost is the host to forward traffic to (only applicable + to SSE transport) + type: string + target_port: + description: TargetPort is the port for the container to expose (only applicable + to SSE transport) + type: integer + telemetry_config: + $ref: '#/components/schemas/telemetry.Config' + thv_ca_bundle: + description: ThvCABundle is the path to the CA certificate bundle for ToolHive + HTTP operations + type: string + tools_filter: + description: ToolsFilter is the list of tools to filter + items: + type: string + type: array + uniqueItems: false + transport: + description: Transport is the transport mode (stdio, sse, or streamable-http) + type: string + x-enum-varnames: + - TransportTypeStdio + - TransportTypeSSE + - TransportTypeStreamableHTTP + - TransportTypeInspector + volumes: + description: |- + Volumes are the directory mounts to pass to the container + Format: "host-path:container-path[:ro]" + items: + type: string + type: array + uniqueItems: false + type: object + runtime.WorkloadStatus: + description: Status is the current status of the workload. + type: string + x-enum-varnames: + - WorkloadStatusRunning + - WorkloadStatusStopped + - WorkloadStatusError + - WorkloadStatusStarting + - WorkloadStatusStopping + - WorkloadStatusUnhealthy + - WorkloadStatusRemoving + - WorkloadStatusUnknown secrets.SecretParameter: properties: name: @@ -258,6 +512,52 @@ components: target: type: string type: object + telemetry.Config: + description: TelemetryConfig contains the OpenTelemetry configuration + properties: + enablePrometheusMetricsPath: + description: |- + EnablePrometheusMetricsPath controls whether to expose Prometheus-style /metrics endpoint + The metrics are served on the main transport port at /metrics + This is separate from OTLP metrics which are sent to the Endpoint + type: boolean + endpoint: + description: Endpoint is the OTLP endpoint URL + type: string + environmentVariables: + description: |- + EnvironmentVariables is a list of environment variable names that should be + included in telemetry spans as attributes. Only variables in this list will + be read from the host machine and included in spans for observability. + Example: []string{"NODE_ENV", "DEPLOYMENT_ENV", "SERVICE_VERSION"} + items: + type: string + type: array + headers: + additionalProperties: + type: string + description: Headers contains authentication headers for the OTLP endpoint + type: object + insecure: + description: Insecure indicates whether to use HTTP instead of HTTPS for + the OTLP endpoint + type: boolean + samplingRate: + description: SamplingRate is the trace sampling rate (0.0-1.0) + type: number + serviceName: + description: ServiceName is the service name for telemetry + type: string + serviceVersion: + description: ServiceVersion is the service version for telemetry + type: string + type: object + types.ProxyMode: + description: ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http") + type: string + x-enum-varnames: + - ProxyModeSSE + - ProxyModeStreamableHTTP types.TransportType: description: TransportType is the type of transport used for this workload. type: string @@ -279,6 +579,8 @@ components: - VSCodeInsider - VSCode - ClaudeCode + - Windsurf + - WindsurfJetBrains type: array uniqueItems: false type: object @@ -312,6 +614,8 @@ components: - VSCodeInsider - VSCode - ClaudeCode + - Windsurf + - WindsurfJetBrains type: object v1.createClientResponse: properties: @@ -325,6 +629,8 @@ components: - VSCodeInsider - VSCode - ClaudeCode + - Windsurf + - WindsurfJetBrains type: object v1.createRequest: description: Request to create a new workload @@ -373,6 +679,12 @@ components: target_port: description: Port to expose from the container type: integer + tools: + description: Tools filter + items: + type: string + type: array + uniqueItems: false transport: description: Transport configuration type: string @@ -602,6 +914,10 @@ components: created_at: description: CreatedAt is the timestamp when the workload was created. type: string + group: + description: Group is the name of the group this workload belongs to, if + any. + type: string labels: additionalProperties: type: string @@ -623,7 +939,7 @@ components: This is embedded in the URL. type: integer status: - $ref: '#/components/schemas/workloads.WorkloadStatus' + $ref: '#/components/schemas/runtime.WorkloadStatus' status_context: description: |- StatusContext provides additional context about the workload's status. @@ -634,24 +950,18 @@ components: ToolType is the type of tool this workload represents. For now, it will always be "mcp" - representing an MCP server. type: string + tools: + description: ToolsFilter is the filter on tools applied to the workload. + items: + type: string + type: array + uniqueItems: false transport_type: $ref: '#/components/schemas/types.TransportType' url: description: URL is the URL of the workload exposed by the ToolHive proxy. type: string type: object - workloads.WorkloadStatus: - description: Status is the current status of the workload. - type: string - x-enum-varnames: - - WorkloadStatusRunning - - WorkloadStatusStopped - - WorkloadStatusError - - WorkloadStatusStarting - - WorkloadStatusStopping - - WorkloadStatusUnhealthy - - WorkloadStatusRemoving - - WorkloadStatusUnknown externalDocs: description: "" url: "" @@ -1285,6 +1595,32 @@ paths: summary: Get workload details tags: - workloads + /api/v1beta/workloads/{name}/export: + get: + description: Export a workload's run configuration as JSON + parameters: + - description: Workload name + in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/runner.RunConfig' + description: OK + "404": + content: + application/json: + schema: + type: string + description: Not Found + summary: Export workload configuration + tags: + - workloads /api/v1beta/workloads/{name}/logs: get: description: Retrieve at most 100 lines of logs for a specific workload by name.