diff --git a/docs/toolhive/reference/cli/thv_client_register.md b/docs/toolhive/reference/cli/thv_client_register.md index cea2429..b83b473 100644 --- a/docs/toolhive/reference/cli/thv_client_register.md +++ b/docs/toolhive/reference/cli/thv_client_register.md @@ -28,10 +28,12 @@ Valid clients: - continue: Continue.dev extensions for VS Code and JetBrains - cursor: Cursor editor - goose: Goose AI agent + - kiro: Kiro AI IDE - lm-studio: LM Studio application + - opencode: OpenCode editor - roo-code: Roo Code extension for VS Code - trae: Trae IDE - - vscode: Visual Studio Code + - vscode: Visual Studio Code (GitHub Copilot) - vscode-insider: Visual Studio Code Insiders edition - windsurf: Windsurf IDE - windsurf-jetbrains: Windsurf for JetBrains IDEs diff --git a/docs/toolhive/reference/cli/thv_client_remove.md b/docs/toolhive/reference/cli/thv_client_remove.md index 6f32e7f..d25889a 100644 --- a/docs/toolhive/reference/cli/thv_client_remove.md +++ b/docs/toolhive/reference/cli/thv_client_remove.md @@ -28,10 +28,12 @@ Valid clients: - continue: Continue.dev extensions for VS Code and JetBrains - cursor: Cursor editor - goose: Goose AI agent + - kiro: Kiro AI IDE - lm-studio: LM Studio application + - opencode: OpenCode editor - roo-code: Roo Code extension for VS Code - trae: Trae IDE - - vscode: Visual Studio Code + - vscode: Visual Studio Code (GitHub Copilot) - vscode-insider: Visual Studio Code Insiders edition - windsurf: Windsurf IDE - windsurf-jetbrains: Windsurf for JetBrains IDEs diff --git a/docs/toolhive/reference/cli/thv_config.md b/docs/toolhive/reference/cli/thv_config.md index c19d24b..8a503af 100644 --- a/docs/toolhive/reference/cli/thv_config.md +++ b/docs/toolhive/reference/cli/thv_config.md @@ -39,4 +39,5 @@ The config command provides subcommands to manage application configuration sett * [thv config set-registry](thv_config_set-registry.md) - Set the MCP server registry * [thv config unset-ca-cert](thv_config_unset-ca-cert.md) - Remove the configured CA certificate * [thv config unset-registry](thv_config_unset-registry.md) - Remove the configured registry +* [thv config usage-metrics](thv_config_usage-metrics.md) - Enable or disable anonymous usage metrics diff --git a/docs/toolhive/reference/cli/thv_config_set-registry.md b/docs/toolhive/reference/cli/thv_config_set-registry.md index 376e03b..0a6725b 100644 --- a/docs/toolhive/reference/cli/thv_config_set-registry.md +++ b/docs/toolhive/reference/cli/thv_config_set-registry.md @@ -15,11 +15,15 @@ Set the MCP server registry ### Synopsis -Set the MCP server registry to either a remote URL or local file path. -The command automatically detects whether the input is a URL or file path. +Set the MCP server registry to a remote URL, local file path, or API endpoint. +The command automatically detects the registry type: + - URLs ending with .json are treated as static registry files + - Other URLs are treated as MCP Registry API endpoints (v0.1 spec) + - Local paths are treated as local registry files Examples: - thv config set-registry https://example.com/registry.json # Remote URL + thv config set-registry https://example.com/registry.json # Static remote file + thv config set-registry https://registry.example.com # API endpoint thv config set-registry /path/to/local-registry.json # Local file path thv config set-registry file:///path/to/local-registry.json # Explicit file URL @@ -30,7 +34,7 @@ thv config set-registry [flags] ### Options ``` - -p, --allow-private-ip Allow setting the registry URL, even if it references a private IP address + -p, --allow-private-ip Allow setting the registry URL or API endpoint, even if it references a private IP address -h, --help help for set-registry ``` diff --git a/docs/toolhive/reference/cli/thv_config_usage-metrics.md b/docs/toolhive/reference/cli/thv_config_usage-metrics.md new file mode 100644 index 0000000..9fa161e --- /dev/null +++ b/docs/toolhive/reference/cli/thv_config_usage-metrics.md @@ -0,0 +1,35 @@ +--- +title: thv config usage-metrics +hide_title: true +description: Reference for ToolHive CLI command `thv config usage-metrics` +last_update: + author: autogenerated +slug: thv_config_usage-metrics +mdx: + format: md +--- + +## thv config usage-metrics + +Enable or disable anonymous usage metrics + +``` +thv config usage-metrics [flags] +``` + +### Options + +``` + -h, --help help for usage-metrics +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv config](thv_config.md) - Manage application configuration + diff --git a/docs/toolhive/reference/cli/thv_registry_info.md b/docs/toolhive/reference/cli/thv_registry_info.md index cb50bd2..45d2f0e 100644 --- a/docs/toolhive/reference/cli/thv_registry_info.md +++ b/docs/toolhive/reference/cli/thv_registry_info.md @@ -26,6 +26,7 @@ thv registry info [server] [flags] ``` --format string Output format (json or text) (default "text") -h, --help help for info + --refresh Force refresh registry cache ``` ### Options inherited from parent commands diff --git a/docs/toolhive/reference/cli/thv_registry_list.md b/docs/toolhive/reference/cli/thv_registry_list.md index a2f9dfe..2feff6c 100644 --- a/docs/toolhive/reference/cli/thv_registry_list.md +++ b/docs/toolhive/reference/cli/thv_registry_list.md @@ -26,6 +26,7 @@ thv registry list [flags] ``` --format string Output format (json or text) (default "text") -h, --help help for list + --refresh Force refresh registry cache ``` ### Options inherited from parent commands diff --git a/static/api-specs/toolhive-api.yaml b/static/api-specs/toolhive-api.yaml index dae2724..51a1206 100644 --- a/static/api-specs/toolhive-api.yaml +++ b/static/api-specs/toolhive-api.yaml @@ -132,6 +132,8 @@ components: - Goose - Trae - Continue + - OpenCode + - Kiro client.MCPClientStatus: properties: client_type: @@ -155,6 +157,8 @@ components: - Goose - Trae - Continue + - OpenCode + - Kiro installed: description: Installed indicates whether the client is installed on the system @@ -333,289 +337,435 @@ components: type: array uniqueItems: false type: object - registry.EnvVar: + remote.Config: + description: RemoteAuthConfig contains OAuth configuration for remote MCP servers properties: - default: - description: |- - Default is the value to use if the environment variable is not explicitly provided - Only used for non-required variables + authorize_url: type: string - description: - description: Description is a human-readable explanation of the variable's - purpose + callback_port: + type: integer + client_id: type: string - name: - description: Name is the environment variable name (e.g., API_KEY) + client_secret: type: string - required: - description: |- - Required indicates whether this environment variable must be provided - If true and not provided via command line or secrets, the user will be prompted for a value - type: boolean - secret: - description: |- - Secret indicates whether this environment variable contains sensitive information - If true, the value will be stored as a secret rather than as a plain environment variable - type: boolean - type: object - registry.Group: - properties: - description: - description: Description is a human-readable description of the group's - purpose and functionality + client_secret_file: type: string - name: - description: Name is the identifier for the group, used when referencing - the group in commands + env_vars: + description: Environment variables for the client + items: + $ref: '#/components/schemas/types.EnvVar' + type: array + uniqueItems: false + headers: + description: Headers for HTTP requests + items: + $ref: '#/components/schemas/types.Header' + type: array + uniqueItems: false + issuer: + description: OAuth endpoint configuration (from registry) type: string - remote_servers: - additionalProperties: - $ref: '#/components/schemas/registry.RemoteServerMetadata' - description: RemoteServers is a map of server names to their corresponding - remote server definitions within this group - type: object - servers: + oauth_params: additionalProperties: - $ref: '#/components/schemas/registry.ImageMetadata' - description: Servers is a map of server names to their corresponding server - definitions within this group + type: string + description: OAuth parameters for server-specific customization type: object - type: object - registry.Header: - properties: - choices: - description: Choices provides a list of valid values for the header (optional) + resource: + description: Resource is the OAuth 2.0 resource indicator (RFC 8707). + type: string + scopes: items: type: string type: array uniqueItems: false - default: - description: |- - Default is the value to use if the header is not explicitly provided - Only used for non-required headers - type: string - description: - description: Description is a human-readable explanation of the header's - purpose + skip_browser: + type: boolean + timeout: + example: 5m type: string - name: - description: Name is the header name (e.g., X-API-Key, Authorization) + token_url: type: string - required: - description: |- - Required indicates whether this header must be provided - If true and not provided via command line or secrets, the user will be prompted for a value - type: boolean - secret: - description: |- - Secret indicates whether this header contains sensitive information - If true, the value will be stored as a secret rather than as plain text + use_pkce: type: boolean type: object - registry.ImageMetadata: - description: Container server details (if it's a container server) + runner.RunConfig: properties: - args: - description: |- - Args are the default command-line arguments to pass to the MCP server container. - These arguments will be used only if no command-line arguments are provided by the user. - If the user provides arguments, they will override these defaults. + 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 - custom_metadata: - additionalProperties: {} - description: CustomMetadata allows for additional user-defined metadata + container_labels: + additionalProperties: + type: string + description: ContainerLabels are the labels to apply to the container type: object - description: - description: Description is a human-readable description of the server's - purpose and functionality + container_name: + description: ContainerName is the name of the container + type: string + debug: + description: Debug indicates whether debug mode is enabled + type: boolean + env_file_dir: + description: EnvFileDir is the directory path to load environment files + from type: string - docker_tags: - description: DockerTags lists the available Docker tags for this server - image - items: - type: string - type: array - uniqueItems: false env_vars: - description: EnvVars defines environment variables that can be passed to - the server + 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_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 + middleware_configs: + description: |- + MiddlewareConfigs contains the list of middleware to apply to the transport + and the configuration for each middleware. items: - $ref: '#/components/schemas/registry.EnvVar' + $ref: '#/components/schemas/types.MiddlewareConfig' type: array uniqueItems: false - image: - description: Image is the Docker image reference for the MCP server - type: string - metadata: - $ref: '#/components/schemas/registry.Metadata' name: - description: |- - Name is the identifier for the MCP server, used when referencing the server in commands - If not provided, it will be auto-generated from the registry key + description: Name is the name of the MCP server type: string - permissions: + oidc_config: + $ref: '#/components/schemas/auth.TokenValidatorConfig' + permission_profile: $ref: '#/components/schemas/permissions.Profile' - provenance: - $ref: '#/components/schemas/registry.Provenance' - repository_url: - description: RepositoryURL is the URL to the source code repository for - the server + permission_profile_name_or_path: + description: PermissionProfileNameOrPath is the name or path of the permission + profile type: string - status: - description: Status indicates whether the server is currently active or - deprecated + port: + description: Port is the port for the HTTP proxy to listen on (host port) + type: integer + proxy_mode: + $ref: '#/components/schemas/types.ProxyMode' + remote_auth_config: + $ref: '#/components/schemas/remote.Config' + remote_url: + description: RemoteURL is the URL of the remote MCP server (if running remotely) type: string - tags: - description: Tags are categorization labels for the server to aid in discovery - and filtering + schema_version: + description: SchemaVersion is the version of the RunConfig schema + type: string + 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 and Streamable HTTP transports) + to SSE transport) type: integer - tier: - description: Tier represents the tier classification level of the server, - e.g., "Official" or "Community" + 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: - description: Tools is a list of tool names provided by this MCP server + token_exchange_config: + $ref: '#/components/schemas/tokenexchange.Config' + tools_filter: + description: ToolsFilter is the list of tools to filter items: type: string type: array uniqueItems: false + tools_override: + additionalProperties: + $ref: '#/components/schemas/runner.ToolOverride' + description: ToolsOverride is a map from an actual tool to its overridden + name and/or description + type: object transport: - description: |- - Transport defines the communication protocol for the server - For containers: stdio, sse, or streamable-http - For remote servers: sse or streamable-http (stdio not supported) + description: Transport is the transport mode (stdio, sse, or streamable-http) type: string + x-enum-varnames: + - TransportTypeStdio + - TransportTypeSSE + - TransportTypeStreamableHTTP + - TransportTypeInspector + trust_proxy_headers: + description: TrustProxyHeaders indicates whether to trust X-Forwarded-* + headers from reverse proxies + type: boolean + 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 - registry.Metadata: - description: Metadata contains additional information about the server such - as popularity metrics + runner.ToolOverride: properties: - last_updated: - description: LastUpdated is the timestamp when the server was last updated, - in RFC3339 format + description: + description: Description is the redefined description of the tool + type: string + name: + description: Name is the redefined name of the tool type: string - pulls: - description: Pulls indicates how many times the server image has been downloaded - type: integer - stars: - description: Stars represents the popularity rating or number of stars for - the server - type: integer type: object - registry.OAuthConfig: - description: |- - OAuthConfig provides OAuth/OIDC configuration for authentication to the remote server - Used with the thv proxy command's --remote-auth flags + runtime.WorkloadStatus: + description: Status is the current status of the workload. + type: string + x-enum-varnames: + - WorkloadStatusRunning + - WorkloadStatusStopped + - WorkloadStatusError + - WorkloadStatusStarting + - WorkloadStatusStopping + - WorkloadStatusUnhealthy + - WorkloadStatusRemoving + - WorkloadStatusUnknown + - WorkloadStatusUnauthenticated + secrets.SecretParameter: properties: - authorize_url: - description: |- - 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 + name: type: string - issuer: - description: |- - Issuer is the OAuth/OIDC issuer URL (e.g., https://accounts.google.com) - Used for OIDC discovery to find authorization and token endpoints + target: type: string - oauth_params: + type: object + telemetry.Config: + description: TelemetryConfig contains the OpenTelemetry configuration + properties: + customAttributes: 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. + CustomAttributes contains custom resource attributes to be added to all telemetry signals. + These are parsed from CLI flags (--otel-custom-attributes) or environment variables + (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs. + We use map[string]string for proper JSON serialization instead of []attribute.KeyValue + which doesn't marshal/unmarshal correctly. type: object - resource: - description: Resource is the OAuth 2.0 resource indicator (RFC 8707) + 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 - scopes: + environmentVariables: description: |- - Scopes are the OAuth scopes to request - If not specified, defaults to ["openid", "profile", "email"] for OIDC + 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 uniqueItems: false - token_url: + 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 + metricsEnabled: description: |- - TokenURL is the OAuth token endpoint URL - Used for non-OIDC OAuth flows when issuer is not provided + 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) + Only used when TracingEnabled is true + type: number + serviceName: + description: ServiceName is the service name for telemetry type: string - use_pkce: + serviceVersion: + description: ServiceVersion is the service version for telemetry + type: string + tracingEnabled: description: |- - UsePKCE indicates whether to use PKCE for the OAuth flow - Defaults to true for enhanced security + TracingEnabled controls whether distributed tracing is enabled + When false, no tracer provider is created even if an endpoint is configured type: boolean type: object - registry.Provenance: - description: Provenance contains verification and signing metadata + tokenexchange.Config: + description: TokenExchangeConfig contains token exchange configuration for external + authentication properties: - attestation: - $ref: '#/components/schemas/registry.VerifiedAttestation' - cert_issuer: - type: string - repository_ref: + audience: + description: Audience is the target audience for the exchanged token type: string - repository_uri: + client_id: + description: ClientID is the OAuth 2.0 client identifier type: string - runner_environment: + client_secret: + description: ClientSecret is the OAuth 2.0 client secret type: string - signer_identity: + external_token_header_name: + description: ExternalTokenHeaderName is the name of the custom header to + use when HeaderStrategy is "custom" type: string - sigstore_url: + header_strategy: + description: |- + HeaderStrategy determines how to inject the token + Valid values: HeaderStrategyReplace (default), HeaderStrategyCustom type: string - type: object - registry.Registry: - description: Full registry data - properties: - groups: - description: Groups is a slice of group definitions containing related MCP - servers + scopes: + description: Scopes is the list of scopes to request for the exchanged token items: - $ref: '#/components/schemas/registry.Group' + type: string type: array uniqueItems: false - last_updated: - description: LastUpdated is the timestamp when the registry was last updated, - in RFC3339 format + subject_token_type: + description: |- + SubjectTokenType specifies the type of the subject token being exchanged. + Common values: tokenTypeAccessToken (default), tokenTypeIDToken, tokenTypeJWT. + If empty, defaults to tokenTypeAccessToken. + type: string + token_url: + description: TokenURL is the OAuth 2.0 token endpoint URL + type: string + type: object + types.EnvVar: + properties: + default: + description: |- + Default is the value to use if the environment variable is not explicitly provided + Only used for non-required variables + type: string + description: + description: Description is a human-readable explanation of the variable's + purpose + type: string + name: + description: Name is the environment variable name (e.g., API_KEY) + type: string + required: + description: |- + Required indicates whether this environment variable must be provided + If true and not provided via command line or secrets, the user will be prompted for a value + type: boolean + secret: + description: |- + Secret indicates whether this environment variable contains sensitive information + If true, the value will be stored as a secret rather than as a plain environment variable + type: boolean + type: object + types.Group: + properties: + description: + description: Description is a human-readable description of the group's + purpose and functionality + type: string + name: + description: Name is the identifier for the group, used when referencing + the group in commands type: string remote_servers: additionalProperties: - $ref: '#/components/schemas/registry.RemoteServerMetadata' - description: |- - RemoteServers is a map of server names to their corresponding remote server definitions - These are MCP servers accessed via HTTP/HTTPS using the thv proxy command + $ref: '#/components/schemas/types.RemoteServerMetadata' + description: RemoteServers is a map of server names to their corresponding + remote server definitions within this group type: object servers: additionalProperties: - $ref: '#/components/schemas/registry.ImageMetadata' + $ref: '#/components/schemas/types.ImageMetadata' description: Servers is a map of server names to their corresponding server - definitions + definitions within this group type: object - version: - description: Version is the schema version of the registry + type: object + types.Header: + properties: + choices: + description: Choices provides a list of valid values for the header (optional) + items: + type: string + type: array + uniqueItems: false + default: + description: |- + Default is the value to use if the header is not explicitly provided + Only used for non-required headers + type: string + description: + description: Description is a human-readable explanation of the header's + purpose + type: string + name: + description: Name is the header name (e.g., X-API-Key, Authorization) type: string + required: + description: |- + Required indicates whether this header must be provided + If true and not provided via command line or secrets, the user will be prompted for a value + type: boolean + secret: + description: |- + Secret indicates whether this header contains sensitive information + If true, the value will be stored as a secret rather than as plain text + type: boolean type: object - registry.RemoteServerMetadata: - description: Remote server details (if it's a remote server) + types.ImageMetadata: + description: Container server details (if it's a container server) properties: + args: + description: |- + Args are the default command-line arguments to pass to the MCP server container. + These arguments will be used only if no command-line arguments are provided by the user. + If the user provides arguments, they will override these defaults. + items: + type: string + type: array + uniqueItems: false custom_metadata: additionalProperties: {} description: CustomMetadata allows for additional user-defined metadata @@ -624,31 +774,34 @@ components: description: Description is a human-readable description of the server's purpose and functionality type: string - env_vars: - description: |- - EnvVars defines environment variables that can be passed to configure the client - These might be needed for client-side configuration when connecting to the remote server + docker_tags: + description: DockerTags lists the available Docker tags for this server + image items: - $ref: '#/components/schemas/registry.EnvVar' + type: string type: array uniqueItems: false - headers: - description: |- - Headers defines HTTP headers that can be passed to the remote server for authentication - These are used with the thv proxy command's authentication features + env_vars: + description: EnvVars defines environment variables that can be passed to + the server items: - $ref: '#/components/schemas/registry.Header' + $ref: '#/components/schemas/types.EnvVar' type: array uniqueItems: false + image: + description: Image is the Docker image reference for the MCP server + type: string metadata: - $ref: '#/components/schemas/registry.Metadata' + $ref: '#/components/schemas/types.Metadata' name: description: |- Name is the identifier for the MCP server, used when referencing the server in commands If not provided, it will be auto-generated from the registry key type: string - oauth_config: - $ref: '#/components/schemas/registry.OAuthConfig' + permissions: + $ref: '#/components/schemas/permissions.Profile' + provenance: + $ref: '#/components/schemas/types.Provenance' repository_url: description: RepositoryURL is the URL to the source code repository for the server @@ -664,6 +817,10 @@ components: type: string type: array uniqueItems: false + target_port: + description: TargetPort is the port for the container to expose (only applicable + to SSE and Streamable HTTP transports) + type: integer tier: description: Tier represents the tier classification level of the server, e.g., "Official" or "Community" @@ -680,331 +837,212 @@ components: For containers: stdio, sse, or streamable-http For remote servers: sse or streamable-http (stdio not supported) type: string - url: - description: URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp) - type: string type: object - registry.VerifiedAttestation: + types.Metadata: + description: Metadata contains additional information about the server such + as popularity metrics properties: - predicate: {} - predicate_type: + last_updated: + description: LastUpdated is the timestamp when the server was last updated, + in RFC3339 format type: string + pulls: + description: Pulls indicates how many times the server image has been downloaded + type: integer + stars: + description: Stars represents the popularity rating or number of stars for + the server + type: integer type: object - remote.Config: - description: RemoteAuthConfig contains OAuth configuration for remote MCP servers + types.MiddlewareConfig: properties: - authorize_url: - type: string - callback_port: - type: integer - client_id: - type: string - client_secret: - type: string - client_secret_file: - type: string - env_vars: - description: Environment variables for the client - items: - $ref: '#/components/schemas/registry.EnvVar' - type: array - uniqueItems: false - headers: - description: Headers for HTTP requests - items: - $ref: '#/components/schemas/registry.Header' - type: array - uniqueItems: false - issuer: - description: OAuth endpoint configuration (from registry) - type: string - oauth_params: - additionalProperties: - type: string - description: OAuth parameters for server-specific customization + parameters: + description: |- + Parameters is a JSON object containing the middleware parameters. + It is stored as a raw message to allow flexible parameter types. type: object - resource: - description: Resource is the OAuth 2.0 resource indicator (RFC 8707). - type: string - scopes: - items: - type: string - type: array - uniqueItems: false - skip_browser: - type: boolean - timeout: - example: 5m - type: string - token_url: + type: + description: Type is a string representing the middleware type. type: string - use_pkce: - type: boolean type: object - runner.RunConfig: + types.OAuthConfig: + description: |- + OAuthConfig provides OAuth/OIDC configuration for authentication to the remote server + Used with the thv proxy command's --remote-auth flags 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_file_dir: - description: EnvFileDir is the directory path to load environment files - from - type: string - 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_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 - middleware_configs: - description: |- - MiddlewareConfigs contains the list of middleware to apply to the transport - and the configuration for each middleware. - items: - $ref: '#/components/schemas/types.MiddlewareConfig' - type: array - uniqueItems: false - 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' - remote_auth_config: - $ref: '#/components/schemas/remote.Config' - 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 - secrets: + authorize_url: 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) + AuthorizeURL is the OAuth authorization endpoint URL + Used for non-OIDC OAuth flows when issuer is not provided type: string - target_port: - description: TargetPort is the port for the container to expose (only applicable - to SSE transport) + 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 - telemetry_config: - $ref: '#/components/schemas/telemetry.Config' - thv_ca_bundle: - description: ThvCABundle is the path to the CA certificate bundle for ToolHive - HTTP operations + client_id: + description: ClientID is the OAuth client ID for authentication type: string - tools_filter: - description: ToolsFilter is the list of tools to filter - items: - type: string - type: array - uniqueItems: false - tools_override: + issuer: + description: |- + 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: - $ref: '#/components/schemas/runner.ToolOverride' - description: ToolsOverride is a map from an actual tool to its overridden - name and/or description + 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 - transport: - description: Transport is the transport mode (stdio, sse, or streamable-http) + resource: + description: Resource is the OAuth 2.0 resource indicator (RFC 8707) type: string - x-enum-varnames: - - TransportTypeStdio - - TransportTypeSSE - - TransportTypeStreamableHTTP - - TransportTypeInspector - trust_proxy_headers: - description: TrustProxyHeaders indicates whether to trust X-Forwarded-* - headers from reverse proxies - type: boolean - volumes: + scopes: description: |- - Volumes are the directory mounts to pass to the container - Format: "host-path:container-path[:ro]" + Scopes are the OAuth scopes to request + If not specified, defaults to ["openid", "profile", "email"] for OIDC items: type: string type: array uniqueItems: false + token_url: + description: |- + TokenURL is the OAuth token endpoint URL + Used for non-OIDC OAuth flows when issuer is not provided + type: string + use_pkce: + description: |- + UsePKCE indicates whether to use PKCE for the OAuth flow + Defaults to true for enhanced security + type: boolean type: object - runner.ToolOverride: + types.Provenance: + description: Provenance contains verification and signing metadata properties: - description: - description: Description is the redefined description of the tool + attestation: + $ref: '#/components/schemas/types.VerifiedAttestation' + cert_issuer: type: string - name: - description: Name is the redefined name of the tool + repository_ref: + type: string + repository_uri: + type: string + runner_environment: + type: string + signer_identity: + type: string + sigstore_url: type: string type: object - runtime.WorkloadStatus: - description: Status is the current status of the workload. + types.ProxyMode: + description: ProxyMode is the proxy mode for stdio transport ("sse" or "streamable-http") type: string x-enum-varnames: - - WorkloadStatusRunning - - WorkloadStatusStopped - - WorkloadStatusError - - WorkloadStatusStarting - - WorkloadStatusStopping - - WorkloadStatusUnhealthy - - WorkloadStatusRemoving - - WorkloadStatusUnknown - - WorkloadStatusUnauthenticated - secrets.SecretParameter: + - ProxyModeSSE + - ProxyModeStreamableHTTP + types.Registry: + description: Full registry data properties: - name: + groups: + description: Groups is a slice of group definitions containing related MCP + servers + items: + $ref: '#/components/schemas/types.Group' + type: array + uniqueItems: false + last_updated: + description: LastUpdated is the timestamp when the registry was last updated, + in RFC3339 format type: string - target: + remote_servers: + additionalProperties: + $ref: '#/components/schemas/types.RemoteServerMetadata' + description: |- + RemoteServers is a map of server names to their corresponding remote server definitions + These are MCP servers accessed via HTTP/HTTPS using the thv proxy command + type: object + servers: + additionalProperties: + $ref: '#/components/schemas/types.ImageMetadata' + description: Servers is a map of server names to their corresponding server + definitions + type: object + version: + description: Version is the schema version of the registry type: string type: object - telemetry.Config: - description: TelemetryConfig contains the OpenTelemetry configuration + types.RemoteServerMetadata: + description: Remote server details (if it's a remote server) properties: - customAttributes: - additionalProperties: - type: string - description: |- - CustomAttributes contains custom resource attributes to be added to all telemetry signals. - These are parsed from CLI flags (--otel-custom-attributes) or environment variables - (OTEL_RESOURCE_ATTRIBUTES) as key=value pairs. - We use map[string]string for proper JSON serialization instead of []attribute.KeyValue - which doesn't marshal/unmarshal correctly. + custom_metadata: + additionalProperties: {} + description: CustomMetadata allows for additional user-defined metadata type: object - 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 + description: + description: Description is a human-readable description of the server's + purpose and functionality type: string - environmentVariables: + env_vars: 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"} + EnvVars defines environment variables that can be passed to configure the client + These might be needed for client-side configuration when connecting to the remote server items: - type: string + $ref: '#/components/schemas/types.EnvVar' type: array uniqueItems: false 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 - 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: + Headers defines HTTP headers that can be passed to the remote server for authentication + These are used with the thv proxy command's authentication features + items: + $ref: '#/components/schemas/types.Header' + type: array + uniqueItems: false + metadata: + $ref: '#/components/schemas/types.Metadata' + name: 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 + Name is the identifier for the MCP server, used when referencing the server in commands + If not provided, it will be auto-generated from the registry key type: string - serviceVersion: - description: ServiceVersion is the service version for telemetry + oauth_config: + $ref: '#/components/schemas/types.OAuthConfig' + repository_url: + description: RepositoryURL is the URL to the source code repository for + the server 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: - parameters: + status: + description: Status indicates whether the server is currently active or + deprecated + type: string + tags: + description: Tags are categorization labels for the server to aid in discovery + and filtering + items: + type: string + type: array + uniqueItems: false + tier: + description: Tier represents the tier classification level of the server, + e.g., "Official" or "Community" + type: string + tools: + description: Tools is a list of tool names provided by this MCP server + items: + type: string + type: array + uniqueItems: false + transport: description: |- - Parameters is a JSON object containing the middleware parameters. - It is stored as a raw message to allow flexible parameter types. - type: object - type: - description: Type is a string representing the middleware type. + Transport defines the communication protocol for the server + For containers: stdio, sse, or streamable-http + For remote servers: sse or streamable-http (stdio not supported) + type: string + url: + description: URL is the endpoint URL for the remote MCP server (e.g., https://api.example.com/mcp) 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 @@ -1013,19 +1051,29 @@ components: - TransportTypeSSE - TransportTypeStreamableHTTP - TransportTypeInspector + types.VerifiedAttestation: + properties: + predicate: {} + predicate_type: + type: string + type: object v1.RegistryType: description: Type of registry (file, url, or default) type: string x-enum-varnames: - RegistryTypeFile - RegistryTypeURL + - RegistryTypeAPI - RegistryTypeDefault v1.UpdateRegistryRequest: description: Request containing registry configuration updates properties: allow_private_ip: - description: Allow private IP addresses for registry URL + description: Allow private IP addresses for registry URL or API URL type: boolean + api_url: + description: MCP Registry API URL + type: string local_path: description: Local registry file path type: string @@ -1073,6 +1121,8 @@ components: - Goose - Trae - Continue + - OpenCode + - Kiro type: array uniqueItems: false type: object @@ -1125,6 +1175,8 @@ components: - Goose - Trae - Continue + - OpenCode + - Kiro type: object v1.createClientResponse: properties: @@ -1155,6 +1207,8 @@ components: - Goose - Trae - Continue + - OpenCode + - Kiro type: object v1.createGroupRequest: properties: @@ -1190,7 +1244,7 @@ components: type: string headers: items: - $ref: '#/components/schemas/registry.Header' + $ref: '#/components/schemas/types.Header' type: array uniqueItems: false host: @@ -1294,7 +1348,7 @@ components: description: Name of the registry type: string registry: - $ref: '#/components/schemas/registry.Registry' + $ref: '#/components/schemas/types.Registry' server_count: description: Number of servers in the registry type: integer @@ -1308,6 +1362,7 @@ components: x-enum-varnames: - RegistryTypeFile - RegistryTypeURL + - RegistryTypeAPI - RegistryTypeDefault version: description: Version of the registry schema @@ -1332,9 +1387,9 @@ components: description: Indicates if this is a remote server type: boolean remote_server: - $ref: '#/components/schemas/registry.RemoteServerMetadata' + $ref: '#/components/schemas/types.RemoteServerMetadata' server: - $ref: '#/components/schemas/registry.ImageMetadata' + $ref: '#/components/schemas/types.ImageMetadata' type: object v1.groupListResponse: properties: @@ -1361,13 +1416,13 @@ components: remote_servers: description: List of remote servers in the registry (if any) items: - $ref: '#/components/schemas/registry.RemoteServerMetadata' + $ref: '#/components/schemas/types.RemoteServerMetadata' type: array uniqueItems: false servers: description: List of container servers in the registry items: - $ref: '#/components/schemas/registry.ImageMetadata' + $ref: '#/components/schemas/types.ImageMetadata' type: array uniqueItems: false type: object @@ -1552,7 +1607,7 @@ components: type: string headers: items: - $ref: '#/components/schemas/registry.Header' + $ref: '#/components/schemas/types.Header' type: array uniqueItems: false host: