Skip to main content

Registry API reference

API docs by Redocly

ToolHive Registry API (0.1)

Download OpenAPI specification:Download

URL: https://github.com/stacklok/toolhive License: Apache 2.0

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).

extension

Get registry

Get a registry by name

Authorizations:
BearerAuth
path Parameters
registryName
required
string

Registry Name

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "createdAt": "string",
  • "name": "string",
  • "syncStatus": {
    },
  • "type": "string",
  • "updatedAt": "string"
}

List registries

List all registries

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "registries": [
    ]
}

registry

Delete server version from specific registry

Delete a server version from a specific managed registry

Authorizations:
BearerAuth
path Parameters
registryName
required
string

Registry name

serverName
required
string

Server name (URL-encoded)

version
required
string

Version (URL-encoded)

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Get specific MCP server version in specific registry

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.

Authorizations:
BearerAuth
path Parameters
registryName
required
string

Registry name

serverName
required
string

URL-encoded server name (e.g., \

version
required
string

URL-encoded version to retrieve (e.g., \

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "_meta": {
    },
  • "server": {
    }
}

List all versions of an MCP server in specific registry

Returns all available versions for a specific MCP server from a specific registry

Authorizations:
BearerAuth
path Parameters
registryName
required
string

Registry name

serverName
required
string

URL-encoded server name (e.g., \

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "servers": [
    ]
}

List servers in specific registry

Get a list of available servers from a specific registry

Authorizations:
BearerAuth
path Parameters
registryName
required
string

Registry name

query Parameters
cursor
string

Pagination cursor for retrieving next set of results

limit
integer

Maximum number of items to return

search
string

Search servers by name (substring match)

version
string

Filter by version ('latest' for latest version, or an exact version like '1.2.3')

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "servers": [
    ]
}

Publish server to specific registry

Publish a server version to a specific managed registry

Authorizations:
BearerAuth
path Parameters
registryName
required
string

Registry name

Request Body schema: application/json
required

Server data

$schema
string <uri> non-empty
object (v0.ServerMeta)
description
string [ 1 .. 100 ] characters
Array of objects (model.Icon)
name
string [ 3 .. 200 ] characters ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$
Array of objects (model.Package)
Array of objects (model.Transport)
object (model.Repository)
title
string [ 1 .. 100 ] characters
version
string
websiteUrl
string <uri>

Responses

Request samples

Content type
application/json
{
  • "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  • "_meta": {
    },
  • "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
  • "icons": [],
  • "name": "io.github.user/weather",
  • "packages": [
    ],
  • "remotes": [
    ],
  • "repository": {},
  • "title": "Weather API",
  • "version": "1.0.2",
  • "websiteUrl": "https://modelcontextprotocol.io/examples"
}

Response samples

Content type
application/json
{
  • "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  • "_meta": {
    },
  • "description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
  • "icons": [],
  • "name": "io.github.user/weather",
  • "packages": [
    ],
  • "remotes": [
    ],
  • "repository": {},
  • "title": "Weather API",
  • "version": "1.0.2",
  • "websiteUrl": "https://modelcontextprotocol.io/examples"
}

registry-aggregated

Get specific MCP server version (aggregated)

Returns detailed information about a specific version of an MCP server from all registries. Use the special version latest to get the latest version.

Authorizations:
BearerAuth
path Parameters
serverName
required
string

URL-encoded server name (e.g., \

version
required
string

URL-encoded version to retrieve (e.g., \

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "_meta": {
    },
  • "server": {
    }
}

List all versions of an MCP server (aggregated)

Returns all available versions for a specific MCP server from all registries (aggregated view)

Authorizations:
BearerAuth
path Parameters
serverName
required
string

URL-encoded server name (e.g., \

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "servers": [
    ]
}

List servers (aggregated)

Get a list of available servers from all registries (aggregated view)

Authorizations:
BearerAuth
query Parameters
cursor
string

Pagination cursor for retrieving next set of results

limit
integer

Maximum number of items to return

search
string

Search servers by name (substring match)

version
string

Filter by version ('latest' for latest version, or an exact version like '1.2.3')

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "servers": [
    ]
}

Publish server (not supported)

Publish a server to the registry. This server does not support publishing via this endpoint. Use the registry-specific endpoint /{registryName}/v0.1/publish instead.

Authorizations:
BearerAuth
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

system

Health check

Check if the registry API is healthy

Responses

Response samples

Content type
application/json
{
  • "status": "healthy"
}

OpenAPI specification

Get the OpenAPI 3.1.0 specification for this API

Responses

Response samples

Content type
application/json
{ }

Readiness check

Check if the registry API is ready to serve requests

Responses

Response samples

Content type
application/json
{
  • "status": "ready"
}

Version information

Get version information about the registry API

Responses

Response samples

Content type
application/json
{
  • "build_date": "2025-01-15T10:30:00Z",
  • "commit": "abc123def",
  • "go_version": "go1.21.5",
  • "platform": "linux/amd64",
  • "version": "v0.1.0"
}