ToolHive Registry API
The ToolHive Registry Server API for discovering, governing, and controlling access to MCP servers and agent skills — MCP Registry API v0.1 (read) plus a /v1 admin API. OpenAPI 3.1.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
url: https://github.com/stacklok/toolhive
description: 'API for accessing MCP server registry data and deployed server information
This API provides endpoints to query the MCP (Model Context Protocol) server registry,
get information about available servers, and check the status of deployed servers.
Authentication is required by default. Use Bearer token authentication with a valid
OAuth/OIDC access token. The /.well-known/oauth-protected-resource endpoint provides
OAuth discovery metadata (RFC 9728).'
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: ToolHive clients registry API
version: '0.1'
tags:
- name: registry
paths:
/registry/{registryName}/v0.1/servers:
get:
description: Get a list of available servers from a specific registry
parameters:
- description: Registry name
in: path
name: registryName
required: true
schema:
type: string
- description: Pagination cursor for retrieving next set of results
in: query
name: cursor
schema:
type: string
- description: Maximum number of items to return
in: query
name: limit
schema:
type: integer
- description: Search servers by name (substring match)
in: query
name: search
schema:
type: string
- description: Filter by version ('latest' for latest version, or an exact version like '1.2.3')
in: query
name: version
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/v0.ServerListResponse'
description: OK
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'401':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Registry not found
security:
- BearerAuth: []
summary: List servers in specific registry
tags:
- registry
/registry/{registryName}/v0.1/servers/{serverName}/versions:
get:
description: Returns all available versions for a specific MCP server from a specific registry
parameters:
- description: Registry name
in: path
name: registryName
required: true
schema:
type: string
- description: URL-encoded server name (e.g., \
in: path
name: serverName
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/v0.ServerListResponse'
description: A list of all versions for the server
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'401':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Server not found
security:
- BearerAuth: []
summary: List all versions of an MCP server in specific registry
tags:
- registry
/registry/{registryName}/v0.1/servers/{serverName}/versions/{version}:
get:
description: 'Returns detailed information about a specific version of an MCP server from a specific registry.
Use the special version `latest` to get the latest version.'
parameters:
- description: Registry name
in: path
name: registryName
required: true
schema:
type: string
- description: URL-encoded server name (e.g., \
in: path
name: serverName
required: true
schema:
type: string
- description: URL-encoded version to retrieve (e.g., \
in: path
name: version
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/v0.ServerResponse'
description: Detailed server information
'400':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Bad request
'401':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Unauthorized
'404':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Server or version not found
security:
- BearerAuth: []
summary: Get specific MCP server version in specific registry
tags:
- registry
/api/v1beta/registry:
get:
description: Get a list of the current registries
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.registryListResponse'
description: OK
summary: List registries
tags:
- registry
post:
description: Add a new registry
requestBody:
content:
application/json:
schema:
type: object
responses:
'501':
content:
application/json:
schema:
type: string
description: Not Implemented
summary: Add a registry
tags:
- registry
/api/v1beta/registry/{name}:
delete:
description: Remove a specific registry
parameters:
- description: Registry name
in: path
name: name
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
type: string
description: No Content
'403':
content:
application/json:
schema:
type: string
description: Forbidden - blocked by policy
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Remove a registry
tags:
- registry
get:
description: Get details of a specific registry
parameters:
- description: Registry name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.getRegistryResponse'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Get a registry
tags:
- registry
put:
description: Update registry URL or local path for the default registry
parameters:
- description: Registry name (must be 'default')
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/pkg_api_v1.UpdateRegistryRequest'
description: Registry configuration
summary: body
description: Registry configuration
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.UpdateRegistryResponse'
description: OK
'400':
content:
application/json:
schema:
type: string
description: Bad Request
'403':
content:
application/json:
schema:
type: string
description: Forbidden - blocked by policy
'404':
content:
application/json:
schema:
type: string
description: Not Found
'502':
content:
application/json:
schema:
type: string
description: Bad Gateway - Registry validation failed
'504':
content:
application/json:
schema:
type: string
description: Gateway Timeout - Registry unreachable
summary: Update registry configuration
tags:
- registry
/api/v1beta/registry/{name}/refresh:
post:
description: Force a refresh of the server-side registry cache for the default registry
parameters:
- description: Registry name (must be 'default')
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Registry refreshed
'404':
content:
application/json:
schema:
type: string
description: Not Found
'500':
content:
application/json:
schema:
type: string
description: Internal Server Error
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.registryErrorResponse'
description: Registry authentication required or upstream registry unavailable
summary: Refresh registry cache
tags:
- registry
/api/v1beta/registry/{name}/servers:
get:
description: Get a list of servers in a specific registry
parameters:
- description: Registry name
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.listServersResponse'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: List servers in a registry
tags:
- registry
/api/v1beta/registry/{name}/servers/{serverName}:
get:
description: Get details of a specific server in a registry
parameters:
- description: Registry name
in: path
name: name
required: true
schema:
type: string
- description: ImageMetadata name
in: path
name: serverName
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pkg_api_v1.getServerResponse'
description: OK
'404':
content:
application/json:
schema:
type: string
description: Not Found
summary: Get a server from a registry
tags:
- registry
/api/v1beta/registry/auth/login:
post:
description: Trigger an interactive OAuth flow to authenticate with the configured registry. Only available in serve mode.
responses:
'200':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Authenticated successfully
'400':
content:
application/json:
schema:
type: string
description: Bad Request - Registry OAuth not configured
'500':
content:
application/json:
schema:
type: string
description: Internal Server Error
summary: Registry login
tags:
- registry
/api/v1beta/registry/auth/logout:
post:
description: Clear cached OAuth tokens for the configured registry. Only available in serve mode.
responses:
'200':
content:
application/json:
schema:
additionalProperties:
type: string
type: object
description: Logged out successfully
'400':
content:
application/json:
schema:
type: string
description: Bad Request - Registry OAuth not configured
'500':
content:
application/json:
schema:
type: string
description: Internal Server Error
summary: Registry logout
tags:
- registry
components:
schemas:
registry.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
permissions.OutboundNetworkPermissions:
description: Outbound defines outbound network permissions
properties:
allow_host:
description: AllowHost is a list of allowed hosts
items:
type: string
type: array
uniqueItems: false
allow_port:
description: AllowPort is a list of allowed ports
items:
type: integer
type: array
uniqueItems: false
insecure_allow_all:
description: InsecureAllowAll allows all outbound network connections
type: boolean
type: object
pkg_api_v1.UpdateRegistryRequest:
description: Request containing registry configuration updates
properties:
allow_private_ip:
description: Allow private IP addresses for registry URL or API URL
type: boolean
api_url:
description: MCP Registry API URL
type: string
auth:
$ref: '#/components/schemas/pkg_api_v1.UpdateRegistryAuthRequest'
local_path:
description: Local registry file path
type: string
url:
description: Registry URL (for remote registries)
type: string
type: object
permissions.NetworkPermissions:
description: Network defines network permissions
properties:
inbound:
$ref: '#/components/schemas/permissions.InboundNetworkPermissions'
mode:
description: 'Mode specifies the network mode for the container (e.g., "host", "bridge", "none")
When empty, the default container runtime network mode is used'
type: string
outbound:
$ref: '#/components/schemas/permissions.OutboundNetworkPermissions'
type: object
model.Icon:
properties:
mimeType:
example: image/png
type: string
sizes:
items:
type: string
type: array
uniqueItems: false
src:
example: https://example.com/icon.png
format: uri
maxLength: 255
type: string
theme:
type: string
type: object
model.ArgumentType:
enum:
- positional
- named
example: positional
type: string
x-enum-varnames:
- ArgumentTypePositional
- ArgumentTypeNamed
pkg_api_v1.registryListResponse:
description: Response containing a list of registries
properties:
registries:
description: List of registries
items:
$ref: '#/components/schemas/pkg_api_v1.registryInfo'
type: array
uniqueItems: false
type: object
v0.ServerJSON:
properties:
$schema:
example: https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json
format: uri
minLength: 1
type: string
_meta:
$ref: '#/components/schemas/v0.ServerMeta'
description:
example: MCP server providing weather data and forecasts via OpenWeatherMap API
maxLength: 100
minLength: 1
type: string
icons:
items:
$ref: '#/components/schemas/model.Icon'
type: array
uniqueItems: false
name:
example: io.github.user/weather
maxLength: 200
minLength: 3
pattern: ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$
type: string
packages:
items:
$ref: '#/components/schemas/model.Package'
type: array
uniqueItems: false
remotes:
items:
$ref: '#/components/schemas/model.Transport'
type: array
uniqueItems: false
repository:
$ref: '#/components/schemas/model.Repository'
title:
example: Weather API
maxLength: 100
minLength: 1
type: string
version:
example: 1.0.2
maxLength: 255
minLength: 1
type: string
websiteUrl:
example: https://modelcontextprotocol.io/examples
format: uri
type: string
type: object
registry.RemoteServerMetadata:
description: Remote server details (if it's a remote server)
properties:
custom_metadata:
additionalProperties: {}
description: CustomMetadata allows for additional user-defined metadata
type: object
description:
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'
items:
$ref: '#/components/schemas/registry.EnvVar'
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'
items:
$ref: '#/components/schemas/registry.Header'
type: array
uniqueItems: false
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'
type: string
oauth_config:
$ref: '#/components/schemas/registry.OAuthConfig'
overview:
description: 'Overview is a longer Markdown-formatted description for web display.
Unlike the Description field (limited to 500 chars), this supports
full Markdown and is intended for rich rendering on catalog pages.'
type: string
proxy_port:
description: 'ProxyPort is the port for the HTTP proxy to listen on (host port)
If not specified, a random available port will be assigned'
type: integer
repository_url:
description: RepositoryURL is the URL to the source code repository for the server
type: string
stateless:
description: Stateless indicates the server only supports POST (no SSE/GET)
type: boolean
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
title:
description: 'Title is an optional human-readable display name for the server.
If not provided, the Name field is used for display purposes.'
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: '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
pkg_api_v1.registryInfo:
description: Basic information about a registry
properties:
auth_config:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig'
auth_status:
description: 'AuthStatus is one of: "none", "configured", "authenticated".
Intentionally omits omitempty so clients always receive the field,
even when the value is "none" (the zero-value equivalent).'
type: string
auth_type:
description: 'AuthType is "oauth", "bearer" (future), or empty string when no auth.
Intentionally omits omitempty so clients can distinguish "no auth
configured" (empty string) from "field missing" without extra logic.'
type: string
last_updated:
description: Last updated timestamp
type: string
name:
description: Name of the registry
type: string
server_count:
description: Number of servers in the registry
type: integer
source:
description: Source of the registry (URL, file path, or empty string for built-in)
type: string
type:
$ref: '#/components/schemas/pkg_api_v1.RegistryType'
version:
description: Version of the registry schema
type: string
type: object
model.Argument:
properties:
choices:
items:
type: string
type: array
uniqueItems: false
default:
type: string
description:
type: string
format:
$ref: '#/components/schemas/model.Format'
isRepeated:
type: boolean
isRequired:
type: boolean
isSecret:
type: boolean
name:
example: --port
type: string
placeholder:
type: string
type:
$ref: '#/components/schemas/model.ArgumentType'
value:
type: string
valueHint:
example: file_path
type: string
variables:
additionalProperties:
$ref: '#/components/schemas/model.Input'
type: object
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'
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
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'
type: string
oauth_params:
additionalProperties:
type: string
description: 'OAuthParams contains additional OAuth parameters to include in the authorization request
These are server-specific parameters like "prompt", "response_mode", etc.'
type: object
resource:
description: Resource is the OAuth 2.0 resource indicator (RFC 8707)
type: string
scopes:
description: '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
pkg_api_v1.RegistryType:
description: Type of registry (file, url, or default)
enum:
- file
- url
- api
- default
type: string
x-enum-varnames:
- RegistryTypeFile
- RegistryTypeURL
- RegistryTypeAPI
- RegistryTypeDefault
pkg_api_v1.getServerResponse:
description: Response containing server details
properties:
is_remote:
description: Indicates if this is a remote server
type: boolean
remote_server:
$ref: '#/components/schemas/registry.RemoteServerMetadata'
server:
$ref: '#/components/schemas/registry.ImageMetadata'
type: object
github_com_stacklok_toolhive-core_registry_types.Registry:
description: Full registry data
properties:
groups:
description: Groups is a slice of group definitions containing related MCP servers
items:
$ref: '#/components/schemas/registry.Group'
type: array
uniqueItems: false
last_updated:
description: LastUpdated is the timestamp when the registry was last updated, in RFC3339 format
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'
type: object
servers:
additionalProperties:
$ref: '#/components/schemas/registry.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
model.Status:
enum:
- active
- deprecated
- deleted
type: string
x-enum-varnames:
- StatusActive
- StatusDeprecated
- StatusDeleted
pkg_api_v1.getRegistryResponse:
description: Response containing registry details
properties:
auth_config:
$ref: '#/components/schemas/github_com_stacklok_toolhive_pkg_registry.OAuthPublicConfig'
auth_status:
description: 'AuthStatus is one of: "none", "configured", "authenticated".
Intentionally omits omitempty — see registryInfo for rationale.'
type: string
auth_type:
description: 'AuthType is "oauth", "bearer" (future), or empty string when no auth.
Intentionally omits omitempty — see registryInfo for rationale.'
type: string
last_updated:
description: Last updated timestamp
type: string
name:
description: Name of the registry
type: string
registry:
$ref: '#/components/schemas/github_com_stacklok_toolhive-core_registry_types.Registry'
server_count:
description: Number of servers in the registry
type: integer
source:
description: Source of the registry (URL, file path, or empty string for built-in)
type: string
type:
$ref: '#/components/schemas/pkg_api_v1.RegistryType'
version:
description: Version of the registry schema
type: string
type: object
registry.Metadata:
description: Metadata contains additional information about the server such as popularity metrics
properties:
kubernetes:
$ref: '#/components/schemas/registry.KubernetesMetadata'
last_updated:
description: LastUpdated is the timestamp when the server was last updated, in RFC3339 format
type: string
stars:
description: Stars represents the popularity rating or number of stars for the server
type: integer
type: object
pkg_api_v1.registryErrorResponse:
description: Structured error response returned by registry endpoints
properties:
code:
description: Code is a machine-readable error code (e.g. "not_found", "registry_auth_required")
type: string
message:
description: Message is a human-readable description of the error
type: string
type: object
registry.KubernetesMetadata:
description: 'Kubernetes contains Kubernetes-specific metadata when the MCP server is deployed in a cluster.
This field is optional and only populated when:
- The server is served from ToolHive Registry Server
- The server was auto-discovered from a Kubernetes deployment
- The Kubernetes resource has the required registry annotations'
properties:
image:
description: Image is the container image used by the Kubernetes workload (applicable to MCPServer)
type: string
kind:
description: Kind is the Kubernetes resource kind (e.g., MCPServer, VirtualMCPServer, MCPRemoteProxy)
type: string
name:
description: Name is the Kubernetes resource name
type: string
namespace:
description: Namespace is the Kubernetes namespace where the resource is deployed
type: string
transport:
description: Transport is the transport type configured for the Kubernetes workload (applicable to MCPServer)
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stacklok/refs/heads/main/openapi/stacklok-registry-api-openapi.yml