Track reference implementation for SEP-2127: python-sdk#2696 (finalize before advancing the SEP)

[tadasant]

🤖 Drafted by Claude Code (an AI coding agent) on behalf of @tadasant. The substance was reviewed by a human before filing.

Summary

The Extensions Track requires an SDK reference implementation before a SEP can advance — from SEP-2133: an extension "MUST have at least one reference implementation in an official SDK prior to review to ensure the extension is practical and implementable." SEP-2127's own Reference Implementation section is still "To be added."

python-sdk#2696 — "Add experimental Server Cards support (SEP-2127)" (by @dsp-ant) is that reference implementation, and it's the furthest-along artifact we have. This issue tracks reviewing/finalizing it. We should not move SEP-2127 forward (to Final / graduation) until this implementation is reviewed, agreed, and merged, and reflects the shape we've settled on. Related: #15 (refactor SEP-2127 to Extensions Track).

What #2696 provides

Status: open, REVIEW_REQUIRED, not merged (created 2026-05-26; supersedes #2692, which was example-app-only). It adds, under experimental namespaces:

• Server side — build_server_card(...) to derive a card from a server's identity, plus mount_server_card / server_card_route to serve it via Starlette.
• Client side — fetch_server_card / load_server_card / well_known_url to fetch and validate a card for pre-connection discovery.
• Models — Pydantic ServerCard, Server, Remote, Package, transports, etc. in mcp.shared.experimental.server_card.
• 28 tests, 100% line+branch coverage on the new modules; round-trips the SEP-2127 conformance example shapes.

Things to confirm before the SEP moves forward

Several decisions baked into #2696 intersect with open spec questions in this repo. We should make sure the reference impl and the spec agree (in both directions) before locking the SEP:

• Well-known path. #2696 serves and fetches at the slash form https://<host>/.well-known/mcp/server-card (twice in the PR description: the served route is GET /.well-known/mcp/server-card). This matches the direction in Standardize the Server Card well-known path on /.well-known/mcp/server-card (slash form) across schema.ts, discovery.md, and SEP-2127 #11 but currently conflicts with the dash form in schema.ts, docs/discovery.md, and SEP-2127. The reference impl is effectively a vote for the slash form — resolve Standardize the Server Card well-known path on /.well-known/mcp/server-card (slash form) across schema.ts, discovery.md, and SEP-2127 #11 and align the spec to whatever #2696 ships (or vice versa) so they don't disagree.
• Validation / source of truth. #2696 uses pure-Pydantic validation ("no separate JSON-Schema/CLI layer"), whereas this repo treats schema.ts → generated schema.json as the source of truth. Decide the relationship: are the SDK's Pydantic models generated from / checked against this repo's schema, or independently authored? Two hand-maintained shapes will drift. This is the same single-source-of-truth concern behind MCP Catalog mediaType (application/mcp-server+json) diverges from AI Catalog's application/mcp-server-card+json #9/docs/discovery.md lists tools/resources/prompts as Server Card contents, contradicting SEP-2127's exclusion of primitives #10.
• $schema URL. #2696 defaults $schema to "the canonical v1 URL." Confirm that URL is real, agreed, and matches what this repo publishes and what the SEP registers.
• Media type. Confirm what media type the client expects/validates (if any) and reconcile with MCP Catalog mediaType (application/mcp-server+json) diverges from AI Catalog's application/mcp-server-card+json #9 (application/mcp-server+json vs AI Catalog's application/mcp-server-card+json).
• Primitives excluded. #2696 "deliberately omits primitive listings (tools/resources/prompts)" — consistent with SEP-2127. Confirm docs/discovery.md is brought in line too (docs/discovery.md lists tools/resources/prompts as Server Card contents, contradicting SEP-2127's exclusion of primitives #10), so the reference impl and the prose don't contradict.
• ServerCard vs Server split. #2696's Server adds packages (the registry server.json shape) on top of ServerCard — confirm this matches schema.ts in this repo.
• Second SDK? Per the Server Card WG discussions, a TypeScript SDK reference implementation (and a FastMCP POC) were also expected. Decide whether Python alone satisfies the "at least one official SDK" bar for review, or whether we want TS before advancing.

Proposed handling

Use this issue as the tracking record for the reference-implementation gate. Keep it open until #2696 (or its successor) is merged in python-sdk and the checklist items above are resolved in this repo / the SEP. Only then should SEP-2127 advance toward Final.

Links: python-sdk#2696 · SEP-2127 (PR #2127) · #15 (Extensions Track refactor).