From 8c563664915b8eee95acebd16e4f2fbb22d17f4d Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 21:28:05 +0000 Subject: [PATCH 01/14] docs(spec): update Mapping to MCP Registry server.json for ADR 0014 + ext-server-card PR #32 Reconcile the server.json mapping appendix with the current ADRs and the landing state of modelcontextprotocol/experimental-ext-server-card PR #32: - Fix the self-contradictory `type` note: examples for entries pointing at a Registry server.json now use the generic `application/json` (no known type exists for server.json), consistent with the note's own rationale. - Explain the open-text `type` model (ADR 0014) and the deliberate `application/mcp-server-card+json` vs `application/mcp-server+json` distinction (ext-server-card issue #9 / PR #18; PR #32 keeps the card value while renaming the field to `type`). - Correct SEP reference SEP-1649 -> SEP-2127 (heading, links, anchors). - Correct Server Card location prose: any unreserved URI, reserved default `/server-card` (not `.well-known`). - Note the urn:air identifier form (ADR 0015) in the conceptual mapping. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 62 +++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 605f759..9f7c121 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1755,12 +1755,13 @@ 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. +> The **MCP Server Card** ([SEP-2127](#relationship-to-mcp-server-cards-sep-2127)) +> is a runtime discovery document — hosted at any unreserved URI the +> catalog references (MCP reserves `/server-card` as +> a predictable default) — 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. ## Overview @@ -1781,7 +1782,7 @@ does not address. | MCP `server.json` | 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) | +| `name` (reverse-DNS identifier) | Entry `identifier` (mapped to the `urn:air:{publisher}:{namespace}:{name}` URN form — e.g. `urn:air:modelcontextprotocol.io:mcp:brave-search`) | | `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` | @@ -1814,14 +1815,16 @@ identity, trust verification, and cross-ecosystem discoverability. ## 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: +`url` points to the `server.json` document. Because the MCP Registry has +not registered a dedicated media type for `server.json`, the entry's +open-text `type` uses the generic `application/json` (see the note after +the example): ```json { "identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search", "version": "1.0.2", - "type": "application/mcp-server-card+json", + "type": "application/json", "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", "description": "MCP server for Brave Search API integration", "tags": ["search", "brave", "web"], @@ -1857,11 +1860,22 @@ 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:** 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 +> **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." There +> is no known type for the Registry `server.json` document, so this +> example uses the generic `application/json`. When an entry instead +> references an MCP **Server Card**, use the known type > `application/mcp-server-card+json` — see -> [Relationship to MCP Server Cards](#relationship-to-mcp-server-cards-sep-1649). +> [Relationship to MCP Server Cards](#relationship-to-mcp-server-cards-sep-2127). +> +> Note the deliberate naming distinction: the MCP Server Card extension +> uses `application/mcp-server-card+json` (not `application/mcp-server+json`) +> for the Server Card to avoid colliding with the Registry's `server.json` +> concept (modelcontextprotocol/experimental-ext-server-card issue #9 / +> PR #18). ADR 0014 makes `type` open-text, so this more precise, +> MCP-governed value is compatible with the AI Catalog's recommended +> known types. ## MCP Registry as AI Catalog @@ -1882,7 +1896,7 @@ agents, skills, and other artifacts: { "identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search", "version": "1.0.2", - "type": "application/mcp-server-card+json", + "type": "application/json", "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", "description": "MCP server for Brave Search API integration", "tags": ["search", "brave"] @@ -1890,7 +1904,7 @@ agents, skills, and other artifacts: { "identifier": "urn:air:modelcontextprotocol.github.io:mcp:filesystem", "version": "1.0.2", - "type": "application/mcp-server-card+json", + "type": "application/json", "url": "https://registry.modelcontextprotocol.io/servers/filesystem/server.json", "description": "MCP server for filesystem operations", "tags": ["filesystem", "files"] @@ -1898,7 +1912,7 @@ agents, skills, and other artifacts: { "identifier": "urn:air:example.github.io:mcp:weather-mcp", "version": "0.5.0", - "type": "application/mcp-server-card+json", + "type": "application/json", "url": "https://registry.modelcontextprotocol.io/servers/weather/server.json", "description": "Python MCP server for weather data access", "tags": ["weather", "python"], @@ -1953,14 +1967,16 @@ 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) +## Relationship to MCP Server Cards (SEP-2127) MCP Server Cards -([SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649)) +([SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) 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 +servers. A Server Card MAY be hosted at any unreserved URI the catalog +references; MCP reserves `/server-card` as a +predictable default location. 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. @@ -1983,7 +1999,7 @@ server can reference the Server Card as its artifact content: { "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", + "url": "https://api.acme-corp.com/mcp/server-card", "description": "MCP server for financial data and trading tools", "tags": ["finance", "mcp"], "publisher": { From 4a22a523d1177a2ffbc0d10becc376742445efe0 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 21:30:44 +0000 Subject: [PATCH 02/14] docs(spec): align conceptual-mapping URN example with appendix examples Use anonymous.modelcontextprotocol.io publisher in the name-row example to match the brave-search entries rendered elsewhere in the appendix. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 9f7c121..5776492 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1782,7 +1782,7 @@ does not address. | MCP `server.json` | AI Catalog Equivalent | |:---|:---| | `server.json` document (whole file) | Artifact content via entry `url` or `data` | -| `name` (reverse-DNS identifier) | Entry `identifier` (mapped to the `urn:air:{publisher}:{namespace}:{name}` URN form — e.g. `urn:air:modelcontextprotocol.io:mcp:brave-search`) | +| `name` (reverse-DNS identifier) | Entry `identifier` (mapped to the `urn:air:{publisher}:{namespace}:{name}` URN form — e.g. `urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search`) | | `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` | From 5b1b6a288e97d1d09b97d4be6ba472591ebfabe3 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 21:39:50 +0000 Subject: [PATCH 03/14] docs: refactor MCP mapping appendix to lead with Server Cards; demote server.json to experimental Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 358 +++++++++++++++--------------------- 1 file changed, 150 insertions(+), 208 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 5776492..5a5cc63 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1745,181 +1745,150 @@ 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 - -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-2127](#relationship-to-mcp-server-cards-sep-2127)) -> is a runtime discovery document — hosted at any unreserved URI the -> catalog references (MCP reserves `/server-card` as -> a predictable default) — 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. +# Mapping to MCP Servers + +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. + +> **Scope:** This mapping covers remote MCP servers described by an MCP +> Server Card. Mapping AI Catalog to the **MCP Registry's `server.json`** +> (an installable-package descriptor) is a *separate* concern that is +> **not officially documented and should be treated as experimental** at +> this stage — see +> [Experimental: Mapping to the MCP Registry (`server.json`)](#experimental-mapping-to-the-mcp-registry-server-json) +> at the end of this appendix. ## 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. It 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. A Server Card MAY be +hosted at any unreserved URI the catalog references; MCP reserves +`/server-card` as a predictable default location. + +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 the `urn:air:{publisher}:{namespace}:{name}` URN form — e.g. `urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search`) | -| `title` | Stays in the artifact (`server.json` carries its own `title`); entry `displayName` is omitted unless the artifact lacks a name | +| 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` | Entry `description` | | `version` | Entry `version` | +| transport / capabilities / tools / resources / auth | Inside the Server Card — not surfaced in the catalog | | `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. +| *(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. Because the MCP Registry has -not registered a dedicated media type for `server.json`, the entry's -open-text `type` uses the generic `application/json` (see the note after -the example): +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", + "identifier": "urn:air:example.com:mcp:finance-server", "version": "1.0.2", - "type": "application/json", - "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", - "description": "MCP server for Brave Search API integration", - "tags": ["search", "brave", "web"], + "type": "application/mcp-server-card+json", + "url": "https://api.acme-corp.com/mcp/server-card", + "description": "MCP server for financial data and trading tools", + "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." There -> is no known type for the Registry `server.json` document, so this -> example uses the generic `application/json`. When an entry instead -> references an MCP **Server Card**, use the known type -> `application/mcp-server-card+json` — see -> [Relationship to MCP Server Cards](#relationship-to-mcp-server-cards-sep-2127). -> -> Note the deliberate naming distinction: the MCP Server Card extension -> uses `application/mcp-server-card+json` (not `application/mcp-server+json`) -> for the Server Card to avoid colliding with the Registry's `server.json` -> concept (modelcontextprotocol/experimental-ext-server-card issue #9 / -> PR #18). ADR 0014 makes `type` open-text, so this more precise, -> MCP-governed value is compatible with the AI Catalog's recommended -> known types. - -## 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: +> 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 the deliberate naming +> distinction: the MCP Server Card extension uses +> `application/mcp-server-card+json` (not `application/mcp-server+json`) +> to avoid colliding with the MCP Registry's `server.json` concept +> (modelcontextprotocol/experimental-ext-server-card issue #9 / PR #18). + +## MCP Servers as an AI Catalog + +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", + "identifier": "urn:air:acme-corp.com:mcp:finance-server", "version": "1.0.2", - "type": "application/json", - "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", - "description": "MCP server for Brave Search API integration", - "tags": ["search", "brave"] + "type": "application/mcp-server-card+json", + "url": "https://api.acme-corp.com/finance/server-card", + "description": "MCP server for financial data and trading tools", + "tags": ["finance", "mcp"] }, { - "identifier": "urn:air:modelcontextprotocol.github.io:mcp:filesystem", + "identifier": "urn:air:acme-corp.com:mcp:docs-search", "version": "1.0.2", - "type": "application/json", - "url": "https://registry.modelcontextprotocol.io/servers/filesystem/server.json", - "description": "MCP server for filesystem operations", - "tags": ["filesystem", "files"] + "type": "application/mcp-server-card+json", + "url": "https://api.acme-corp.com/docs-search/server-card", + "description": "MCP server for searching internal documentation", + "tags": ["search", "docs"] }, { - "identifier": "urn:air:example.github.io:mcp:weather-mcp", + "identifier": "urn:air:acme-corp.com:mcp:ci-cd", "version": "0.5.0", - "type": "application/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" - } + "type": "application/mcp-server-card+json", + "url": "https://api.acme-corp.com/ci-cd/server-card", + "description": "MCP server for CI/CD pipeline operations", + "tags": ["ci", "cd", "devops"] } ] } @@ -1927,10 +1896,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: @@ -1938,23 +1906,31 @@ 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. +A client discovering MCP servers follows this flow: -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. +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` (`application/mcp-server-card+json`) 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. -## What AI Catalog Adds to server.json +## What AI Catalog Adds -The `server.json` format has no trust or identity layer. AI Catalog -fills this gap: +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 @@ -1967,78 +1943,44 @@ 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-2127) - -MCP Server Cards -([SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) -define a static discovery document for individual HTTP-based MCP -servers. A Server Card MAY be hosted at any unreserved URI the catalog -references; MCP reserves `/server-card` as a -predictable default location. 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: +## Experimental: Mapping to the MCP Registry (`server.json`) -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? +> **Experimental — not officially documented.** The MCP Registry's +> `server.json` format +> (see [modelcontextprotocol/registry](https://github.com/modelcontextprotocol/registry)) +> is a *different* document from the Server Card: it is an installable +> **package descriptor** (package coordinates, transports, environment +> variables, CLI arguments). Mapping AI Catalog entries directly to +> `server.json` is **not part of the documented AI Catalog ↔ MCP +> integration** above and the AI Catalog WG has not standardized it. +> There is also **no registered media type** for `server.json`. Treat the +> sketch below as experimental and subject to change; the documented path +> for cataloging MCP servers is via their Server Cards. -The two mechanisms layer naturally. An AI Catalog entry for an MCP -server can reference the Server Card as its artifact content: +An entry could, experimentally, point its `url` at a `server.json` +document. Because there is no known type for `server.json`, such an entry +would use the generic open-text `type` `application/json`: ```json { - "identifier": "urn:air:example.com:mcp:finance-server", - "type": "application/mcp-server-card+json", - "url": "https://api.acme-corp.com/mcp/server-card", - "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" - } - ] - } + "identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search", + "version": "1.0.2", + "type": "application/json", + "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", + "description": "MCP server for Brave Search API integration", + "tags": ["search", "brave", "web"] } ``` -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. +The conceptual field correspondence would mirror the Server Card mapping +above — the whole `server.json` is the referenced artifact; `name` maps +to the entry `identifier`; `description`/`version` map to the +like-named entry members; and `packages[]`, `remotes[]`, and +`environmentVariables[]` stay inside the artifact rather than being +surfaced in the catalog. The centralized MCP Registry and decentralized +AI Catalogs would be complementary: the registry could serve an AI +Catalog as its response format, while individual domains publish their +own catalogs for direct discovery. # Mapping to Claude Code Plugins Marketplace From ea3d6b6dfff8002e1c4e03e540f0232662f685a9 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 22:04:46 +0000 Subject: [PATCH 04/14] docs: drop experimental server.json section; align server-card URLs with MCP spec - Remove the 'experimental' MCP Registry server.json mapping (server.json gets a first-class treatment in a follow-up PR). - Replace stale .well-known/mcp/server-card.json example URLs with the current /server-card convention (the Server Card WG dropped the .well-known requirement for the card itself). Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 58 +++++-------------------------------- 1 file changed, 8 insertions(+), 50 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 5a5cc63..dda3fb6 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", @@ -1754,13 +1754,10 @@ 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. -> **Scope:** This mapping covers remote MCP servers described by an MCP -> Server Card. Mapping AI Catalog to the **MCP Registry's `server.json`** -> (an installable-package descriptor) is a *separate* concern that is -> **not officially documented and should be treated as experimental** at -> this stage — see -> [Experimental: Mapping to the MCP Registry (`server.json`)](#experimental-mapping-to-the-mcp-registry-server-json) -> at the end of this appendix. +A Server Card is a runtime discovery document for a single HTTP-based MCP +server (its identity and connection details). It is distinct from the MCP +Registry's `server.json` — an installable-package descriptor — which is a +separate artifact type addressed in its own appendix. ## Overview @@ -1943,45 +1940,6 @@ or trust layer. AI Catalog fills this gap: 6. **Composability**: MCP servers can be packaged with related artifacts (A2A agents, datasets) in nested catalogs. -## Experimental: Mapping to the MCP Registry (`server.json`) - -> **Experimental — not officially documented.** The MCP Registry's -> `server.json` format -> (see [modelcontextprotocol/registry](https://github.com/modelcontextprotocol/registry)) -> is a *different* document from the Server Card: it is an installable -> **package descriptor** (package coordinates, transports, environment -> variables, CLI arguments). Mapping AI Catalog entries directly to -> `server.json` is **not part of the documented AI Catalog ↔ MCP -> integration** above and the AI Catalog WG has not standardized it. -> There is also **no registered media type** for `server.json`. Treat the -> sketch below as experimental and subject to change; the documented path -> for cataloging MCP servers is via their Server Cards. - -An entry could, experimentally, point its `url` at a `server.json` -document. Because there is no known type for `server.json`, such an entry -would use the generic open-text `type` `application/json`: - -```json -{ - "identifier": "urn:air:anonymous.modelcontextprotocol.io:mcp:brave-search", - "version": "1.0.2", - "type": "application/json", - "url": "https://registry.modelcontextprotocol.io/servers/brave-search/server.json", - "description": "MCP server for Brave Search API integration", - "tags": ["search", "brave", "web"] -} -``` - -The conceptual field correspondence would mirror the Server Card mapping -above — the whole `server.json` is the referenced artifact; `name` maps -to the entry `identifier`; `description`/`version` map to the -like-named entry members; and `packages[]`, `remotes[]`, and -`environmentVariables[]` stay inside the artifact rather than being -surfaced in the catalog. The centralized MCP Registry and decentralized -AI Catalogs would be complementary: the registry could serve an AI -Catalog as its response format, while individual domains publish their -own catalogs for direct discovery. - # Mapping to Claude Code Plugins Marketplace This appendix describes how the Anthropic Claude Code Plugins From 930bc2d2a20f8983cab41a33661c0a16750bebd6 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 22:26:23 +0000 Subject: [PATCH 05/14] docs(mcp-mapping): don't claim server.json is addressed in its own appendix PR #53 alone does not add a server.json appendix (that lands in a stacked follow-up). Acknowledge server.json exists as a distinct artifact type without claiming this PR provides guidance on it. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index dda3fb6..54aed22 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1756,8 +1756,8 @@ as the artifact content of a Catalog Entry. A Server Card is a runtime discovery document for a single HTTP-based MCP server (its identity and connection details). It is distinct from the MCP -Registry's `server.json` — an installable-package descriptor — which is a -separate artifact type addressed in its own appendix. +Registry's `server.json`, an installable-package descriptor — a separate +artifact type that this appendix does not address. ## Overview From 57a4b4db1b6682d4347520a6979f2a7e3bf7e3eb Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 22:30:24 +0000 Subject: [PATCH 06/14] docs(mcp-mapping): drop stale MCP initialization-handshake reference MCP is removing the mandatory initialize handshake (modelcontextprotocol/ modelcontextprotocol#2575, stateless MCP). The Server Card description no longer frames itself as mirroring that handshake response; it simply states the fields the card carries. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 54aed22..e0f3986 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1762,8 +1762,7 @@ artifact type that this appendix does not address. ## Overview An MCP Server Card is a static discovery document for an individual -HTTP-based MCP server. It mirrors the MCP initialization handshake -response: it carries the server's name, version, transport +HTTP-based MCP server. It carries the server's name, version, transport configuration, capabilities, authentication requirements, and optionally the full list of tools, resources, and prompts. A Server Card MAY be hosted at any unreserved URI the catalog references; MCP reserves From da1f37c9725a7a179de046b21f0e4479b1b81c96 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 22:33:00 +0000 Subject: [PATCH 07/14] docs(mcp-mapping): describe the Server Card consistently as static The scope note called the card a 'runtime discovery document' while the Overview called it 'static'; align on 'static' (the SEP-2127 framing and the accurate one now that the card is the static replacement for the removed initialize handshake). The connection/runtime nuance stays in the parenthetical. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index e0f3986..a03fc87 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1754,7 +1754,7 @@ 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. -A Server Card is a runtime discovery document for a single HTTP-based MCP +A Server Card is a static discovery document for a single HTTP-based MCP server (its identity and connection details). It is distinct from the MCP Registry's `server.json`, an installable-package descriptor — a separate artifact type that this appendix does not address. From eb349340006938f2571f11b7fa78ef4f24bc3ef2 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 26 Jun 2026 22:35:36 +0000 Subject: [PATCH 08/14] docs(mcp-mapping): keep Server Card overview high-level, defer hosting detail to SEP-2127 The overview repeated SEP-2127's precise hosting rule (reserved /server-card default), which can drift from the SEP. Replace it with a high-level, example-led description and link out to SEP-2127 for the card's schema, fields, and hosting conventions. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index a03fc87..2e4bb2a 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1762,11 +1762,11 @@ artifact type that this appendix does not address. ## Overview An MCP Server Card is a static discovery document for an individual -HTTP-based MCP server. It carries the server's name, version, transport -configuration, capabilities, authentication requirements, and optionally -the full list of tools, resources, and prompts. A Server Card MAY be -hosted at any unreserved URI the catalog references; MCP reserves -`/server-card` as a predictable default location. +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 From 6b760400b04e8244a7614f16e92d4d1e393acb29 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 2 Jul 2026 00:52:51 +0000 Subject: [PATCH 09/14] docs(mcp-mapping): omit duplicative version/description from Server Card examples version and description restate values the referenced Server Card already carries, the same drift risk that keeps displayName/title out of the entry. Drop them from the example entries and update the conceptual mapping table to justify the omission (as the title row already does), while keeping the mapping documented. Co-Authored-By: Claude Opus 4.8 --- specification/ai-catalog.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 2e4bb2a..21ee626 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1793,8 +1793,8 @@ AI Catalog (cross-artifact) | 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` | Entry `description` | -| `version` | Entry `version` | +| `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 unless the catalog lists multiple versions of one identifier (see [Multi-Version Entries](#multi-version-entries)) | | transport / capabilities / tools / resources / auth | Inside the Server Card — not surfaced in the catalog | | `repository` | Entry `metadata.repository` | | *(not in the Server Card)* | Entry `publisher` | @@ -1810,10 +1810,8 @@ server's Server Card and whose `type` is the known type ```json { "identifier": "urn:air:example.com:mcp:finance-server", - "version": "1.0.2", "type": "application/mcp-server-card+json", "url": "https://api.acme-corp.com/mcp/server-card", - "description": "MCP server for financial data and trading tools", "tags": ["finance", "mcp"], "publisher": { "identifier": "did:web:acme-corp.com", @@ -1864,26 +1862,20 @@ entry points to a server's Server Card: "entries": [ { "identifier": "urn:air:acme-corp.com:mcp:finance-server", - "version": "1.0.2", "type": "application/mcp-server-card+json", "url": "https://api.acme-corp.com/finance/server-card", - "description": "MCP server for financial data and trading tools", "tags": ["finance", "mcp"] }, { "identifier": "urn:air:acme-corp.com:mcp:docs-search", - "version": "1.0.2", "type": "application/mcp-server-card+json", "url": "https://api.acme-corp.com/docs-search/server-card", - "description": "MCP server for searching internal documentation", "tags": ["search", "docs"] }, { "identifier": "urn:air:acme-corp.com:mcp:ci-cd", - "version": "0.5.0", "type": "application/mcp-server-card+json", "url": "https://api.acme-corp.com/ci-cd/server-card", - "description": "MCP server for CI/CD pipeline operations", "tags": ["ci", "cd", "devops"] } ] From 4e424af32f29d9b09ac7de46598ae27409847b3c Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 2 Jul 2026 01:01:58 +0000 Subject: [PATCH 10/14] docs: reframe Server Card discovery flow as a spectrum of integration points Replace the rigid 1-5 catalog-first ordering with a description that matches experimental-ext-server-card PR #36: the Server Card is a connection entry point useful on its own when the client already knows the URL, discovery has no single prescribed ordering, and the card is advisory (reconciled against the live connection, never authoritative for access control). Link out to the best-practices guidance. --- specification/ai-catalog.md | 45 +++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 21ee626..bcfcd41 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1894,23 +1894,34 @@ A vendor hosting its own MCP servers can publish: https://api.acme-corp.com/.well-known/ai-catalog.json ``` -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` (`application/mcp-server-card+json`) 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. +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 From b92dab57c1f7bb0bc69f0d392e40918d6a2eb24d Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 2 Jul 2026 01:57:32 +0000 Subject: [PATCH 11/14] docs: apply drift-avoidance treatment to the Server Card `repository` mapping MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Server Card carries its own `repository` field, so copying it into entry `metadata.repository` duplicates a value that can drift — the same argument that keeps `title`/`description`/`version` in the card. Leave `repository` in the card; catalog-level provenance/source links belong in the Trust Manifest. --- specification/ai-catalog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index bcfcd41..72f741c 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1796,7 +1796,7 @@ AI Catalog (cross-artifact) | `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 unless the catalog lists multiple versions of one identifier (see [Multi-Version Entries](#multi-version-entries)) | | transport / capabilities / tools / resources / auth | Inside the Server Card — not surfaced in the catalog | -| `repository` | Entry `metadata.repository` | +| `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 | From 74db617af0582a4da72dfa525b20bd38b1794a0d Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 2 Jul 2026 02:00:03 +0000 Subject: [PATCH 12/14] docs: bring Server Card `version` mapping to parity with the other drift fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A remote MCP server serves exactly one Server Card, so a catalog never lists multiple versions of it — the multi-version carve-out doesn't apply on the Server Card side. Drop it and treat `version` like the other drift-prone fields (stays in the card, omitted from the entry). The multi-version distinction remains on the server.json side (PR #54), where a registry genuinely can serve multiple versions. --- specification/ai-catalog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 72f741c..5d86881 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1794,7 +1794,7 @@ AI Catalog (cross-artifact) | 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 unless the catalog lists multiple versions of one identifier (see [Multi-Version Entries](#multi-version-entries)) | +| `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` | From e9a979f2bbe2e4a10b30582b448ce53eb4ebf8a3 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 2 Jul 2026 02:01:53 +0000 Subject: [PATCH 13/14] docs: drop the server.json naming-distinction note from the Server Card appendix Keep the Server-Card-only spec free of server.json references. The two-types naming rationale (application/mcp-server-card+json vs application/mcp-server+json) belongs with the server.json mapping, which is introduced in the stacked follow-up PR, not here. --- specification/ai-catalog.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 5d86881..eea13d9 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1838,11 +1838,7 @@ server's Server Card and whose `type` is the known type > ([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 the deliberate naming -> distinction: the MCP Server Card extension uses -> `application/mcp-server-card+json` (not `application/mcp-server+json`) -> to avoid colliding with the MCP Registry's `server.json` concept -> (modelcontextprotocol/experimental-ext-server-card issue #9 / PR #18). +> `application/mcp-server-card+json`. ## MCP Servers as an AI Catalog From f340affbee870ea127a7878aa5c3d206cb962946 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Thu, 2 Jul 2026 02:10:29 +0000 Subject: [PATCH 14/14] docs: drop redundant Server Card vs server.json contrast paragraph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The paragraph's first sentence duplicated the Overview immediately below it, and its second sentence referenced the MCP Registry server.json — which the Server-Card-only spec deliberately does not mention. The Server-Card-vs-server.json distinction lives in the stacked follow-up PR's dedicated 'Relationship to MCP Server Cards' section. --- specification/ai-catalog.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index eea13d9..2ec6244 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -1754,11 +1754,6 @@ 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. -A Server Card is a static discovery document for a single HTTP-based MCP -server (its identity and connection details). It is distinct from the MCP -Registry's `server.json`, an installable-package descriptor — a separate -artifact type that this appendix does not address. - ## Overview An MCP Server Card is a static discovery document for an individual