Skip to main content

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

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., \

Responses

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., \

Responses

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

Responses

Response samples

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

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

Responses

Response samples

Content type
application/json
{
  • "_meta": {
    },
  • "allowedTools": [
    ],
  • "compatibility": "string",
  • "description": "string",
  • "icons": [
    ],
  • "license": "string",
  • "metadata": {
    },
  • "name": "string",
  • "namespace": "string",
  • "packages": [
    ],
  • "repository": {
    },
  • "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

Responses

Response samples

Content type
application/json
{
  • "_meta": {
    },
  • "allowedTools": [
    ],
  • "compatibility": "string",
  • "description": "string",
  • "icons": [
    ],
  • "license": "string",
  • "metadata": {
    },
  • "name": "string",
  • "namespace": "string",
  • "packages": [
    ],
  • "repository": {
    },
  • "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

Responses

Response samples

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

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

Responses

Response samples

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

system

OpenAPI specification

Get the OpenAPI 3.1.0 specification for this API

Responses

Response samples

Content type
application/json
{ }

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
required

Registry configuration

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "claims": {
    },
  • "createdAt": "string",
  • "creationType": "API",
  • "name": "string",
  • "sources": [
    ],
  • "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
required

Source configuration

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "claims": {
    },
  • "createdAt": "string",
  • "creationType": "API",
  • "filterConfig": {
    },
  • "name": "string",
  • "sourceConfig": null,
  • "sourceType": "git",
  • "syncSchedule": "string",
  • "syncStatus": {
    },
  • "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

Responses

Response samples

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

Delete registry

Delete a registry by name

path Parameters
name
required
string

Registry Name

Responses

Response samples

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

Delete source

Delete a source by name

path Parameters
name
required
string

Source Name

Responses

Response samples

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

Get current user info

Returns the authenticated caller's identity and roles

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ],
  • "subject": "string"
}

Get entry claims

Get the claims for an API-published entry name within the managed source. Claims are stored at the entry-name level and are shared by every version of that name. Synced-source entries (git/api/file/kubernetes) are out of scope: their claims come from upstream (the source manifest or the toolhive.stacklok.dev/authz-claims annotation) and are surfaced through the /v1/sources/{name}/entries and /v1/registries/{name}/entries lists.

path Parameters
type
required
string

Entry Type (server or skill)

name
required
string

Entry Name

Responses

Response samples

Content type
application/json
{
  • "claims": {
    }
}

Get registry

Get a registry by name

path Parameters
name
required
string

Registry Name

Responses

Response samples

Content type
application/json
{
  • "claims": {
    },
  • "createdAt": "string",
  • "creationType": "API",
  • "name": "string",
  • "sources": [
    ],
  • "updatedAt": "string"
}

Get source

Get a source by name

path Parameters
name
required
string

Source Name

Responses

Response samples

Content type
application/json
{
  • "claims": {
    },
  • "createdAt": "string",
  • "creationType": "API",
  • "filterConfig": {
    },
  • "name": "string",
  • "sourceConfig": null,
  • "sourceType": "git",
  • "syncSchedule": "string",
  • "syncStatus": {
    },
  • "type": "string",
  • "updatedAt": "string"
}

List registries

List all registries

Responses

Response samples

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

List registry entries

List all entries for a registry

path Parameters
name
required
string

Registry Name

Responses

Response samples

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

List source entries

List all entries for a source

path Parameters
name
required
string

Source Name

Responses

Response samples

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

List sources

List all sources

Responses

Response samples

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

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

Content type
application/json
Example
{ }

Response samples

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
required

Claims to set

One of
object

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

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