diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md index 63a7174d..60b33bc2 100644 --- a/docs/toolhive/reference/cli/thv.md +++ b/docs/toolhive/reference/cli/thv.md @@ -18,7 +18,7 @@ ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers ToolHive (thv) is a lightweight, secure, and fast manager for MCP (Model Context Protocol) servers. It is written in Go and has extensive test coverage—including input validation—to ensure reliability and security. -Under the hood, ToolHive acts as a very thin client for the Docker/Podman/Colima Unix socket API. +Under the hood, ToolHive acts as a very thin client for the Docker/Podman Unix socket API. This design choice allows it to remain both efficient and lightweight while still providing powerful, container-based isolation for running MCP servers. diff --git a/docs/toolhive/reference/cli/thv_config_otel.md b/docs/toolhive/reference/cli/thv_config_otel.md index bd991240..24781da3 100644 --- a/docs/toolhive/reference/cli/thv_config_otel.md +++ b/docs/toolhive/reference/cli/thv_config_otel.md @@ -32,13 +32,25 @@ Configure OpenTelemetry settings for observability and monitoring of MCP servers ### SEE ALSO * [thv config](thv_config.md) - Manage application configuration +* [thv config otel get-enable-prometheus-metrics-path](thv_config_otel_get-enable-prometheus-metrics-path.md) - Get the currently configured OpenTelemetry Prometheus metrics path flag * [thv config otel get-endpoint](thv_config_otel_get-endpoint.md) - Get the currently configured OpenTelemetry endpoint * [thv config otel get-env-vars](thv_config_otel_get-env-vars.md) - Get the currently configured OpenTelemetry environment variables +* [thv config otel get-insecure](thv_config_otel_get-insecure.md) - Get the currently configured OpenTelemetry insecure transport flag +* [thv config otel get-metrics-enabled](thv_config_otel_get-metrics-enabled.md) - Get the currently configured OpenTelemetry metrics export flag * [thv config otel get-sampling-rate](thv_config_otel_get-sampling-rate.md) - Get the currently configured OpenTelemetry sampling rate +* [thv config otel get-tracing-enabled](thv_config_otel_get-tracing-enabled.md) - Get the currently configured OpenTelemetry tracing export flag +* [thv config otel set-enable-prometheus-metrics-path](thv_config_otel_set-enable-prometheus-metrics-path.md) - Set the OpenTelemetry Prometheus metrics path flag * [thv config otel set-endpoint](thv_config_otel_set-endpoint.md) - Set the OpenTelemetry endpoint URL * [thv config otel set-env-vars](thv_config_otel_set-env-vars.md) - Set the OpenTelemetry environment variables +* [thv config otel set-insecure](thv_config_otel_set-insecure.md) - Set the OpenTelemetry insecure transport flag +* [thv config otel set-metrics-enabled](thv_config_otel_set-metrics-enabled.md) - Set the OpenTelemetry metrics export to enabled * [thv config otel set-sampling-rate](thv_config_otel_set-sampling-rate.md) - Set the OpenTelemetry sampling rate +* [thv config otel set-tracing-enabled](thv_config_otel_set-tracing-enabled.md) - Set the OpenTelemetry tracing export to enabled +* [thv config otel unset-enable-prometheus-metrics-path](thv_config_otel_unset-enable-prometheus-metrics-path.md) - Remove the configured OpenTelemetry Prometheus metrics path flag * [thv config otel unset-endpoint](thv_config_otel_unset-endpoint.md) - Remove the configured OpenTelemetry endpoint * [thv config otel unset-env-vars](thv_config_otel_unset-env-vars.md) - Remove the configured OpenTelemetry environment variables +* [thv config otel unset-insecure](thv_config_otel_unset-insecure.md) - Remove the configured OpenTelemetry insecure transport flag +* [thv config otel unset-metrics-enabled](thv_config_otel_unset-metrics-enabled.md) - Remove the configured OpenTelemetry metrics export flag * [thv config otel unset-sampling-rate](thv_config_otel_unset-sampling-rate.md) - Remove the configured OpenTelemetry sampling rate +* [thv config otel unset-tracing-enabled](thv_config_otel_unset-tracing-enabled.md) - Remove the configured OpenTelemetry tracing export flag diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-enable-prometheus-metrics-path.md b/docs/toolhive/reference/cli/thv_config_otel_get-enable-prometheus-metrics-path.md new file mode 100644 index 00000000..7930a07f --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_get-enable-prometheus-metrics-path.md @@ -0,0 +1,39 @@ +--- +title: thv config otel get-enable-prometheus-metrics-path +hide_title: true +description: Reference for ToolHive CLI command `thv config otel get-enable-prometheus-metrics-path` +last_update: + author: autogenerated +slug: thv_config_otel_get-enable-prometheus-metrics-path +mdx: + format: md +--- + +## thv config otel get-enable-prometheus-metrics-path + +Get the currently configured OpenTelemetry Prometheus metrics path flag + +### Synopsis + +Display the OpenTelemetry Prometheus metrics path flag that is currently configured. + +``` +thv config otel get-enable-prometheus-metrics-path [flags] +``` + +### Options + +``` + -h, --help help for get-enable-prometheus-metrics-path +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-insecure.md b/docs/toolhive/reference/cli/thv_config_otel_get-insecure.md new file mode 100644 index 00000000..bea3eea3 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_get-insecure.md @@ -0,0 +1,39 @@ +--- +title: thv config otel get-insecure +hide_title: true +description: Reference for ToolHive CLI command `thv config otel get-insecure` +last_update: + author: autogenerated +slug: thv_config_otel_get-insecure +mdx: + format: md +--- + +## thv config otel get-insecure + +Get the currently configured OpenTelemetry insecure transport flag + +### Synopsis + +Display the OpenTelemetry insecure transport flag that is currently configured. + +``` +thv config otel get-insecure [flags] +``` + +### Options + +``` + -h, --help help for get-insecure +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-metrics-enabled.md b/docs/toolhive/reference/cli/thv_config_otel_get-metrics-enabled.md new file mode 100644 index 00000000..656d463a --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_get-metrics-enabled.md @@ -0,0 +1,39 @@ +--- +title: thv config otel get-metrics-enabled +hide_title: true +description: Reference for ToolHive CLI command `thv config otel get-metrics-enabled` +last_update: + author: autogenerated +slug: thv_config_otel_get-metrics-enabled +mdx: + format: md +--- + +## thv config otel get-metrics-enabled + +Get the currently configured OpenTelemetry metrics export flag + +### Synopsis + +Display the OpenTelemetry metrics export flag that is currently configured. + +``` +thv config otel get-metrics-enabled [flags] +``` + +### Options + +``` + -h, --help help for get-metrics-enabled +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_get-tracing-enabled.md b/docs/toolhive/reference/cli/thv_config_otel_get-tracing-enabled.md new file mode 100644 index 00000000..d817f26d --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_get-tracing-enabled.md @@ -0,0 +1,39 @@ +--- +title: thv config otel get-tracing-enabled +hide_title: true +description: Reference for ToolHive CLI command `thv config otel get-tracing-enabled` +last_update: + author: autogenerated +slug: thv_config_otel_get-tracing-enabled +mdx: + format: md +--- + +## thv config otel get-tracing-enabled + +Get the currently configured OpenTelemetry tracing export flag + +### Synopsis + +Display the OpenTelemetry tracing export flag that is currently configured. + +``` +thv config otel get-tracing-enabled [flags] +``` + +### Options + +``` + -h, --help help for get-tracing-enabled +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-enable-prometheus-metrics-path.md b/docs/toolhive/reference/cli/thv_config_otel_set-enable-prometheus-metrics-path.md new file mode 100644 index 00000000..189ecf5a --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_set-enable-prometheus-metrics-path.md @@ -0,0 +1,41 @@ +--- +title: thv config otel set-enable-prometheus-metrics-path +hide_title: true +description: Reference for ToolHive CLI command `thv config otel set-enable-prometheus-metrics-path` +last_update: + author: autogenerated +slug: thv_config_otel_set-enable-prometheus-metrics-path +mdx: + format: md +--- + +## thv config otel set-enable-prometheus-metrics-path + +Set the OpenTelemetry Prometheus metrics path flag + +### Synopsis + +Set the OpenTelemetry Prometheus metrics path flag to enable /metrics endpoint. + + thv config otel set-enable-prometheus-metrics-path true + +``` +thv config otel set-enable-prometheus-metrics-path [flags] +``` + +### Options + +``` + -h, --help help for set-enable-prometheus-metrics-path +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-insecure.md b/docs/toolhive/reference/cli/thv_config_otel_set-insecure.md new file mode 100644 index 00000000..d60d698c --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_set-insecure.md @@ -0,0 +1,41 @@ +--- +title: thv config otel set-insecure +hide_title: true +description: Reference for ToolHive CLI command `thv config otel set-insecure` +last_update: + author: autogenerated +slug: thv_config_otel_set-insecure +mdx: + format: md +--- + +## thv config otel set-insecure + +Set the OpenTelemetry insecure transport flag + +### Synopsis + +Set the OpenTelemetry insecure flag to enable HTTP instead of HTTPS for OTLP endpoints. + + thv config otel set-insecure true + +``` +thv config otel set-insecure [flags] +``` + +### Options + +``` + -h, --help help for set-insecure +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-metrics-enabled.md b/docs/toolhive/reference/cli/thv_config_otel_set-metrics-enabled.md new file mode 100644 index 00000000..7fb0305b --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_set-metrics-enabled.md @@ -0,0 +1,41 @@ +--- +title: thv config otel set-metrics-enabled +hide_title: true +description: Reference for ToolHive CLI command `thv config otel set-metrics-enabled` +last_update: + author: autogenerated +slug: thv_config_otel_set-metrics-enabled +mdx: + format: md +--- + +## thv config otel set-metrics-enabled + +Set the OpenTelemetry metrics export to enabled + +### Synopsis + +Set the OpenTelemetry metrics flag to enable to export metrics to an OTel collector. + + thv config otel set-metrics-enabled true + +``` +thv config otel set-metrics-enabled [flags] +``` + +### Options + +``` + -h, --help help for set-metrics-enabled +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_set-tracing-enabled.md b/docs/toolhive/reference/cli/thv_config_otel_set-tracing-enabled.md new file mode 100644 index 00000000..fb02fbee --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_set-tracing-enabled.md @@ -0,0 +1,41 @@ +--- +title: thv config otel set-tracing-enabled +hide_title: true +description: Reference for ToolHive CLI command `thv config otel set-tracing-enabled` +last_update: + author: autogenerated +slug: thv_config_otel_set-tracing-enabled +mdx: + format: md +--- + +## thv config otel set-tracing-enabled + +Set the OpenTelemetry tracing export to enabled + +### Synopsis + +Set the OpenTelemetry tracing flag to enable to export traces to an OTel collector. + + thv config otel set-tracing-enabled true + +``` +thv config otel set-tracing-enabled [flags] +``` + +### Options + +``` + -h, --help help for set-tracing-enabled +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-enable-prometheus-metrics-path.md b/docs/toolhive/reference/cli/thv_config_otel_unset-enable-prometheus-metrics-path.md new file mode 100644 index 00000000..b583a7d9 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-enable-prometheus-metrics-path.md @@ -0,0 +1,39 @@ +--- +title: thv config otel unset-enable-prometheus-metrics-path +hide_title: true +description: Reference for ToolHive CLI command `thv config otel unset-enable-prometheus-metrics-path` +last_update: + author: autogenerated +slug: thv_config_otel_unset-enable-prometheus-metrics-path +mdx: + format: md +--- + +## thv config otel unset-enable-prometheus-metrics-path + +Remove the configured OpenTelemetry Prometheus metrics path flag + +### Synopsis + +Remove the OpenTelemetry Prometheus metrics path flag configuration. + +``` +thv config otel unset-enable-prometheus-metrics-path [flags] +``` + +### Options + +``` + -h, --help help for unset-enable-prometheus-metrics-path +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-insecure.md b/docs/toolhive/reference/cli/thv_config_otel_unset-insecure.md new file mode 100644 index 00000000..3e31d737 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-insecure.md @@ -0,0 +1,39 @@ +--- +title: thv config otel unset-insecure +hide_title: true +description: Reference for ToolHive CLI command `thv config otel unset-insecure` +last_update: + author: autogenerated +slug: thv_config_otel_unset-insecure +mdx: + format: md +--- + +## thv config otel unset-insecure + +Remove the configured OpenTelemetry insecure transport flag + +### Synopsis + +Remove the OpenTelemetry insecure transport flag configuration. + +``` +thv config otel unset-insecure [flags] +``` + +### Options + +``` + -h, --help help for unset-insecure +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-metrics-enabled.md b/docs/toolhive/reference/cli/thv_config_otel_unset-metrics-enabled.md new file mode 100644 index 00000000..cd7c9812 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-metrics-enabled.md @@ -0,0 +1,39 @@ +--- +title: thv config otel unset-metrics-enabled +hide_title: true +description: Reference for ToolHive CLI command `thv config otel unset-metrics-enabled` +last_update: + author: autogenerated +slug: thv_config_otel_unset-metrics-enabled +mdx: + format: md +--- + +## thv config otel unset-metrics-enabled + +Remove the configured OpenTelemetry metrics export flag + +### Synopsis + +Remove the OpenTelemetry metrics export flag configuration. + +``` +thv config otel unset-metrics-enabled [flags] +``` + +### Options + +``` + -h, --help help for unset-metrics-enabled +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_config_otel_unset-tracing-enabled.md b/docs/toolhive/reference/cli/thv_config_otel_unset-tracing-enabled.md new file mode 100644 index 00000000..fe449100 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_otel_unset-tracing-enabled.md @@ -0,0 +1,39 @@ +--- +title: thv config otel unset-tracing-enabled +hide_title: true +description: Reference for ToolHive CLI command `thv config otel unset-tracing-enabled` +last_update: + author: autogenerated +slug: thv_config_otel_unset-tracing-enabled +mdx: + format: md +--- + +## thv config otel unset-tracing-enabled + +Remove the configured OpenTelemetry tracing export flag + +### Synopsis + +Remove the OpenTelemetry tracing export flag configuration. + +``` +thv config otel unset-tracing-enabled [flags] +``` + +### Options + +``` + -h, --help help for unset-tracing-enabled +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config otel](thv_config_otel.md) - Manage OpenTelemetry configuration + diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md index 150a0545..6d9e5428 100644 --- a/docs/toolhive/reference/cli/thv_run.md +++ b/docs/toolhive/reference/cli/thv_run.md @@ -107,8 +107,10 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...] --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-metrics-enabled Enable OTLP metrics export (when OTLP endpoint is configured) --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) + --otel-tracing-enabled Enable distributed tracing (when OTLP endpoint is configured) --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") diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index 77e35de6..be9e0f43 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -878,8 +878,16 @@ components: description: Insecure indicates whether to use HTTP instead of HTTPS for the OTLP endpoint type: boolean + metricsEnabled: + description: |- + MetricsEnabled controls whether OTLP metrics are enabled + When false, OTLP metrics are not sent even if an endpoint is configured + This is independent of EnablePrometheusMetricsPath + type: boolean samplingRate: - description: SamplingRate is the trace sampling rate (0.0-1.0) + description: |- + SamplingRate is the trace sampling rate (0.0-1.0) + Only used when TracingEnabled is true type: number serviceName: description: ServiceName is the service name for telemetry @@ -887,6 +895,11 @@ components: serviceVersion: description: ServiceVersion is the service version for telemetry type: string + tracingEnabled: + description: |- + TracingEnabled controls whether distributed tracing is enabled + When false, no tracer provider is created even if an endpoint is configured + type: boolean type: object types.MiddlewareConfig: properties: @@ -1082,6 +1095,11 @@ components: group: description: Group name this workload belongs to type: string + headers: + items: + $ref: '#/components/schemas/registry.Header' + type: array + uniqueItems: false host: description: Host to bind to type: string @@ -1095,6 +1113,8 @@ components: description: Whether network isolation is turned on. This applies the rules in the permission profile. type: boolean + oauth_config: + $ref: '#/components/schemas/v1.remoteOAuthConfig' oidc: $ref: '#/components/schemas/v1.oidcOptions' permission_profile: @@ -1120,6 +1140,9 @@ components: transport: description: Transport configuration type: string + url: + description: Remote server specific fields + type: string volumes: description: Volume mounts items: @@ -1317,6 +1340,47 @@ components: type: array uniqueItems: false type: object + v1.remoteOAuthConfig: + description: OAuth configuration for remote server authentication + properties: + authorize_url: + description: OAuth authorization endpoint URL (alternative to issuer for + non-OIDC OAuth) + type: string + callback_port: + description: Specific port for OAuth callback server + type: integer + client_id: + description: OAuth client ID for authentication + type: string + client_secret: + $ref: '#/components/schemas/secrets.SecretParameter' + issuer: + description: OAuth/OIDC issuer URL (e.g., https://accounts.google.com) + type: string + oauth_params: + additionalProperties: + type: string + description: Additional OAuth parameters for server-specific customization + type: object + scopes: + description: OAuth scopes to request + items: + type: string + type: array + uniqueItems: false + skip_browser: + description: Whether to skip opening browser for OAuth flow (defaults to + false) + type: boolean + token_url: + description: OAuth token endpoint URL (alternative to issuer for non-OIDC + OAuth) + type: string + use_pkce: + description: Whether to use PKCE for the OAuth flow + type: boolean + type: object v1.secretKeyResponse: description: Secret key information properties: @@ -1369,6 +1433,11 @@ components: group: description: Group name this workload belongs to type: string + headers: + items: + $ref: '#/components/schemas/registry.Header' + type: array + uniqueItems: false host: description: Host to bind to type: string @@ -1379,6 +1448,8 @@ components: description: Whether network isolation is turned on. This applies the rules in the permission profile. type: boolean + oauth_config: + $ref: '#/components/schemas/v1.remoteOAuthConfig' oidc: $ref: '#/components/schemas/v1.oidcOptions' permission_profile: @@ -1404,6 +1475,9 @@ components: transport: description: Transport configuration type: string + url: + description: Remote server specific fields + type: string volumes: description: Volume mounts items: