MCP Registry API (Developer Preview)

Apicurio Registry exposes an experimental MCP Registry API at /apis/mcp-registry/v0.1. This is separate from the mcp/ server module, which exposes Registry operations as MCP tools.

This Developer Preview targets {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.

Enable both configuration properties:

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

Publish a server definition with POST /apis/mcp-registry/v0.1/publish. The reverse-DNS name io.github.example/weather maps to group io.github.example and artifact ID weather, with type MCP_SERVER. Publishing validates the original JSON against the pinned upstream 2025-12-11 server schema and applies configured Registry rules. 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.

Read the published version using the standard URL-encoded serverName path segment:

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

List all published server versions using GET /apis/mcp-registry/v0.1/servers. Use version=latest to select only the latest version of each server. search matches names or descriptions. updated_since accepts RFC 3339 timestamps and uses the returned version’s modification timestamp, including status changes. Incremental listing includes deleted records; other reads exclude them unless include_deleted=true. Version lists are newest-first. Reuse metadata.nextCursor with the same filters. Both explicit and default limits respect apicurio.mcp-registry.max-page-size.

Mutation behavior and operational considerations

  • Draft artifact versions are not published MCP records and are excluded from MCP reads.

  • Version and server-wide status updates persist status messages and update 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/history. Use include_deleted=true to inspect it or PATCH 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.

  • Optional PUT 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 publisher’s $schema URL.

  • 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/KubernetesOps support reads 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; the lifecycle status is derived from version state.