docs: add Server Cards page with runnable examples

New Advanced page covering serving a card, publishing on a brand
domain, static publishing, discovery and connect, ETag revalidation,
and the security model (advisory cards, endpoint-keyed dedup, host
scoped consent, SSRF policy defaults). Tutorials are pyright-checked
docs_src modules proved against the real SDK by
tests/docs_src/test_server_cards.py.

Author: claude

docs/advanced/server-cards.md

@@ -0,0 +1,124 @@
+# Server Cards
+
+!!! warning "Experimental"
+    Server Cards are an experimental MCP extension tracking
+    [SEP-2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127).
+    Everything on this page lives under `experimental` modules and may change or be
+    removed in any release without a deprecation cycle.
+
+A **Server Card** is a static JSON document that describes a single remote MCP server
+well enough for a client to discover it and connect, before any protocol exchange:
+identity (`name`, `version`, `description`, `title`, `icons`, `repository`,
+`websiteUrl`), the transport endpoints (`remotes[]` with URL templates, header inputs
+and supported protocol versions), and namespaced `_meta` for anything else. It is served
+as `application/mcp-server-card+json`.
+
+A card deliberately omits two things. Tools, resources and prompts stay behind the
+runtime `list` operations. Local install metadata (packages, registries, arguments,
+environment) belongs to the MCP Registry's `server.json`. If you need install hints,
+put them in `_meta`.
+
+## Serving a card
+
+The spec reserves `GET <your streamable HTTP URL>/server-card` as the default location,
+and domain-level discovery reads an **AI Catalog** at `/.well-known/ai-catalog.json`.
+`mount_discovery` sets up both on a single-domain deployment:
+
+```python title="serve_card.py" hl_lines="12 19"
+--8<-- "docs_src/server_cards/tutorial001.py"
+```
+
+`build_server_card` derives `title`, `description`, `version`, `websiteUrl` and `icons`
+from the server object, so the card stays consistent with what `serverInfo` reports at
+runtime. Explicit keyword arguments override the derived values. The namespaced card
+`name` and the public `remotes` URLs are yours to supply, since the server object cannot
+know them.
+
+With the app above, `GET /mcp/server-card` and `GET /.well-known/ai-catalog.json` both
+answer with the spec's required headers: the correct `Content-Type`, the CORS headers
+the spec mandates on card endpoints, a `Cache-Control: public, max-age=3600` default,
+and a strong `ETag` that turns a matching `If-None-Match` into an empty `304`.
+
+The card routes are appended to the app after `streamable_http_app()` builds it. Mount
+them outside any auth middleware. Discovery is unauthenticated by design, and a card or
+catalog must never contain credentials, internal topology or private endpoints.
+
+If you need only one of the two endpoints, or different paths, use the smaller pieces:
+`create_server_card_routes` / `mount_server_card` for the card and
+`create_ai_catalog_routes` / `mount_ai_catalog` for the catalog. For fully custom
+hosting (say a FastAPI route), `discovery_response` is the compliance chokepoint that
+produces a correct response from a request and the document bytes.
+
+## Publishing on your brand domain
+
+The catalog belongs on the domain users associate with your service, which is often
+different from the API host (think `github.com` versus `api.githubcopilot.com`). In that
+case skip `mount_discovery` and build the entry yourself with `server_card_entry`, then
+publish it in the catalog your brand domain serves. Entries can point at the hosted card
+by URL or inline the whole card as `data`.
+
+A card is just JSON, so static publishing needs no server at all:
+
+```python title="publish_static.py"
+--8<-- "docs_src/server_cards/tutorial004.py"
+```
+
+Upload the result to your CDN and reference it from your catalog.
+
+## Discovering and connecting
+
+`discover_server_cards` is one probe: it fetches the well-known catalog of the URL's
+origin, follows Server Card entries (by URL or inline `data`) and nested catalogs, and
+returns every card it found. It never runs implicitly. Your host decides when to probe.
+
+```python title="discover_and_connect.py" hl_lines="10 16"
+--8<-- "docs_src/server_cards/tutorial002.py"
+```
+
+`resolve_remote` substitutes the card's `{curly_brace}` variables using declared
+defaults and your values, and raises a `ValueError` naming every missing required input,
+so you can prompt for all of them at once. `Remote.required_variables` lists them up
+front.
+
+The probe collects per-entry problems in `DiscoveryResult.failures` instead of raising,
+so one hostile or broken entry never hides the rest. Each `CardListing` carries the
+listing chain for your consent UI: `listing_domain` is where the catalog listed the
+card, `hosting_domain` is where the card itself lives, and they legitimately differ.
+
+For local development the hardened defaults get in the way (plain http and loopback
+targets are blocked). Opt in explicitly with
+`DiscoveryPolicy(allow_private_addresses=True)`.
+
+## Caching and revalidation
+
+Clients should honor `Cache-Control` and avoid polling. The SDK deliberately ships no
+cache storage. Instead, the stateless request/parse pairs let your host revalidate with
+its own store:
+
+```python title="revalidate.py" hl_lines="16 18"
+--8<-- "docs_src/server_cards/tutorial003.py"
+```
+
+Store the `ETag` alongside the card and send it back as `If-None-Match`. An unchanged
+card costs a 304 and no body.
+
+## Security model
+
+Cards are unverified, advisory input. The rules that keep discovery safe:
+
+- **Runtime wins.** A card's claims should match the live server, and
+  `reconcile_server_card` reports any drift, but clients must never treat card contents
+  as authoritative for security or access-control decisions.
+- **De-duplicate on endpoints.** `name` and the catalog `identifier` are self-asserted
+  and spoofable. `ServerCard.endpoint_urls()` gives you the dedup key: the card's actual
+  `remotes[]` URLs.
+- **Never auto-install.** Consent, its persistence ("not now", "this session",
+  "always"), decline memory and enterprise allowlists are host application policy. The
+  SDK exposes the data and stays out of the decision.
+- **Hardened fetching.** Every fetch, redirect hop and nested catalog follow is checked
+  under `DiscoveryPolicy`: https only (plain http is loopback-only), an SSRF guard that
+  rejects private, loopback, link-local and metadata addresses (checked again after DNS
+  resolution), bounded redirects, response size and entry count caps, and no cookies or
+  ambient credentials. If you pass your own `http_client`, keep it credential-free. The
+  guard resolves DNS before the request while the client re-resolves on connect, so a
+  DNS rebinding race remains possible between the two.

docs_src/server_cards/__init__.py

@@ -0,0 +1,19 @@
+from mcp.server import MCPServer
+from mcp.server.experimental.server_card import build_server_card, mount_discovery
+from mcp.shared.experimental.server_card import Remote
+
+mcp = MCPServer(
+    name="weather",
+    version="1.4.0",
+    description="Hourly forecasts.",
+    website_url="https://example.com",
+)
+
+card = build_server_card(
+    mcp,
+    name="com.example/weather",
+    remotes=[Remote(type="streamable-http", url="https://mcp.example.com/mcp")],
+)
+
+app = mcp.streamable_http_app()
+mount_discovery(app, card, public_url="https://mcp.example.com")

docs_src/server_cards/tutorial001.py

@@ -0,0 +1,22 @@
+import httpx2
+
+from mcp import Client
+from mcp.client.experimental.server_card import discover_server_cards, reconcile_server_card
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared.experimental.server_card import resolve_remote
+
+
+async def main() -> None:
+    result = await discover_server_cards("https://example.com/docs")
+    for listing in result.listings:
+        print(listing.entry.identifier, "listed on", listing.listing_domain, "hosted at", listing.hosting_domain)
+
+    chosen = result.listings[0]  # your host app: consent UI, dedup on chosen.card.endpoint_urls()
+    assert chosen.card.remotes is not None
+    resolved = resolve_remote(chosen.card.remotes[0], {"token": "..."})  # ValueError names missing inputs
+
+    async with httpx2.AsyncClient(headers=resolved.headers, follow_redirects=True) as http_client:
+        transport = streamable_http_client(resolved.url, http_client=http_client)
+        async with Client(transport) as client:
+            for mismatch in reconcile_server_card(chosen.card, client.server_info):  # advisory: runtime wins
+                print("card mismatch:", mismatch.field, mismatch.card_value, mismatch.runtime_value)

docs_src/server_cards/tutorial002.py

@@ -0,0 +1,22 @@
+import httpx2
+
+from mcp.client.experimental.server_card import create_server_card_request, parse_server_card_response
+from mcp.shared.experimental.server_card import ServerCard
+
+
+class CardStore:
+    """Your host's cache. Anything that keeps a card and its ETag per URL works."""
+
+    def __init__(self) -> None:
+        self.cards: dict[str, ServerCard] = {}
+        self.etags: dict[str, str] = {}
+
+
+async def refresh(store: CardStore, http: httpx2.AsyncClient, url: str) -> ServerCard:
+    request = create_server_card_request(url, if_none_match=store.etags.get(url))
+    response = await http.send(request)
+    if response.status_code != 304:  # an unchanged card costs a 304
+        store.cards[url] = parse_server_card_response(response)
+        if "etag" in response.headers:
+            store.etags[url] = response.headers["etag"]
+    return store.cards[url]

docs_src/server_cards/tutorial003.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+from mcp.shared.experimental.server_card import Remote, ServerCard
+
+card = ServerCard(
+    name="com.example/weather",
+    version="1.4.0",
+    description="Hourly forecasts.",
+    title="Weather",
+    website_url="https://example.com",
+    remotes=[Remote(type="streamable-http", url="https://mcp.example.com/mcp")],
+)
+
+
+def publish(path: Path) -> None:
+    path.write_text(card.model_dump_json(by_alias=True, exclude_none=True))

docs_src/server_cards/tutorial004.py

@@ -67,6 +67,7 @@ nav:
       - Middleware: advanced/middleware.md
       - Extensions: advanced/extensions.md
       - MCP Apps: advanced/apps.md
+      - Server Cards: advanced/server-cards.md
   - Troubleshooting: troubleshooting.md
   - Migration Guide: migration.md
   - API Reference: api/

mkdocs.yml

@@ -0,0 +1,126 @@
+"""`docs/advanced/server-cards.md`: every claim the page makes, proved against the real SDK."""
+
+import ipaddress
+from pathlib import Path
+
+import httpx2
+import pytest
+
+from docs_src.server_cards import tutorial001, tutorial002, tutorial003, tutorial004
+from mcp import Client
+from mcp.client.experimental import _discovery_http
+from mcp.client.experimental.server_card import discover_server_cards, load_server_card, reconcile_server_card
+from mcp.shared.experimental.server_card import Input, Remote, resolve_remote
+
+# See test_index.py for why this is a per-module mark and not a conftest hook.
+pytestmark = [pytest.mark.anyio, pytest.mark.filterwarnings("error::mcp.MCPDeprecationWarning")]
+
+INITIALIZE = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "d", "version": "1"}},
+}
+MCP_HEADERS = {"Accept": "application/json, text/event-stream", "Content-Type": "application/json"}
+
+
+@pytest.fixture
+def public_dns(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Pin DNS to a public address so the default discovery policy runs offline.
+
+    The SSRF guard resolves every hostname before the request, and the page's
+    example domains do not resolve in CI.
+    """
+
+    async def resolve(host: str) -> list[ipaddress.IPv4Address | ipaddress.IPv6Address]:
+        return [ipaddress.ip_address("93.184.216.34")]
+
+    monkeypatch.setattr(_discovery_http, "_host_addresses", resolve)
+
+
+async def test_mount_discovery_serves_both_endpoints_with_the_spec_headers() -> None:
+    """tutorial001: the two GET endpoints exist beside the live transport, with the
+    page's promised Content-Type, CORS, Cache-Control and ETag/304 behavior."""
+    transport = httpx2.ASGITransport(app=tutorial001.app)
+    async with tutorial001.mcp.session_manager.run():
+        async with httpx2.AsyncClient(transport=transport, base_url="http://localhost:8000") as http:
+            initialize = await http.post("/mcp", json=INITIALIZE, headers=MCP_HEADERS)
+            card_response = await http.get("/mcp/server-card")
+            catalog_response = await http.get("/.well-known/ai-catalog.json")
+            revalidated = await http.get("/mcp/server-card", headers={"If-None-Match": card_response.headers["etag"]})
+    assert initialize.status_code == 200
+    assert card_response.headers["content-type"] == "application/mcp-server-card+json"
+    assert card_response.headers["access-control-allow-origin"] == "*"
+    assert card_response.headers["access-control-allow-methods"] == "GET"
+    assert card_response.headers["access-control-allow-headers"] == "Content-Type"
+    assert card_response.headers["cache-control"] == "public, max-age=3600"
+    assert catalog_response.headers["content-type"] == "application/ai-catalog+json"
+    assert (revalidated.status_code, revalidated.content) == (304, b"")
+
+
+async def test_build_server_card_keeps_the_card_consistent_with_server_info() -> None:
+    """tutorial001 + the page's derivation claim: the card carries the server's version,
+    description and websiteUrl, so `reconcile_server_card` finds no drift after connect."""
+    assert tutorial001.card.version == "1.4.0"
+    assert tutorial001.card.description == "Hourly forecasts."
+    assert tutorial001.card.website_url == "https://example.com"
+    async with Client(tutorial001.mcp) as client:
+        assert reconcile_server_card(tutorial001.card, client.server_info) == []
+
+
+async def test_the_discovery_probe_finds_the_served_card(public_dns: None) -> None:
+    """tutorial002: `discover_server_cards` on any page of the origin finds the card
+    tutorial001 mounted, and the listing exposes the consent-UI domains and the endpoint
+    dedup key. The tutorial's `main()` itself needs a live network, so the flow is
+    proved here against the in-memory app."""
+    http_client = httpx2.AsyncClient(
+        transport=httpx2.ASGITransport(app=tutorial001.app), base_url="https://mcp.example.com"
+    )
+    async with http_client:
+        result = await discover_server_cards("https://mcp.example.com/docs", http_client=http_client)
+    assert result.failures == []
+    (listing,) = result.listings
+    assert listing.entry.identifier == "urn:air:mcp.example.com:mcp:weather"
+    assert (listing.listing_domain, listing.hosting_domain) == ("mcp.example.com", "mcp.example.com")
+    assert listing.card.endpoint_urls() == frozenset({"https://mcp.example.com/mcp"})
+    assert listing.card == tutorial001.card
+
+
+def test_resolve_remote_names_every_missing_required_input() -> None:
+    """tutorial002's comment: `resolve_remote` raises a ValueError naming the missing
+    required inputs so a host can prompt for all of them at once."""
+    remote = Remote(
+        type="streamable-http",
+        url="https://{tenant}.example.com/mcp",
+        variables={"tenant": Input(is_required=True)},
+    )
+    assert remote.required_variables == frozenset({"tenant"})
+    with pytest.raises(ValueError, match="tenant"):
+        resolve_remote(remote)
+    assert resolve_remote(remote, {"tenant": "acme"}).url == "https://acme.example.com/mcp"
+
+
+async def test_the_revalidation_recipe_costs_a_304_when_unchanged() -> None:
+    """tutorial003: the first `refresh` parses and stores the card, the second sends the
+    stored ETag and reuses the cache on the 304."""
+    store = tutorial003.CardStore()
+    transport = httpx2.ASGITransport(app=tutorial001.app)
+    async with httpx2.AsyncClient(transport=transport, base_url="https://mcp.example.com") as http:
+        first = await tutorial003.refresh(store, http, "https://mcp.example.com/mcp/server-card")
+        second = await tutorial003.refresh(store, http, "https://mcp.example.com/mcp/server-card")
+    assert first == tutorial001.card
+    assert second is first
+    assert store.etags["https://mcp.example.com/mcp/server-card"].startswith('"')
+
+
+def test_static_publishing_writes_a_loadable_card(tmp_path: Path) -> None:
+    """tutorial004: the written file is a valid card document that loads back."""
+    target = tmp_path / "server-card.json"
+    tutorial004.publish(target)
+    assert load_server_card(target) == tutorial004.card
+
+
+def test_the_connect_tutorial_exposes_its_client_program() -> None:
+    """tutorial002's `main()` needs a live network, so its coverage here is the import
+    plus the in-memory proof of the same flow above."""
+    assert callable(tutorial002.main)