diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 605f759..2ec6244 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -123,7 +123,7 @@ For example, a minimal catalog listing three AI artifacts: { "identifier": "urn:air:example.com:mcp:weather", "type": "application/mcp-server-card+json", - "url": "https://api.example.com/.well-known/mcp/server-card.json" + "url": "https://api.example.com/mcp/server-card" }, { "identifier": "urn:air:example.com:a2a:research", @@ -1389,7 +1389,7 @@ artifact types including a nested catalog packaging related artifacts: "identifier": "urn:air:acme.com:server:finance-mcp", "version": "1.4.0", "type": "application/mcp-server-card+json", - "url": "https://api.acme-corp.com/.well-known/mcp/server-card.json", + "url": "https://api.acme-corp.com/mcp/server-card", "description": "MCP server with finance tools.", "tags": ["finance", "mcp"], "updatedAt": "2026-03-15T10:00:00Z" @@ -1411,7 +1411,7 @@ artifact types including a nested catalog packaging related artifacts: { "identifier": "urn:air:acme.com:server:finance-mcp", "type": "application/mcp-server-card+json", - "url": "https://api.acme-corp.com/.well-known/mcp/server-card.json" + "url": "https://api.acme-corp.com/mcp/server-card" }, { "identifier": "urn:air:acme.com:data:market-2026q1", @@ -1519,7 +1519,7 @@ containing both protocol-specific entries: { "identifier": "urn:air:acme.com:agent:finance:mcp", "type": "application/mcp-server-card+json", - "url": "https://api.acme-corp.com/.well-known/mcp/server-card.json" + "url": "https://api.acme-corp.com/mcp/server-card" }, { "identifier": "urn:air:acme.com:agent:finance:a2a", @@ -1745,167 +1745,129 @@ Both approaches can coexist. A tooling bridge converts between them losslessly, allowing simple consumers to work with the logical format while infrastructure-oriented deployments leverage OCI distribution. -# Mapping to MCP Registry server.json +# Mapping to MCP Servers -This appendix describes how the MCP Registry `server.json` format -(see [modelcontextprotocol/registry](https://github.com/modelcontextprotocol/registry)) -relates to AI Catalog, enabling MCP servers to be discovered alongside -other AI artifacts through a unified catalog. - -> **Note:** The MCP ecosystem defines two distinct metadata documents -> for servers. The **Registry `server.json`** is an installable package -> descriptor (package coordinates, transports, environment variables). -> The **MCP Server Card** ([SEP-1649](#relationship-to-mcp-server-cards-sep-1649)) -> is a runtime discovery document at `/.well-known/mcp/server-card.json` -> describing capabilities, tools, and authentication. An AI Catalog -> entry can reference either artifact depending on the use case — use -> `server.json` for installable packages and Server Cards for -> connectable HTTP endpoints. +This appendix describes how **remote (HTTP-connectable) MCP servers** +map to AI Catalog, enabling them to be discovered alongside other AI +artifacts through a unified catalog. The documented, supported path is +to reference each server's **MCP Server Card** +([SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) +as the artifact content of a Catalog Entry. ## Overview -The MCP Registry defines a `server.json` format for describing MCP -servers. Each `server.json` document captures everything needed to -install, configure, and connect to a single MCP server: package -coordinates (npm, PyPI, NuGet, OCI), remote endpoints (streamable-http, -SSE), transport configuration, environment variables, and CLI arguments. +An MCP Server Card is a static discovery document for an individual +HTTP-based MCP server, describing its identity and how to connect to it. +A Catalog Entry references the card wherever the server publishes it, as +in the examples below. See +[SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) +for the Server Card's schema, fields, and hosting conventions. + +In AI Catalog terms, the Server Card is the **artifact content** — the +native metadata that a Catalog Entry references via its `url`, declared +with the known type `application/mcp-server-card+json`. The AI Catalog +does not duplicate or redefine Server Card fields; it provides the +discovery and trust layer that the Server Card does not address. -In AI Catalog terms, a `server.json` document is the **artifact -content** — the native metadata that a Catalog Entry references. The -AI Catalog does not duplicate or redefine `server.json` fields. -Instead, it provides the discovery and trust layer that `server.json` -does not address. +AI Catalog and MCP Server Cards address different layers of discovery: + +MCP Server Card (per-server) +: What does this specific MCP server offer? What transport does it + use? What tools and resources are available? What authentication + is required? + +AI Catalog (cross-artifact) +: What artifacts does this domain offer? Who published them? Can I + trust them? What other artifact types are available alongside MCP + servers? ## Conceptual Mapping -| MCP `server.json` | AI Catalog Equivalent | +| MCP Server Card | AI Catalog Equivalent | |:---|:---| -| `server.json` document (whole file) | Artifact content via entry `url` or `data` | -| `name` (reverse-DNS identifier) | Entry `identifier` (mapped to URI form) | -| `title` | Stays in the artifact (`server.json` carries its own `title`); entry `displayName` is omitted unless the artifact lacks a name | -| `description` | Entry `description` | -| `version` | Entry `version` | -| `repository` | Entry `metadata.repository` | -| `packages[]` (npm, pypi, nuget, oci) | Inside the artifact — not surfaced in catalog | -| `remotes[]` (streamable-http, sse) | Inside the artifact — not surfaced in catalog | -| `environmentVariables[]` | Inside the artifact — not surfaced in catalog | -| `_meta` | Entry `metadata` for catalog-level hints; otherwise stays in artifact | -| *(not in server.json)* | Entry `publisher` | -| *(not in server.json)* | Entry `trustManifest` (identity, attestations, provenance) | -| *(not in server.json)* | Entry `tags` for cross-artifact discovery | -| MCP Registry (centralized service) | AI Catalog (decentralized, any URL) | - -## Separation of Concerns - -The `server.json` format and AI Catalog address different concerns: - -server.json (Operational) -: How do I install this server? What packages, transports, arguments, - and environment variables does it need? - -AI Catalog (Discovery + Trust) -: What servers exist? Who published them? Can I trust them? Where is - their metadata? - -This separation means the AI Catalog entry is thin — it points at the -`server.json` and adds only what `server.json` lacks: publisher -identity, trust verification, and cross-ecosystem discoverability. +| Server Card document (whole file) | Artifact content via entry `url` (type `application/mcp-server-card+json`) or `data` | +| Server `name` (reverse-DNS identifier) | Entry `identifier` (mapped to the `urn:air:{publisher}:{namespace}:{name}` URN form — e.g. `urn:air:example.com:mcp:finance-server`) | +| `title` | Stays in the Server Card (which carries its own `title`); entry `displayName` is omitted unless the artifact lacks a name | +| `description` | Stays in the Server Card (which carries its own `description`); entry `description` is omitted to avoid duplicating a value that can drift | +| `version` | Stays in the Server Card (which carries its own `version`); entry `version` is omitted to avoid duplicating a value that can drift (a remote MCP server serves one Server Card, so a catalog never lists multiple versions of it) | +| transport / capabilities / tools / resources / auth | Inside the Server Card — not surfaced in the catalog | +| `repository` | Stays in the Server Card (which carries its own `repository`); omitted from the entry to avoid duplicating a value that can drift — catalog-level source/provenance links surface through the Trust Manifest when needed | +| *(not in the Server Card)* | Entry `publisher` | +| *(not in the Server Card)* | Entry `trustManifest` (identity, attestations, provenance) | +| *(not in the Server Card)* | Entry `tags` for cross-artifact discovery | ## MCP Server as Catalog Entry -An MCP server listed in the Registry maps to a Catalog Entry whose -`url` points to the `server.json` document and whose `type` -reflects the Registry format: +A remote MCP server maps to a Catalog Entry whose `url` points to the +server's Server Card and whose `type` is the known type +`application/mcp-server-card+json`: ```json { - "identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search", - "version": "1.0.2", + "identifier": "urn:air:example.com:mcp:finance-server", "type": "application/mcp-server-card+json", - "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", - "description": "MCP server for Brave Search API integration", - "tags": ["search", "brave", "web"], + "url": "https://api.acme-corp.com/mcp/server-card", + "tags": ["finance", "mcp"], "publisher": { - "identifier": "did:web:modelcontextprotocol.io", - "displayName": "Model Context Protocol" + "identifier": "did:web:acme-corp.com", + "displayName": "Acme Financial Corp" }, "trustManifest": { - "identity": "did:web:anonymous.modelcontextprotocol.io:mcp:brave-search", + "identity": "urn:air:example.com:mcp:finance-server", "attestations": [ { "type": "publisher-identity", - "uri": "https://registry.modelcontextprotocol.io/certs/publisher.jwt", - "description": "Verifies did:web:modelcontextprotocol.io as publisher" - } - ], - "provenance": [ + "uri": "https://trust.acme-corp.com/certs/publisher.jwt" + }, { - "relation": "publishedFrom", - "sourceId": "https://github.com/modelcontextprotocol/servers", - "registryUri": "https://registry.npmjs.org" + "type": "SOC2-Type2", + "uri": "https://trust.acme-corp.com/reports/soc2.pdf", + "digest": "sha256:a1b2c3d4e5f6" } ] - }, - "metadata": { - "repository": "https://github.com/modelcontextprotocol/servers" - }, - "updatedAt": "2026-03-15T10:00:00Z" + } } ``` -The `url` points to the complete `server.json`. A client fetches the -catalog entry for discovery and trust evaluation, then retrieves the -`server.json` for operational details (packages, transports, env vars). +> **Note on `type`:** The `type` member is an open-text type identifier +> ([ADR 0014](https://github.com/Agent-Card/ai-catalog/blob/main/adr/0014-media-type-to-type.md)); +> any string is accepted, with a recommended set of "known types." The +> known type for an MCP server referenced by its Server Card is +> `application/mcp-server-card+json`. -> **Note:** This example uses `application/json` because the MCP -> Registry has not registered a dedicated media type for `server.json`. -> When referencing an MCP Server Card (SEP-1649) instead, use -> `application/mcp-server-card+json` — see -> [Relationship to MCP Server Cards](#relationship-to-mcp-server-cards-sep-1649). +## MCP Servers as an AI Catalog -## MCP Registry as AI Catalog - -The MCP Registry — a centralized index of MCP servers — can be -represented as an AI Catalog. This enables clients that understand -`application/ai-catalog+json` to discover MCP servers alongside A2A -agents, skills, and other artifacts: +A domain that hosts remote MCP servers can publish them as an AI Catalog, +letting clients that understand `application/ai-catalog+json` discover +those servers alongside A2A agents, skills, and other artifacts. Each +entry points to a server's Server Card: ```json { "specVersion": "1.0", "host": { - "displayName": "MCP Server Registry", - "identifier": "did:web:modelcontextprotocol.io", - "documentationUrl": "https://modelcontextprotocol.io/docs" + "displayName": "Acme MCP Servers", + "identifier": "did:web:acme-corp.com", + "documentationUrl": "https://acme-corp.com/docs" }, "entries": [ { - "identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search", - "version": "1.0.2", + "identifier": "urn:air:acme-corp.com:mcp:finance-server", "type": "application/mcp-server-card+json", - "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", - "description": "MCP server for Brave Search API integration", - "tags": ["search", "brave"] + "url": "https://api.acme-corp.com/finance/server-card", + "tags": ["finance", "mcp"] }, { - "identifier": "urn:air:modelcontextprotocol.github.io:mcp:filesystem", - "version": "1.0.2", + "identifier": "urn:air:acme-corp.com:mcp:docs-search", "type": "application/mcp-server-card+json", - "url": "https://registry.modelcontextprotocol.io/servers/filesystem/server.json", - "description": "MCP server for filesystem operations", - "tags": ["filesystem", "files"] + "url": "https://api.acme-corp.com/docs-search/server-card", + "tags": ["search", "docs"] }, { - "identifier": "urn:air:example.github.io:mcp:weather-mcp", - "version": "0.5.0", + "identifier": "urn:air:acme-corp.com:mcp:ci-cd", "type": "application/mcp-server-card+json", - "url": "https://registry.modelcontextprotocol.io/servers/weather/server.json", - "description": "Python MCP server for weather data access", - "tags": ["weather", "python"], - "publisher": { - "identifier": "did:web:example.github.io", - "displayName": "Example Corp" - } + "url": "https://api.acme-corp.com/ci-cd/server-card", + "tags": ["ci", "cd", "devops"] } ] } @@ -1913,10 +1875,9 @@ agents, skills, and other artifacts: ## Decentralized Discovery -The MCP Registry is a centralized service. AI Catalog enables -decentralized discovery: any domain can publish its MCP servers at -`/.well-known/ai-catalog.json` without registering with a central -authority. +AI Catalog enables decentralized discovery: any domain can publish its +MCP servers at `/.well-known/ai-catalog.json` without registering with a +central authority. A vendor hosting its own MCP servers can publish: @@ -1924,23 +1885,42 @@ A vendor hosting its own MCP servers can publish: https://api.acme-corp.com/.well-known/ai-catalog.json ``` -Clients and crawlers discover the catalog via the well-known URL, -find entries by `type`, and fetch the referenced artifacts for -operational details — whether those are MCP Server Cards, Registry -`server.json` documents, or other AI artifact formats. - -The centralized MCP Registry and decentralized AI Catalogs are -complementary. The registry can serve an AI Catalog as its response -format, while individual domains publish their own catalogs for -direct discovery. - -## What AI Catalog Adds to server.json - -The `server.json` format has no trust or identity layer. AI Catalog -fills this gap: +The catalog and the Server Card play two complementary roles: the +catalog is how a client *finds* a server's URL in the first place, and +the Server Card is the connection entry point it points at. They are +useful independently — a client that already knows a server's URL can +point at its Server Card directly, with no catalog traversal, while a +client starting from just a domain uses the catalog to enumerate what +that domain offers. + +Because of this, there is no single prescribed discovery ordering. +Clients wire discovery in wherever it fits their architecture — probing +a domain's catalog when it enters a session, watching outbound traffic +at an egress boundary, or connecting to a known Server Card directly. A +typical catalog-first path is: fetch `/.well-known/ai-catalog.json`, +filter entries by `type` (`application/mcp-server-card+json`) to find +MCP servers, follow an entry's `url` to its Server Card for connection +details, and connect — evaluating the Trust Manifest (when present) for +publisher identity and attestations along the way. Whatever the path, +the Server Card is advisory: a client reconciles it against the live +connection and MUST NOT treat it as authoritative for access control — +the connection itself remains the source of truth. See the Server Card +[best-practices guidance](https://github.com/modelcontextprotocol/experimental-ext-server-card) +for the range of client integration strategies. + +This separation lets AI Catalog provide the trust and cross-ecosystem +indexing layer while the MCP Server Card provides the protocol-specific +operational details. A domain with multiple MCP servers publishes one AI +Catalog listing all of them, with each entry pointing to its respective +Server Card. + +## What AI Catalog Adds + +A Server Card describes a single server but has no cross-server discovery +or trust layer. AI Catalog fills this gap: 1. **Publisher identity**: Verifiable publisher with DID or domain - anchor, absent from `server.json`. + anchor. 2. **Trust verification**: Attestations (SOC2, HIPAA, publisher identity proofs) via the Trust Manifest. 3. **Provenance**: Links to source repositories, registries, and @@ -1953,77 +1933,6 @@ fills this gap: 6. **Composability**: MCP servers can be packaged with related artifacts (A2A agents, datasets) in nested catalogs. -## Relationship to MCP Server Cards (SEP-1649) - -MCP Server Cards -([SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649)) -define a static discovery document for individual HTTP-based MCP -servers at `/.well-known/mcp/server-card.json`. A Server Card mirrors -the MCP initialization handshake response: it carries the server's -name, version, transport configuration, capabilities, authentication -requirements, and optionally the full list of tools, resources, and -prompts. - -AI Catalog and MCP Server Cards address different layers of discovery: - -MCP Server Card (per-server) -: What does this specific MCP server offer? What transport does it - use? What tools and resources are available? What authentication - is required? - -AI Catalog (cross-artifact) -: What artifacts does this domain offer? Who published them? Can I - trust them? What other artifact types are available alongside MCP - servers? - -The two mechanisms layer naturally. An AI Catalog entry for an MCP -server can reference the Server Card as its artifact content: - -```json -{ - "identifier": "urn:air:example.com:mcp:finance-server", - "type": "application/mcp-server-card+json", - "url": "https://api.acme-corp.com/.well-known/mcp/server-card.json", - "description": "MCP server for financial data and trading tools", - "tags": ["finance", "mcp"], - "publisher": { - "identifier": "did:web:acme-corp.com", - "displayName": "Acme Financial Corp" - }, - "trustManifest": { - "identity": "urn:air:example.com:mcp:finance-server", - "attestations": [ - { - "type": "publisher-identity", - "uri": "https://trust.acme-corp.com/certs/publisher.jwt" - }, - { - "type": "SOC2-Type2", - "uri": "https://trust.acme-corp.com/reports/soc2.pdf", - "digest": "sha256:a1b2c3d4e5f6" - } - ] - } -} -``` - -A client discovering MCP servers follows this flow: - -1. Fetch `/.well-known/ai-catalog.json` to discover all artifacts on - a domain (MCP servers, A2A agents, plugins, etc.). -2. Filter entries by `type` to find MCP servers. -3. Evaluate the Trust Manifest for publisher identity and attestations. -4. Fetch the Server Card at the entry's `url` for operational details - (transport, capabilities, tools, authentication). -5. Connect to the MCP server using the transport configuration from - the Server Card. - -This separation ensures that AI Catalog provides the trust and -cross-ecosystem indexing layer, while the MCP Server Card provides the -protocol-specific operational details. A domain with multiple MCP -servers publishes one AI Catalog listing all of them, with each entry -pointing to its respective Server Card. - # Mapping to Claude Code Plugins Marketplace This appendix describes how the Anthropic Claude Code Plugins