fix(experimental): align server cards with discovery spec

Adopt the current AI Catalog entry wire shape and MCP identifier namespace. Remove the retired MCP catalog fallback, keep metadata instability explicit, and tighten the focused tests and documentation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 13eb8021-1971-4c4f-9d07-4e98c0aaff7b

Author: SamMorrowDrums

docs/advanced/server-cards.md

@@ -6,7 +6,7 @@ speaks — so a client can learn all of that *before* it connects. An **AI
 Catalog** is the index that lists a host's cards at a well-known URL, so a client
 that knows only a domain can discover the servers behind it.
 
-This is the SDK's implementation of [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/community/sep-guidelines.md)
+This is the SDK's implementation of [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)
 and the companion AI Catalog discovery extension.
 
 !!! warning "Experimental"
@@ -29,7 +29,7 @@ sequenceDiagram
     participant C as Client
     participant H as Host (example.com)
     C->>H: GET /.well-known/ai-catalog.json
-    H-->>C: AI Catalog { entries: [ { url, media_type } ] }
+    H-->>C: AI Catalog { entries: [ { url, type } ] }
     C->>H: GET the card URL from a catalog entry
     H-->>C: Server Card { name, version, remotes[] }
     C->>H: connect to remotes[].url (streamable-http / sse)
@@ -89,8 +89,8 @@ so you can serialize them and serve the JSON from any web server or CDN:
 --8<-- "docs_src/server_cards/tutorial002.py"
 ```
 
-Serialize with `by_alias=True` so the wire names (`$schema`, `_meta`) are emitted,
-and `exclude_none=True` so unset optional fields are dropped.
+Serialize with `by_alias=True` so the wire names (`$schema`, `_meta`, `type`) are
+emitted, and `exclude_none=True` so unset optional fields are dropped.
 
 ## Discovery HTTP semantics
 
@@ -118,9 +118,8 @@ If-None-Match: "6b86b273ff34fce19d6b804eff5a3f57…"
 304 Not Modified
 ```
 
-The catalog is served from the well-known path `/.well-known/ai-catalog.json`.
-Clients probe there first and fall back to the MCP-scoped
-`/.well-known/mcp/catalog.json` on a 404, so either location is discoverable.
+The catalog is served from the well-known path
+`/.well-known/ai-catalog.json`.
 
 ## Discovering servers from a client
 
@@ -131,10 +130,10 @@ every MCP server the host advertises:
 --8<-- "docs_src/server_cards/tutorial003.py"
 ```
 
-`discover_server_cards` resolves the well-known catalog (with the
-`/.well-known/mcp/catalog.json` fallback), then fetches and validates each
-referenced card. Malformed documents raise `pydantic.ValidationError`; a card
-that omits `$schema` is tolerated and defaulted to the current v1 schema URL.
+`discover_server_cards` resolves the well-known catalog, then fetches and
+validates each referenced card. Malformed documents raise
+`pydantic.ValidationError`; a card that omits `$schema` is tolerated and
+defaulted to the current v1 schema URL.
 
 If you want to inspect the catalog before fetching cards, compose the lower-level
 helpers — `well_known_ai_catalog_url`, `fetch_ai_catalog`, and
@@ -162,9 +161,9 @@ suffix appended:
 
 | Card `name` | Catalog identifier |
 | --- | --- |
-| `com.example/weather` | `urn:air:example.com:weather` |
-| `example/dice` | `urn:air:example:dice` |
+| `com.example/weather` | `urn:air:example.com:mcp:weather` |
+| `example/dice` | `urn:air:example:mcp:dice` |
 
-`server_card_entry` computes this for you, and fills the entry's display name,
-description, and version from the card — so a catalog stays consistent with the
-cards it points at.
+`server_card_entry` computes this for you and emits only the identifier, type,
+and card URL. Human-readable fields remain on the card so the catalog cannot
+drift from it.

docs_src/server_cards/tutorial001.py

@@ -32,5 +32,5 @@
 mount_server_card(app, card, path="/mcp/server-card")
 
 card_url = "https://dice.example.com/mcp/server-card"
-catalog = AICatalog(entries=[server_card_entry(card, card_url)])
+catalog = AICatalog(spec_version="1.0", entries=[server_card_entry(card, card_url)])
 mount_ai_catalog(app, catalog)

docs_src/server_cards/tutorial002.py

@@ -13,10 +13,13 @@
     title="Dice Roller",
     remotes=[Remote(type="streamable-http", url="https://dice.example.com/mcp")],
 )
-catalog = AICatalog(entries=[server_card_entry(card, "https://dice.example.com/server-card.json")])
+catalog = AICatalog(
+    spec_version="1.0",
+    entries=[server_card_entry(card, "https://dice.example.com/server-card.json")],
+)
 
-# `by_alias=True` emits the wire names (`$schema`, `_meta`); `exclude_none=True`
-# drops unset optional fields.
+# `by_alias=True` emits the wire names (`$schema`, `_meta`, `type`);
+# `exclude_none=True` drops unset optional fields.
 card_json = card.model_dump_json(by_alias=True, exclude_none=True)
 catalog_json = catalog.model_dump_json(by_alias=True, exclude_none=True)
 

docs_src/server_cards/tutorial003.py

@@ -2,9 +2,8 @@
 
 
 async def main() -> None:
-    # Fetches the host's AI Catalog from `/.well-known/ai-catalog.json` (falling
-    # back to `/.well-known/mcp/catalog.json` on a 404), then validates the
-    # Server Card of every MCP entry it references.
+    # Fetches the host's AI Catalog from `/.well-known/ai-catalog.json`, then
+    # validates the Server Card of every MCP entry it references.
     for card in await discover_server_cards("https://dice.example.com"):
         print(card.name, card.version, "-", card.description)
         for remote in card.remotes or []:

src/mcp/client/experimental/ai_catalog.py

@@ -32,7 +32,7 @@
 __all__ = ["well_known_ai_catalog_url", "fetch_ai_catalog"]
 
 
-def well_known_ai_catalog_url(url: str, *, well_known_path: str = AI_CATALOG_WELL_KNOWN_PATH) -> str:
+def well_known_ai_catalog_url(url: str) -> str:
     """Resolve the well-known AI Catalog URL for a server's origin.
 
     Accepts either a bare origin (``https://example.com``) or any URL on the
@@ -44,7 +44,7 @@ def well_known_ai_catalog_url(url: str, *, well_known_path: str = AI_CATALOG_WEL
     parts = urlsplit(url)
     if parts.scheme not in ("http", "https") or not parts.netloc:
         raise ValueError(f"Expected an absolute http(s) URL, got {url!r}")
-    return urljoin(f"{parts.scheme}://{parts.netloc}", well_known_path)
+    return urljoin(f"{parts.scheme}://{parts.netloc}", AI_CATALOG_WELL_KNOWN_PATH)
 
 
 async def fetch_ai_catalog(url: str, *, http_client: httpx2.AsyncClient | None = None) -> AICatalog:

src/mcp/client/experimental/server_card.py

@@ -26,10 +26,7 @@
 
 from mcp.client.experimental.ai_catalog import fetch_ai_catalog, well_known_ai_catalog_url
 from mcp.shared._httpx_utils import create_mcp_http_client
-from mcp.shared.experimental.ai_catalog.types import (
-    MCP_CATALOG_WELL_KNOWN_PATH,
-    MCP_SERVER_CARD_MEDIA_TYPE,
-)
+from mcp.shared.experimental.ai_catalog.types import MCP_SERVER_CARD_MEDIA_TYPE
 from mcp.shared.experimental.server_card.types import ServerCard
 
 __all__ = ["fetch_server_card", "load_server_card", "discover_server_cards"]
@@ -57,11 +54,10 @@ async def fetch_server_card(url: str, *, http_client: httpx2.AsyncClient | None
 async def discover_server_cards(url: str, *, http_client: httpx2.AsyncClient | None = None) -> list[ServerCard]:
     """Discover the MCP servers advertised by the host of ``url``.
 
-    Fetches the host's AI Catalog from ``/.well-known/ai-catalog.json``
-    (falling back to the MCP-scoped ``/.well-known/mcp/catalog.json`` on a
-    404), then validates the Server Card of every MCP server entry — fetched
-    from the entry's ``url`` or read from its inline ``data``. Entries with
-    other media types are ignored.
+    Fetches the host's AI Catalog from ``/.well-known/ai-catalog.json``, then
+    validates the Server Card of every MCP server entry — fetched from the
+    entry's ``url`` or read from its inline ``data``. Entries with other types
+    are ignored.
 
     Card URLs are taken from the fetched catalog and may point anywhere,
     including other domains. Non-http(s) card URLs are rejected; beyond that,
@@ -81,13 +77,7 @@ async def discover_server_cards(url: str, *, http_client: httpx2.AsyncClient | N
             return await discover_server_cards(url, http_client=client)
 
     catalog_url = well_known_ai_catalog_url(url)
-    try:
-        catalog = await fetch_ai_catalog(catalog_url, http_client=http_client)
-    except httpx2.HTTPStatusError as exc:
-        if exc.response.status_code != 404:
-            raise
-        catalog_url = well_known_ai_catalog_url(url, well_known_path=MCP_CATALOG_WELL_KNOWN_PATH)
-        catalog = await fetch_ai_catalog(catalog_url, http_client=http_client)
+    catalog = await fetch_ai_catalog(catalog_url, http_client=http_client)
 
     cards: list[ServerCard] = []
     for entry in catalog.entries:

src/mcp/server/experimental/ai_catalog.py

@@ -5,7 +5,10 @@
 A server advertises its MCP server(s) by serving an AI Catalog from the
 well-known path, with one entry per Server Card::
 
-    catalog = AICatalog(entries=[server_card_entry(card, "https://example.com/server-card")])
+    catalog = AICatalog(
+        spec_version="1.0",
+        entries=[server_card_entry(card, "https://example.com/server-card")],
+    )
     mount_ai_catalog(server.streamable_http_app(), catalog)   # GET /.well-known/ai-catalog.json
 
 To write a catalog to a file instead, use
@@ -44,10 +47,6 @@
 }
 
 
-def _strong_etag(body: bytes) -> str:
-    return f'"{hashlib.sha256(body).hexdigest()}"'
-
-
 def _if_none_match_matches(if_none_match: str | None, etag: str) -> bool:
     if if_none_match is None:
         return False
@@ -63,7 +62,8 @@ def _if_none_match_matches(if_none_match: str | None, etag: str) -> bool:
 
 
 def discovery_response(request: Request, body: bytes, media_type: str) -> Response:
-    etag = _strong_etag(body)
+    """Build a cacheable discovery response with conditional ETag handling."""
+    etag = f'"{hashlib.sha256(body).hexdigest()}"'
     if _if_none_match_matches(request.headers.get("if-none-match"), etag):
         return Response(
             status_code=304,
@@ -78,28 +78,26 @@ def _air_identifier(card_name: str) -> str:
     The card ``name`` is ``namespace/suffix`` in reverse-DNS form
     (``com.example/weather``); the namespace labels are reversed to forward-DNS
     (``com.example`` -> ``example.com``) and the suffix appended:
-    ``urn:air:example.com:weather``.
+    ``urn:air:example.com:mcp:weather``.
     """
     namespace, _, suffix = card_name.partition("/")
     publisher = ".".join(reversed(namespace.split(".")))
-    return f"{AI_CATALOG_URN_PREFIX}{publisher}:{suffix}"
+    return f"{AI_CATALOG_URN_PREFIX}{publisher}:mcp:{suffix}"
 
 
 def server_card_entry(card: ServerCard, url: str) -> CatalogEntry:
     """Build the catalog entry advertising ``card``, served at ``url``.
 
     The entry's identifier is derived from the card's ``name``
-    (``urn:air:{publisher}:{name}``); display name, description and version are
-    taken from the card. ``url`` should be the absolute URL the card is
-    retrievable from, since catalogs may be fetched cross-domain.
+    (``urn:air:{publisher}:mcp:{name}``). Human-readable fields stay on the
+    Server Card so the catalog cannot drift from it. ``url`` should be the
+    absolute URL the card is retrievable from, since catalogs may be fetched
+    cross-domain.
     """
     return CatalogEntry(
         identifier=_air_identifier(card.name),
-        display_name=card.title or card.name,
         media_type=MCP_SERVER_CARD_MEDIA_TYPE,
         url=url,
-        description=card.description,
-        version=card.version,
     )
 
 

src/mcp/server/experimental/server_card.py

@@ -11,7 +11,7 @@
     mount_server_card(server.streamable_http_app(), card, path="/mcp/server-card")
 
 Clients learn the card's URL from a catalog entry, so any reachable path works;
-the convention only matters for fallback probing.
+the convention gives publishers a predictable default.
 
 A hosted card is only discoverable once it is registered in an AI Catalog (see
 ``mcp.server.experimental.ai_catalog``); clients learn a card's URL from a

src/mcp/shared/experimental/ai_catalog/__init__.py

@@ -14,7 +14,6 @@
     AI_CATALOG_MEDIA_TYPE,
     AI_CATALOG_URN_PREFIX,
     AI_CATALOG_WELL_KNOWN_PATH,
-    MCP_CATALOG_WELL_KNOWN_PATH,
     MCP_SERVER_CARD_MEDIA_TYPE,
     AICatalog,
     Attestation,
@@ -30,7 +29,6 @@
     "AI_CATALOG_MEDIA_TYPE",
     "AI_CATALOG_URN_PREFIX",
     "AI_CATALOG_WELL_KNOWN_PATH",
-    "MCP_CATALOG_WELL_KNOWN_PATH",
     "MCP_SERVER_CARD_MEDIA_TYPE",
     "AICatalog",
     "Attestation",

src/mcp/shared/experimental/ai_catalog/types.py

@@ -4,16 +4,14 @@
 
 An AI Catalog is a typed, nestable JSON container for discovering
 heterogeneous AI artifacts (MCP servers, A2A agents, skills, nested
-catalogs, ...). Each entry declares its artifact type via a media type and
-either references the artifact by URL or embeds it inline. Hosts advertise a
-catalog at ``/.well-known/ai-catalog.json`` so clients can discover artifacts
-— for MCP, the Server Cards in ``mcp.shared.experimental.server_card`` —
-without prior configuration.
+catalogs, ...). Each entry declares its artifact type via a type identifier
+and either references the artifact by URL or embeds it inline. Hosts advertise
+a catalog at ``/.well-known/ai-catalog.json`` so clients can discover
+artifacts — for MCP, the Server Cards in
+``mcp.shared.experimental.server_card`` — without prior configuration.
 
 The models mirror the normative CDDL schema of the AI Catalog specification,
-including the optional Trust Manifest extension. The MCP Catalog defined by
-the MCP discovery extension is a structural subset of an AI Catalog, so these
-models ingest both document flavours.
+including the optional Trust Manifest extension.
 
 See https://github.com/Agent-Card/ai-catalog and
 https://github.com/modelcontextprotocol/experimental-ext-server-card/blob/main/docs/discovery.md.
@@ -34,12 +32,10 @@
 MCP_SERVER_CARD_MEDIA_TYPE = "application/mcp-server-card+json"
 #: Well-known path an AI Catalog is published at, relative to the host root.
 AI_CATALOG_WELL_KNOWN_PATH = "/.well-known/ai-catalog.json"
-#: Well-known path of the MCP-scoped catalog defined by the MCP discovery
-#: extension. A structural subset of an AI Catalog, so it parses with these models.
-MCP_CATALOG_WELL_KNOWN_PATH = "/.well-known/mcp/catalog.json"
 #: URN prefix for AI Catalog entry identifiers. MCP server entries use
-#: ``urn:air:{publisher}:{name}`` where ``publisher`` is the forward-DNS form of
-#: the card name's namespace (``com.example/weather`` -> ``urn:air:example.com:weather``).
+#: ``urn:air:{publisher}:mcp:{name}`` where ``publisher`` is the forward-DNS
+#: form of the card name's namespace
+#: (``com.example/weather`` -> ``urn:air:example.com:mcp:weather``).
 AI_CATALOG_URN_PREFIX = "urn:air:"
 
 
@@ -135,7 +131,11 @@ class TrustManifest(MCPModel):
     """Detached JWS signature computed over the Trust Manifest content."""
 
     metadata: dict[str, Any] | None = None
-    """Open map for custom or non-standard trust metadata."""
+    """Open map for custom trust data.
+
+    This field is unstable and may be replaced by structured extensions before
+    AI Catalog v1.
+    """
 
 
 class Publisher(MCPModel):
@@ -185,17 +185,17 @@ class CatalogEntry(MCPModel):
     is its name suffix.
     """
 
-    display_name: str
+    display_name: str | None = None
     """Human-readable name for the artifact."""
 
-    media_type: str
-    """Media type identifying the artifact type (e.g. ``"application/mcp-server-card+json"``)."""
+    media_type: str = Field(validation_alias="type", serialization_alias="type")
+    """The serialized ``type`` identifier (e.g. ``"application/mcp-server-card+json"``)."""
 
     url: str | None = None
     """URL where the full artifact document can be retrieved."""
 
     data: Any = None
-    """The complete artifact document inline; its structure is determined by ``media_type``."""
+    """The complete artifact document inline; its structure is determined by ``type``."""
 
     version: str | None = None
     """Version of the artifact. Semantic versioning is recommended."""
@@ -216,7 +216,11 @@ class CatalogEntry(MCPModel):
     """When this entry was last modified."""
 
     metadata: dict[str, Any] | None = None
-    """Open map for custom or non-standard metadata."""
+    """Open map for custom data.
+
+    This field is unstable and may be replaced by structured extensions before
+    AI Catalog v1.
+    """
 
     @model_validator(mode="after")
     def _check_content_and_trust(self) -> CatalogEntry:
@@ -235,16 +239,13 @@ def _check_content_and_trust(self) -> CatalogEntry:
 class AICatalog(MCPModel):
     """A catalog of AI artifacts, served as ``application/ai-catalog+json``.
 
-    A minimal catalog is just ``entries`` — names, media types and URLs. A
+    A minimal catalog is just ``specVersion`` and ``entries``. A
     catalog may be served from any URL; hosts that want automated discovery
     publish one at ``/.well-known/ai-catalog.json``.
     """
 
-    spec_version: str = "1.0"
-    """The AI Catalog specification version, in ``"Major.Minor"`` format.
-
-    Required by the specification; defaulted here for documents that omit it.
-    """
+    spec_version: str
+    """The AI Catalog specification version, in ``"Major.Minor"`` format."""
 
     entries: list[CatalogEntry]
     """The cataloged artifacts. May be empty."""
@@ -253,4 +254,8 @@ class AICatalog(MCPModel):
     """The operator of this catalog."""
 
     metadata: dict[str, Any] | None = None
-    """Open map for custom or non-standard metadata."""
+    """Open map for custom data.
+
+    This field is unstable and may be replaced by structured extensions before
+    AI Catalog v1.
+    """