docs: add Server Cards (SEP-2127) usage guide

[tadasant]

What this adds

Documentation for the experimental MCP Server Cards (SEP-2127) and AI Catalog discovery feature you built in modelcontextprotocol#2951. The PR shipped src/ + tests/ with no docs, so this fills that gap:

• docs/server-cards.md — a guide covering:
  • what a Server Card is (SEP-2127) and the experimental/opt-in stability caveat (front and center),
  • building a card server-side with build_server_card,
  • mounting the card + the AI Catalog onto the streamable_http_app() ASGI app (mount_server_card, server_card_entry, mount_ai_catalog),
  • the discovery HTTP semantics — well-known path (/.well-known/ai-catalog.json) with the MCP-scoped …/mcp/catalog.json fallback, strong SHA-256 ETags + conditional If-None-Match/304, and the DISCOVERY_HEADERS (CORS + Cache-Control),
  • client-side discovery (discover_server_cards) and the lower-level helpers (well_known_ai_catalog_url, fetch_ai_catalog, fetch_server_card, load_server_card), including the note about passing your own http_client for network policy,
  • the urn:air:{publisher}:{name} identifier derivation.
• One nav: line in mkdocs.yml wiring the page in.

Additive — none of your code changes

This is purely documentation. It changes no source and no tests. git diff --stat against experimental-server-card-v2:

 docs/server-cards.md | 286 +++++++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml           |   1 +
 2 files changed, 287 insertions(+)

It targets experimental-server-card-v2 (your PR branch), not upstream main, so you can fold it straight into modelcontextprotocol#2951.

A note on conventions

The repo's docs pages embed code inline with title="…" fences (e.g. docs/testing.md) rather than via a docs_src/ snippet directory, and the prose pages live flat in docs/ — so this page matches that. The new nav entry sits under the existing Documentation section (there is no "Advanced" section). Every code snippet is based on the real public signatures from your branch, and the server-side examples use the low-level Server to match your tests/experimental/server_card/test_server.py.

Verification

• uv run mkdocs build --strict passes — no broken nav, links, or mkdocstrings cross-references. Output: Documentation built in ~19s, exit 0.
• Snippets type-check under the repo's strict Pyright config. Extracted both the server-side and client-side code blocks into standalone modules and ran uv run pyright → 0 errors, 0 warnings. (Doc snippets aren't part of CI's pytest-examples run, which only targets README.v2.md, so this was verified locally.)

Disclosure

🤖 Opened via Claude Code, on behalf of @tadasant.