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.

Procedure
  • Set both of the following configuration properties:

    apicurio.features.experimental.enabled=true
    apicurio.mcp-registry.enabled=true

    Setting apicurio.agents.enabled=true instead 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.

Table 1. MCP Registry API operations
Operation Method and path Behavior

Publish a server definition

POST /apis/mcp-registry/v0.1/publish

Maps the reverse-DNS name, for example io.github.example/weather, to group io.github.example and artifact ID weather, with type MCP_SERVER. Validates the original JSON against the pinned upstream 2025-12-11 server schema and applies the configured Apicurio Registry rules.

Read a server version

GET /apis/mcp-registry/v0.1/servers/{serverName}/versions/{version}

Returns one published version. The serverName path segment is the URL-encoded server name, for example io.github.example%2Fweather.

List server versions

GET /apis/mcp-registry/v0.1/servers

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.

Example read request
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:

Example single-version response
{
  "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 updatedCount and the updated servers.

  • DELETE is a soft deletion: it returns HTTP 200 with status deleted and retains content and history. Use include_deleted=true to inspect a deleted record, or PATCH its status to restore it. Permanent deletion is only available through the native v3 API, subject to apicurio.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 $schema URL 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.