docs: refactor MCP mapping appendix to Server Cards + align with MCP spec

[tadasant]

⚠️ AI-assisted draft. This PR's content (spec prose and description) was drafted by an AI assistant working on Tadas's behalf. Tadas will review, vet, and rewrite as needed, and will remove this disclosure once he has done so. Until then, treat this as a steered placeholder, not Tadas's finished position.

What this does

Refreshes the MCP mapping appendix of the spec (live: https://ai-catalog.io/#mapping-to-mcp-registry-server-json), which was very outdated, and does a broader clean-up pass to align the spec's MCP examples with the current MCP spec.

Key changes

• Heading renamed Mapping to MCP Registry server.json → Mapping to MCP Servers. (No internal cross-references targeted the old anchor, so nothing else in the spec breaks; the public-page anchor changes accordingly.)
• The mapping is now Server-Card-centric. A remote MCP server maps to a Catalog Entry whose url points to the server's Server Card (SEP-2127) with the known type application/mcp-server-card+json. The conceptual table, the entry example, the "MCP Servers as an AI Catalog" example, the discovery flow, and "What AI Catalog Adds" were all rewritten around Server Cards.
• Server Card location aligned with the current MCP spec. Stale example URLs of the form https://…/.well-known/mcp/server-card.json are replaced with realistic example URLs the catalog entry can point at (the Server Card WG dropped the .well-known requirement for the card itself). This touches four examples elsewhere in the spec (the Top-Level Structure example and a few OCI/entry examples) in addition to the appendix — hence the broader "clean up to align with MCP spec" scope. The AI Catalog's own discovery file (/.well-known/ai-catalog.json) is unchanged — that's the catalog, not the card.
• Overview kept high-level, hosting detail deferred to the SEP. The appendix Overview previously restated SEP-2127's precise hosting rule (a reserved <streamable-http-url>/server-card default), which is the kind of technical detail that drifts from the SEP over time. It now gives a high-level, example-led description and links out to SEP-2127 for the card's schema, fields, and hosting conventions.
• type aligned with ADR 0014 (mediaType→type, open-text with recommended known types) throughout.
• Dropped the stale MCP initialization-handshake reference. MCP is removing the mandatory initialize handshake (modelcontextprotocol/modelcontextprotocol#2575, stateless MCP), so the Server Card description no longer frames itself as "mirroring the initialization handshake response" — it just states the fields the card carries. Relatedly, the card is now described consistently as a static discovery document (it had been called both "static" and "runtime") — the SEP-2127 framing, and accurate now that the static card is the replacement for the removed runtime handshake.

Scope note: server.json

The previous version of this appendix centered on the MCP Registry server.json format. That mapping is removed here and will be reintroduced as a first-class cataloged artifact type in a follow-up PR stacked on this one (giving server.json its own known media type rather than treating it as a footnote). This PR is intentionally Server-Card-only.

Assumptions / premise notes

• Assumes modelcontextprotocol/experimental-ext-server-card PR Add AI Catalog governance proposal #32 lands as written: it renames the Catalog Entry field mediaType→type but keeps the value application/mcp-server-card+json (deliberately not application/mcp-server+json, to avoid colliding with the Registry server.json concept — see ext-server-card issue Proposal: Start by Defining Design Principles for the Registry Standard #9 / PR spec: post-meeting converged AI Card profile proposal #18). If PR Add AI Catalog governance proposal #32 lands differently, the type value in these examples needs a follow-up edit.
• Premise correction: ADR 0014 on main already uses application/mcp-server-card+json (not application/mcp-server+json), so ADR 0014 and ext-server-card already agree — this PR keeps that value.

Verification

• Spec builds locally with the exact CI command (python tools/build_spec.py), exit 0, dist/index.html produced.
• Experimental section cleanly removed — no dangling in-page link to the deleted section remains (grep "experimental-mapping" → none).
• All stale server-card URLs gone — grep "well-known/mcp/server-card" → none; replaced count 4→0. The catalog's own /.well-known/ai-catalog.json URLs were verified unchanged (not wrongly rewritten).
• No new broken anchors — built-HTML link/id audit shows the only unresolved anchors (metadata-extensibility, resolving-an-artifacts-display-name, version-handling) are pre-existing on main (verified by building main's version); none are introduced or referenced by this change.
• All JSON examples valid and use the correct type (application/mcp-server-card+json) and urn:air: identifier form.
• Fresh-eyes review performed in-process on the final diff; came back clean (no issues).
• CI green on the latest commit (confirmed via wait-for-CI after the final push).

Status

Draft — do not merge. Awaiting Tadas's review and rewrite. A stacked follow-up PR adds first-class server.json cataloging.

[github-actions]

Preview: https://ai-catalog.io/pr/53/

This comment is updated automatically while the pull request preview is available.