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

registry

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

Payload

Content type

application/json

{ }

Response samples

200
400
401
404

Content type

application/json

{"_meta": {"io.modelcontextprotocol.registry/official": {"isLatest": true,
"publishedAt": "2019-08-24T14:15:22Z",
"status": "active",
"statusChangedAt": "2019-08-24T14:15:22Z",
"statusMessage": "string",
"updatedAt": "2019-08-24T14:15:22Z"
}
},
"server": {"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"_meta": {"io.modelcontextprotocol.registry/publisher-provided": {"property1": null,
"property2": null
}
},
"description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
"icons": [{"mimeType": "image/png",
"sizes": ["string"
],
"src": "https://example.com/icon.png",
"theme": "string"
}
],
"name": "io.github.user/weather",
"packages": [{"environmentVariables": [{"name": "SOME_VARIABLE"
}
],
"fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
"identifier": "@modelcontextprotocol/server-brave-search",
"packageArguments": [{"isRepeated": true,
"name": "--port",
"type": "positional",
"valueHint": "file_path"
}
],
"registryBaseUrl": "https://registry.npmjs.org",
"registryType": "npm",
"runtimeArguments": [{"isRepeated": true,
"name": "--port",
"type": "positional",
"valueHint": "file_path"
}
],
"runtimeHint": "npx",
"transport": {"headers": [{"name": "SOME_VARIABLE"
}
],
"type": "stdio",
"url": "https://api.example.com/mcp",
"variables": {"property1": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
},
"property2": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
}
}
},
"version": "1.0.2"
}
],
"remotes": [{"headers": [{"name": "SOME_VARIABLE"
}
],
"type": "stdio",
"url": "https://api.example.com/mcp",
"variables": {"property1": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
},
"property2": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
}
}
}
],
"repository": {"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9",
"source": "github",
"subfolder": "src/everything",
"url": "https://github.com/modelcontextprotocol/servers"
},
"title": "Weather API",
"version": "1.0.2",
"websiteUrl": "https://modelcontextprotocol.io/examples"
}
}

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

Payload

Content type

application/json

{ }

Response samples

200
400
401
404

Content type

application/json

{"metadata": {"count": 0,
"nextCursor": "string"
},
"servers": [{"_meta": {"io.modelcontextprotocol.registry/official": {"isLatest": true,
"publishedAt": "2019-08-24T14:15:22Z",
"status": "active",
"statusChangedAt": "2019-08-24T14:15:22Z",
"statusMessage": "string",
"updatedAt": "2019-08-24T14:15:22Z"
}
},
"server": {"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"_meta": {"io.modelcontextprotocol.registry/publisher-provided": {"property1": null,
"property2": null
}
},
"description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
"icons": [{"mimeType": "image/png",
"sizes": ["string"
],
"src": "https://example.com/icon.png",
"theme": "string"
}
],
"name": "io.github.user/weather",
"packages": [{"environmentVariables": [{"name": "SOME_VARIABLE"
}
],
"fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
"identifier": "@modelcontextprotocol/server-brave-search",
"packageArguments": [{"isRepeated": true,
"name": "--port",
"type": "positional",
"valueHint": "file_path"
}
],
"registryBaseUrl": "https://registry.npmjs.org",
"registryType": "npm",
"runtimeArguments": [{"isRepeated": true,
"name": "--port",
"type": "positional",
"valueHint": "file_path"
}
],
"runtimeHint": "npx",
"transport": {"headers": [{"name": "SOME_VARIABLE"
}
],
"type": "stdio",
"url": "https://api.example.com/mcp",
"variables": {"property1": {"choices": [null
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
},
"property2": {"choices": [null
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
}
}
},
"version": "1.0.2"
}
],
"remotes": [{"headers": [{"name": "SOME_VARIABLE"
}
],
"type": "stdio",
"url": "https://api.example.com/mcp",
"variables": {"property1": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
},
"property2": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
}
}
}
],
"repository": {"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9",
"source": "github",
"subfolder": "src/everything",
"url": "https://github.com/modelcontextprotocol/servers"
},
"title": "Weather API",
"version": "1.0.2",
"websiteUrl": "https://modelcontextprotocol.io/examples"
}
}
]
}

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

Payload

Content type

application/json

{ }

Response samples

200
400
401
404

Content type

application/json

{"metadata": {"count": 0,
"nextCursor": "string"
},
"servers": [{"_meta": {"io.modelcontextprotocol.registry/official": {"isLatest": true,
"publishedAt": "2019-08-24T14:15:22Z",
"status": "active",
"statusChangedAt": "2019-08-24T14:15:22Z",
"statusMessage": "string",
"updatedAt": "2019-08-24T14:15:22Z"
}
},
"server": {"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"_meta": {"io.modelcontextprotocol.registry/publisher-provided": {"property1": null,
"property2": null
}
},
"description": "MCP server providing weather data and forecasts via OpenWeatherMap API",
"icons": [{"mimeType": "image/png",
"sizes": ["string"
],
"src": "https://example.com/icon.png",
"theme": "string"
}
],
"name": "io.github.user/weather",
"packages": [{"environmentVariables": [{"name": "SOME_VARIABLE"
}
],
"fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
"identifier": "@modelcontextprotocol/server-brave-search",
"packageArguments": [{"isRepeated": true,
"name": "--port",
"type": "positional",
"valueHint": "file_path"
}
],
"registryBaseUrl": "https://registry.npmjs.org",
"registryType": "npm",
"runtimeArguments": [{"isRepeated": true,
"name": "--port",
"type": "positional",
"valueHint": "file_path"
}
],
"runtimeHint": "npx",
"transport": {"headers": [{"name": "SOME_VARIABLE"
}
],
"type": "stdio",
"url": "https://api.example.com/mcp",
"variables": {"property1": {"choices": [null
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
},
"property2": {"choices": [null
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
}
}
},
"version": "1.0.2"
}
],
"remotes": [{"headers": [{"name": "SOME_VARIABLE"
}
],
"type": "stdio",
"url": "https://api.example.com/mcp",
"variables": {"property1": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
},
"property2": {"choices": ["string"
],
"default": "string",
"description": "string",
"format": "string",
"isRequired": true,
"isSecret": true,
"placeholder": "string",
"value": "string"
}
}
}
],
"repository": {"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9",
"source": "github",
"subfolder": "src/everything",
"url": "https://github.com/modelcontextprotocol/servers"
},
"title": "Weather API",
"version": "1.0.2",
"websiteUrl": "https://modelcontextprotocol.io/examples"
}
}
]
}

skills

Get latest skill version

Get the latest version of a skill by namespace and name.

Authorizations:

BearerAuth

path Parameters

registryName required	string Registry name
namespace required	string Skill namespace (reverse-DNS)
name required	string Skill name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"_meta": {"property1": null,
"property2": null
},
"allowedTools": ["string"
],
"compatibility": "string",
"description": "string",
"icons": [{"label": "string",
"size": "string",
"src": "string",
"type": "string"
}
],
"license": "string",
"metadata": {"property1": null,
"property2": null
},
"name": "string",
"namespace": "string",
"packages": [{"commit": "string",
"digest": "string",
"identifier": "string",
"mediaType": "string",
"ref": "string",
"registryType": "string",
"subfolder": "string",
"url": "string"
}
],
"repository": {"type": "string",
"url": "string"
},
"status": "string",
"title": "string",
"version": "string"
}

Get specific skill version

Get a specific version of a skill.

Authorizations:

BearerAuth

path Parameters

registryName required	string Registry name
namespace required	string Skill namespace (reverse-DNS)
name required	string Skill name
version required	string Skill version

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"_meta": {"property1": null,
"property2": null
},
"allowedTools": ["string"
],
"compatibility": "string",
"description": "string",
"icons": [{"label": "string",
"size": "string",
"src": "string",
"type": "string"
}
],
"license": "string",
"metadata": {"property1": null,
"property2": null
},
"name": "string",
"namespace": "string",
"packages": [{"commit": "string",
"digest": "string",
"identifier": "string",
"mediaType": "string",
"ref": "string",
"registryType": "string",
"subfolder": "string",
"url": "string"
}
],
"repository": {"type": "string",
"url": "string"
},
"status": "string",
"title": "string",
"version": "string"
}

List skill versions

List all versions of a skill.

Authorizations:

BearerAuth

path Parameters

registryName required	string Registry name
namespace required	string Skill namespace (reverse-DNS)
name required	string Skill name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"metadata": {"count": 0,
"nextCursor": "string"
},
"skills": [{"_meta": {"property1": null,
"property2": null
},
"allowedTools": ["string"
],
"compatibility": "string",
"description": "string",
"icons": [{"label": "string",
"size": "string",
"src": "string",
"type": "string"
}
],
"license": "string",
"metadata": {"property1": null,
"property2": null
},
"name": "string",
"namespace": "string",
"packages": [{"commit": "string",
"digest": "string",
"identifier": "string",
"mediaType": "string",
"ref": "string",
"registryType": "string",
"subfolder": "string",
"url": "string"
}
],
"repository": {"type": "string",
"url": "string"
},
"status": "string",
"title": "string",
"version": "string"
}
]
}

List skills in registry

List skills in a registry (paginated, latest versions).

Authorizations:

BearerAuth

path Parameters

registryName

required

string

Registry name

query Parameters

search	string Filter by name/description substring
status	string Filter by status (comma-separated, e.g. active,deprecated)
limit	integer Max results (default 50, max 100)
cursor	string Pagination cursor

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
500

Content type

application/json

{"metadata": {"count": 0,
"nextCursor": "string"
},
"skills": [{"_meta": {"property1": null,
"property2": null
},
"allowedTools": ["string"
],
"compatibility": "string",
"description": "string",
"icons": [{"label": "string",
"size": "string",
"src": "string",
"type": "string"
}
],
"license": "string",
"metadata": {"property1": null,
"property2": null
},
"name": "string",
"namespace": "string",
"packages": [{"commit": "string",
"digest": "string",
"identifier": "string",
"mediaType": "string",
"ref": "string",
"registryType": "string",
"subfolder": "string",
"url": "string"
}
],
"repository": {"type": "string",
"url": "string"
},
"status": "string",
"title": "string",
"version": "string"
}
]
}

system

Health check

Check if the registry API is healthy

Responses

Response samples

200

Content type

application/json

{"status": "healthy"
}

OpenAPI specification

Get the OpenAPI 3.1.0 specification for this API

Responses

Response samples

200
500

Content type

application/json

{ }

Readiness check

Check if the registry API is ready to serve requests

Responses

Response samples

200
503

Content type

application/json

{"status": "ready"
}

Version information

Get version information about the registry API

Responses

Response samples

200

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"
}

v1

Create or update registry

Create a new registry or update an existing one

path Parameters

name

required

string

Registry Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
201
400
403
500

Content type

application/json

{"claims": {"property1": null,
"property2": null
},
"createdAt": "string",
"creationType": "API",
"name": "string",
"sources": ["string"
],
"updatedAt": "string"
}

Create or update source

Create a new source or update an existing one

path Parameters

name

required

string

Source Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
201
400
403
500

Content type

application/json

{"claims": {"property1": null,
"property2": null
},
"createdAt": "string",
"creationType": "API",
"filterConfig": {"names": {"exclude": ["string"
],
"include": ["string"
]
},
"tags": {"exclude": ["string"
],
"include": ["string"
]
}
},
"format": "string",
"name": "string",
"sourceConfig": null,
"sourceType": "git",
"syncSchedule": "string",
"syncStatus": {"attemptCount": 0,
"lastAttempt": "string",
"lastSyncTime": "string",
"message": "string",
"phase": "string",
"serverCount": 0
},
"type": "string",
"updatedAt": "string"
}

Delete published entry

Delete a published entry version

path Parameters

type required	string Entry Type (server or skill)
name required	string Entry Name
version required	string Version

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

400
404
500

Content type

application/json

{"property1": "string",
"property2": "string"
}

Delete registry

Delete a registry by name

path Parameters

name

required

string

Registry Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

400
403
404
500

Content type

application/json

{"property1": "string",
"property2": "string"
}

Delete source

Delete a source by name

path Parameters

name

required

string

Source Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

400
403
404
409
500

Content type

application/json

{"property1": "string",
"property2": "string"
}

Get registry

Get a registry by name

path Parameters

name

required

string

Registry Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"claims": {"property1": null,
"property2": null
},
"createdAt": "string",
"creationType": "API",
"name": "string",
"sources": ["string"
],
"updatedAt": "string"
}

Get source

Get a source by name

path Parameters

name

required

string

Source Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"claims": {"property1": null,
"property2": null
},
"createdAt": "string",
"creationType": "API",
"filterConfig": {"names": {"exclude": ["string"
],
"include": ["string"
]
},
"tags": {"exclude": ["string"
],
"include": ["string"
]
}
},
"format": "string",
"name": "string",
"sourceConfig": null,
"sourceType": "git",
"syncSchedule": "string",
"syncStatus": {"attemptCount": 0,
"lastAttempt": "string",
"lastSyncTime": "string",
"message": "string",
"phase": "string",
"serverCount": 0
},
"type": "string",
"updatedAt": "string"
}

List registries

List all registries

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
500

Content type

application/json

{"registries": [{"claims": {"property1": null,
"property2": null
},
"createdAt": "string",
"creationType": "API",
"name": "string",
"sources": ["string"
],
"updatedAt": "string"
}
]
}

List registry entries

List all entries for a registry

path Parameters

name

required

string

Registry Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"entries": [{"entryType": "string",
"name": "string",
"sourceName": "string",
"version": "string"
}
]
}

List source entries

List all entries for a source

path Parameters

name

required

string

Source Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
400
404
500

Content type

application/json

{"entries": [{"claims": {"property1": null,
"property2": null
},
"entryType": "string",
"name": "string",
"versions": [{"createdAt": "string",
"description": "string",
"title": "string",
"updatedAt": "string",
"version": "string"
}
]
}
]
}

List sources

List all sources

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
500

Content type

application/json

{"sources": [{"claims": {"property1": null,
"property2": null
},
"createdAt": "string",
"creationType": "API",
"filterConfig": {"names": {"exclude": ["string"
],
"include": ["string"
]
},
"tags": {"exclude": ["string"
],
"include": ["string"
]
}
},
"format": "string",
"name": "string",
"sourceConfig": null,
"sourceType": "git",
"syncSchedule": "string",
"syncStatus": {"attemptCount": 0,
"lastAttempt": "string",
"lastSyncTime": "string",
"message": "string",
"phase": "string",
"serverCount": 0
},
"type": "string",
"updatedAt": "string"
}
]
}

Publish entry

Publish a new server or skill entry. Exactly one of 'server' or 'skill' must be provided.

Request Body schema: application/json
required

Entry to publish (server or skill)

One of

object

Responses

Request samples

Payload

Content type

application/json

Example

{ }

Response samples

201
400
409
500

Content type

application/json

{ }

Update entry claims

Update claims for a published entry name

path Parameters

type required	string Entry Type (server or skill)
name required	string Entry Name

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

400
501

Content type

application/json

{"property1": "string",
"property2": "string"
}