Align experimental Server Cards with SEP-2127 v1 schema

Bring the experimental Server Card support up to date with the latest
extension spec (modelcontextprotocol/experimental-ext-server-card) and
the AI Catalog discovery docs. This takes over and supersedes #2696,
which was stacked on the now-removed Tasks (SEP-1686) work.

Conformance fixes:

- Pin the Server Card `$schema` to
  `.../schemas/v1/server-card.schema.json` instead of accepting any
  `/v1/*.schema.json`; a card referencing the registry `server.schema.json`
  is now correctly rejected.
- Use the canonical artifact media type `application/mcp-server-card+json`
  when serving and in catalog entries.
- Derive AI Catalog entry identifiers as `urn:air:{publisher}:{name}`:
  the card name's reverse-DNS namespace is turned back into the publisher's
  forward-DNS domain (`com.example/weather` -> `urn:air:example.com:weather`),
  replacing the old `urn:mcp:server:` scheme.
- Drop the registry-shaped `Server`/`packages` types (and the removed
  `server.schema.json` reference); v1 is card-only, with locally-runnable
  package metadata owned by the MCP Registry. `variables` now lives directly
  on `KeyValueInput`.
- Default `server_card_route`/`mount_server_card` to the spec-reserved
  `/server-card` path.

Restore the `experimental/__init__.py` package markers (regular packages, as
on the original branch) so `py.typed` propagates and pyright stays clean now
that the modules are no longer carried by the Tasks work.

Document that a Server Card must be registered in an AI Catalog to be
discoverable: clients learn a card's URL from a catalog entry rather than
guessing it.

Co-authored-by: David Soria Parra <davidsp@anthropic.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

src/mcp/client/experimental/__init__.py

@@ -0,0 +1,4 @@
+"""Experimental client-side MCP features.
+
+WARNING: These APIs are experimental and may change without notice.
+"""

src/mcp/client/experimental/server_card.py

@@ -12,8 +12,8 @@
             print(remote.type, remote.url, remote.supported_protocol_versions)
 
 Returned :class:`ServerCard` objects are validated; malformed documents raise
-``pydantic.ValidationError``. Ingestion is deliberately lenient about a
-missing ``$schema`` key — see ``ServerCard.schema_uri``.
+``pydantic.ValidationError``. A missing ``$schema`` key is tolerated — see
+``ServerCard.schema_uri``.
 """
 
 from __future__ import annotations
@@ -34,10 +34,6 @@
 
 __all__ = ["fetch_server_card", "load_server_card", "discover_server_cards"]
 
-# The MCP discovery extension and the AI Catalog specification currently name
-# the Server Card media type differently; accept either when filtering.
-_SERVER_CARD_MEDIA_TYPES = frozenset({MCP_SERVER_CARD_MEDIA_TYPE, "application/mcp-server-card+json"})
-
 
 async def fetch_server_card(url: str, *, http_client: httpx.AsyncClient | None = None) -> ServerCard:
     """Fetch and validate the Server Card at ``url``.
@@ -62,7 +58,7 @@ async def discover_server_cards(url: str, *, http_client: httpx.AsyncClient | No
     """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 transitional ``/.well-known/mcp/catalog.json`` on a
+    (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.
@@ -95,7 +91,7 @@ async def discover_server_cards(url: str, *, http_client: httpx.AsyncClient | No
 
     cards: list[ServerCard] = []
     for entry in catalog.entries:
-        if entry.media_type not in _SERVER_CARD_MEDIA_TYPES:
+        if entry.media_type != MCP_SERVER_CARD_MEDIA_TYPE:
             continue
         if entry.url is not None:
             # Entry URLs are usually absolute; resolve relative ones against

src/mcp/server/experimental/__init__.py

@@ -0,0 +1,4 @@
+"""Experimental server-side MCP features.
+
+WARNING: These APIs are experimental and may change without notice.
+"""

src/mcp/server/experimental/ai_catalog.py

@@ -2,21 +2,13 @@
 
 WARNING: These APIs are experimental and may change without notice.
 
-A server author advertises their MCP server by serving an AI Catalog from the
-well-known path, with an entry pointing at the server's Server Card::
+A server advertises its MCP server(s) by serving an AI Catalog from the
+well-known path, with one entry per Server Card::
 
-    from mcp.server.experimental.ai_catalog import mount_ai_catalog, server_card_entry
-    from mcp.server.experimental.server_card import build_server_card, mount_server_card
-    from mcp.shared.experimental.ai_catalog import AICatalog
+    catalog = AICatalog(entries=[server_card_entry(card, "https://example.com/server-card")])
+    mount_ai_catalog(server.streamable_http_app(), catalog)   # GET /.well-known/ai-catalog.json
 
-    card = build_server_card(server, name="io.modelcontextprotocol.examples/dice-roller")
-
-    app = server.streamable_http_app()
-    mount_server_card(app, card, path="/server-card.json")
-    catalog = AICatalog(entries=[server_card_entry(card, "https://dice.example.com/server-card.json")])
-    mount_ai_catalog(app, catalog)          # GET /.well-known/ai-catalog.json
-
-To write a catalog to a file instead, serialize it with
+To write a catalog to a file instead, use
 ``catalog.model_dump_json(by_alias=True, exclude_none=True)``.
 """
 
@@ -29,9 +21,9 @@
 
 from mcp.shared.experimental.ai_catalog.types import (
     AI_CATALOG_MEDIA_TYPE,
+    AI_CATALOG_URN_PREFIX,
     AI_CATALOG_WELL_KNOWN_PATH,
     MCP_SERVER_CARD_MEDIA_TYPE,
-    MCP_SERVER_URN_PREFIX,
     AICatalog,
     CatalogEntry,
 )
@@ -40,8 +32,8 @@
 __all__ = ["DISCOVERY_HEADERS", "server_card_entry", "ai_catalog_route", "mount_ai_catalog"]
 
 #: Response headers for discovery endpoints (catalogs and the artifacts they
-#: reference). Browser-based clients must be able to read them: the discovery
-#: spec makes the CORS headers a MUST and the caching header a SHOULD.
+#: reference): CORS headers so browser clients can read them, plus a caching
+#: hint.
 DISCOVERY_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET",
@@ -50,16 +42,29 @@
 }
 
 
+def _air_identifier(card_name: str) -> str:
+    """Derive an AI Catalog ``urn:air:`` identifier from a Server Card name.
+
+    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``.
+    """
+    namespace, _, suffix = card_name.partition("/")
+    publisher = ".".join(reversed(namespace.split(".")))
+    return f"{AI_CATALOG_URN_PREFIX}{publisher}:{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`` per the MCP
-    discovery extension (``urn:mcp:server:<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.
+    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.
     """
     return CatalogEntry(
-        identifier=f"{MCP_SERVER_URN_PREFIX}{card.name}",
+        identifier=_air_identifier(card.name),
         display_name=card.title or card.name,
         media_type=MCP_SERVER_CARD_MEDIA_TYPE,
         url=url,

src/mcp/server/experimental/server_card.py

@@ -2,24 +2,21 @@
 
 WARNING: These APIs are experimental and may change without notice.
 
-A server author builds a card from the server's identity and serves it at a
-path of their choosing, advertised through an AI Catalog (see
-``mcp.server.experimental.ai_catalog``)::
+A server author builds a card from the server's identity and serves it. The
+recommended location is ``<streamable-http-url>/server-card`` — pass ``path`` to
+match the MCP endpoint (e.g. ``/mcp/server-card`` when the server is mounted at
+``/mcp``)::
 
-    from mcp.server.experimental.server_card import build_server_card, mount_server_card
-    from mcp.shared.experimental.server_card import Remote
+    card = build_server_card(server, name="com.example/dice-roller", remotes=[...])
+    mount_server_card(server.streamable_http_app(), card, path="/mcp/server-card")
 
-    card = build_server_card(
-        server,
-        name="io.modelcontextprotocol.examples/dice-roller",
-        remotes=[Remote(type="streamable-http", url="https://dice.example.com/mcp")],
-    )
-
-    app = server.streamable_http_app()
-    mount_server_card(app, card, path="/server-card.json")
+Clients learn the card's URL from a catalog entry, so any reachable path works;
+the convention only matters for fallback probing.
 
-To write a card to a file instead, serialize it with
-``card.model_dump_json(by_alias=True, exclude_none=True)``.
+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
+catalog entry rather than guessing it. To write a card to a file instead of
+serving it, use ``card.model_dump_json(by_alias=True, exclude_none=True)``.
 """
 
 from __future__ import annotations
@@ -102,14 +99,16 @@ def build_server_card(
     )
 
 
-def server_card_route(card: ServerCard, *, path: str) -> Route:
+def server_card_route(card: ServerCard, *, path: str = "/server-card") -> Route:
     """Build a Starlette GET route that serves ``card`` at ``path``.
 
-    Add it to a new app — ``Starlette(routes=[server_card_route(card, path=...)])``
-    — or an existing one via :func:`mount_server_card`, and advertise the
-    resulting URL in an AI Catalog entry. The payload is serialized once and
-    served as ``application/mcp-server+json`` with the CORS and caching
-    headers discovery requires.
+    ``path`` defaults to ``/server-card``, the recommended location
+    (``<streamable-http-url>/server-card``). Add the route to
+    a new app — ``Starlette(routes=[server_card_route(card)])`` — or an existing
+    one via :func:`mount_server_card`, and advertise the resulting URL in an AI
+    Catalog entry. The payload is serialized once and served as
+    ``application/mcp-server-card+json`` with the CORS and caching headers
+    discovery requires.
     """
     body = card.model_dump_json(by_alias=True, exclude_none=True).encode()
 
@@ -119,10 +118,11 @@ async def endpoint(_request: Request) -> Response:
     return Route(path, endpoint=endpoint, methods=["GET"], name="mcp_server_card")
 
 
-def mount_server_card(app: Starlette, card: ServerCard, *, path: str) -> None:
+def mount_server_card(app: Starlette, card: ServerCard, *, path: str = "/server-card") -> None:
     """Attach a Server Card route to an existing Starlette application.
 
-    Pre-connection discovery expects the card to be reachable without
-    authentication; mount it outside any auth middleware.
+    ``path`` defaults to ``/server-card``, the reserved location. Pre-connection
+    discovery expects the card to be reachable without authentication; mount it
+    outside any auth middleware.
     """
     app.router.routes.append(server_card_route(card, path=path))

src/mcp/shared/experimental/__init__.py

@@ -0,0 +1,4 @@
+"""Shared experimental MCP features.
+
+WARNING: These APIs are experimental and may change without notice.
+"""

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

@@ -12,10 +12,10 @@
 
 from mcp.shared.experimental.ai_catalog.types import (
     AI_CATALOG_MEDIA_TYPE,
+    AI_CATALOG_URN_PREFIX,
     AI_CATALOG_WELL_KNOWN_PATH,
     MCP_CATALOG_WELL_KNOWN_PATH,
     MCP_SERVER_CARD_MEDIA_TYPE,
-    MCP_SERVER_URN_PREFIX,
     AICatalog,
     Attestation,
     CatalogEntry,
@@ -28,10 +28,10 @@
 
 __all__ = [
     "AI_CATALOG_MEDIA_TYPE",
+    "AI_CATALOG_URN_PREFIX",
     "AI_CATALOG_WELL_KNOWN_PATH",
     "MCP_CATALOG_WELL_KNOWN_PATH",
     "MCP_SERVER_CARD_MEDIA_TYPE",
-    "MCP_SERVER_URN_PREFIX",
     "AICatalog",
     "Attestation",
     "CatalogEntry",

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

@@ -32,14 +32,16 @@
 AI_CATALOG_MEDIA_TYPE = "application/ai-catalog+json"
 #: Media type identifying an MCP Server Card artifact in a catalog entry,
 #: per the MCP discovery extension.
-MCP_SERVER_CARD_MEDIA_TYPE = "application/mcp-server+json"
+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 transitional MCP-scoped catalog defined by the MCP
-#: discovery extension. Structurally compatible with an AI Catalog.
+#: 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 MCP server entry identifiers (``urn:mcp:server:<name>``).
-MCP_SERVER_URN_PREFIX = "urn:mcp:server:"
+#: 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``).
+AI_CATALOG_URN_PREFIX = "urn:air:"
 
 
 class TrustSchema(MCPModel):
@@ -179,15 +181,16 @@ class CatalogEntry(MCPModel):
     identifier: str
     """Identifier for the artifact; SHOULD be a URN or URI.
 
-    MCP server entries use ``urn:mcp:server:<name>`` where ``<name>`` is the
-    referenced Server Card's ``name``.
+    MCP server entries use ``urn:air:{publisher}:{name}``, where ``publisher`` is
+    the forward-DNS form of the referenced Server Card's namespace and ``name``
+    is its name suffix.
     """
 
     display_name: str
     """Human-readable name for the artifact."""
 
     media_type: str
-    """Media type identifying the artifact type (e.g. ``"application/mcp-server+json"``)."""
+    """Media type identifying the artifact type (e.g. ``"application/mcp-server-card+json"``)."""
 
     url: str | None = None
     """URL where the full artifact document can be retrieved."""
@@ -241,8 +244,7 @@ class AICatalog(MCPModel):
     spec_version: str = "1.0"
     """The AI Catalog specification version, in ``"Major.Minor"`` format.
 
-    The specification marks ``specVersion`` as required; ingestion here is
-    deliberately lenient and defaults it for documents that omit the key.
+    Required by the specification; defaulted here for documents that omit it.
     """
 
     entries: list[CatalogEntry]

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

@@ -12,42 +12,20 @@
 
 from mcp.shared.experimental.server_card.types import (
     SERVER_CARD_SCHEMA_URL,
-    SERVER_SCHEMA_URL,
-    Argument,
     Icon,
     Input,
-    InputWithVariables,
     KeyValueInput,
-    NamedArgument,
-    Package,
-    PackageTransport,
-    PositionalArgument,
     Remote,
     Repository,
-    Server,
     ServerCard,
-    SsePackageTransport,
-    StdioTransport,
-    StreamableHttpPackageTransport,
 )
 
 __all__ = [
     "SERVER_CARD_SCHEMA_URL",
-    "SERVER_SCHEMA_URL",
-    "Argument",
     "Icon",
     "Input",
-    "InputWithVariables",
     "KeyValueInput",
-    "NamedArgument",
-    "Package",
-    "PackageTransport",
-    "PositionalArgument",
     "Remote",
     "Repository",
-    "Server",
     "ServerCard",
-    "SsePackageTransport",
-    "StdioTransport",
-    "StreamableHttpPackageTransport",
 ]