MCP Registry API (Developer Preview)
Apicurio Registry exposes an experimental Model Context Protocol (MCP) Registry API at /apis/mcp-registry/v0.1. You can use it to publish, read, list, and manage MCP server definitions, which Apicurio Registry stores as artifacts.
MCP Registry API overview
The Model Context Protocol (MCP) Registry API is an experimental Apicurio Registry API for publishing and reading MCP server definitions. It is separate from the mcp/ server module, which exposes Apicurio Registry operations as MCP tools.
This Developer Preview targets Apicurio Registry 3.4.0. The internal Java package and specification directory use v0 for the facade generation; the published upstream wire contract is explicitly v0.1. They are not separate served API versions.
Apicurio Registry stores each published server definition as an artifact of type MCP_SERVER. The reverse-DNS server name maps to a group and an artifact ID. For example, io.github.example/weather maps to group io.github.example and artifact ID weather.
Enabling the MCP Registry API
The MCP Registry API is an experimental feature, so you must enable experimental features and the API itself before Apicurio Registry serves it.
-
Set both of the following configuration properties:
apicurio.features.experimental.enabled=true apicurio.mcp-registry.enabled=trueSetting
apicurio.agents.enabled=trueinstead also enables the MCP Registry API, with the other agent discovery features.
MCP Registry API operations
The MCP Registry API provides operations to publish a server definition, read a published version, and list published server versions.
| Operation | Method and path | Behavior |
|---|---|---|
Publish a server definition |
|
Maps the reverse-DNS name, for example |
Read a server version |
|
Returns one published version. The |
List server versions |
|
Returns all published server versions, newest first. Query parameters filter the list and page through it. |
A compatibility rule can protect existing package installation and remote connection choices across versions. Package version and hash upgrades are allowed; removing or changing an existing connection or its configuration is considered backward-incompatible.
curl 'http://localhost:8080/apis/mcp-registry/v0.1/servers/io.github.example%2Fweather/versions/1.0.0'
Single-version responses and list entries separate the server definition from registry-owned metadata:
{
"server": {
"name": "io.github.example/weather",
"version": "1.0.0",
"description": "Weather forecasts"
},
"_meta": {
"io.modelcontextprotocol.registry/official": {
"status": "active",
"isLatest": true
}
}
}
The following query parameters filter the list of server versions:
version=latest-
Selects only the latest version of each server.
search-
Matches server names or descriptions.
updated_since-
Accepts an RFC 3339 timestamp and compares it with the modification timestamp of the returned version, including status changes. This incremental listing includes deleted records.
include_deleted=true-
Includes deleted records in reads that exclude them by default.
To page through results, reuse metadata.nextCursor with the same filters. Both explicit and default page limits respect apicurio.mcp-registry.max-page-size.
MCP Registry API mutation behavior and operational considerations
The following behaviors apply when you publish, update, delete, or list MCP server versions through the MCP Registry API.
-
Draft artifact versions are not published MCP records, and MCP reads exclude them.
-
Version and server-wide status updates persist status messages and update the selected versions atomically. Server-wide updates return
updatedCountand the updatedservers. -
DELETE is a soft deletion: it returns HTTP 200 with status
deletedand retains content and history. Useinclude_deleted=trueto inspect a deleted record, or PATCH its status to restore it. Permanent deletion is only available through the native v3 API, subject toapicurio.rest.deletion.artifact-version.enabled; MCP does not bypass that gate. -
The optional PUT operation returns HTTP 501, as permitted by the upstream API. Publish a new immutable version instead.
-
Input manifests are limited to 1 MiB. Validation uses the bundled schema without fetching the
$schemaURL of the publisher. -
Filtered lists scan and resolve server versions before pagination. The page-size limit bounds responses and storage batches, not total scanning work or memory. Offset cursors do not provide snapshot consistency across concurrent writes.
-
GitOps and KubernetesOps storage read from imported branch metadata and reject writes with HTTP 501.
-
Registering a server manifest does not contact the server or import its tools.
-
Status messages are descriptive, user-editable version metadata. They are not authorization or approval state; Apicurio Registry derives the lifecycle status from the version state.
