experimental-ext-server-card

One thing we keep running into with the current spec direction: without tool definitions in the card, the card doesn't really tell you what a server does. The spec defers primitives because servers are dynamic, but there's a whole class of consumers that will never connect to a live MCP server like registries, developer portals, agent orchestrators planning tool routing. For them the card ends up like an API catalog that lists URLs but no operations. The OpenAPI parallel feels apt here: static documentation of what a server supports, used for discovery not execution. That model works well in practice and I think the same approach can work for MCP tools. The fix seems straightforward: add optional tools, resources, and prompts arrays using the existing MCP types. Dynamic servers just don't set them. Clients still use tools/list at runtime as the source of truth. The static list is for discovery, not execution. We built an open-source renderer that already visualizes static tool definitions from card JSON and it works really well in practice. Happy to demo if helpful. Related: SEP-2127 comment

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, , not merged (created 2026-05-26; supersedes #2692, which was example-app-only). It adds, under experimental namespaces: Server side — to derive a card from a server's identity, plus / to serve it via Starlette. Client side — / / to fetch and validate a card for pre-connection discovery. Models — Pydantic , , , , transports, etc. in . 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 (twice in the PR description: the served route is ). This matches the direction in #11 but currently conflicts with the dash form in , , and SEP-2127. The reference impl is effectively a vote for the slash form — resolve #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 → generated 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 #9/#10. [ ] URL. #2696 defaults 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 #9 ( vs AI Catalog's ). [ ] Primitives excluded. #2696 "deliberately omits primitive listings (tools/resources/prompts)" — consistent with SEP-2127. Confirm is brought in line too (#10), so the reference impl and the prose don't contradict. [ ] vs split. #2696's adds (the registry shape) on top of — confirm this matches 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!~ python-sdk#2951 · SEP-2127 (PR #2127) · #15 (Extensions Track refactor).

Adds and links it from the README. Docs-only; no schema or code changes. The doc speaks for itself — read it here. This description covers only what it does not say about itself. Why The repo documents the mechanics of Server Cards but never says when to serve one, or what a client should do with one it finds. This fills that gap as advisory guidance layered on the normative material in the README, , and the AI Catalog spec. Positions worth reviewing explicitly These are judgment calls, not obvious consequences of the spec. Argue with them here: Default-on probing for user-entered URLs is stated as a floor for client implementors, with tool-call results and network egress explicitly recommended _off_ by default until the pattern proves out. That's a recommendation this repo has not made before. Installs are held to a stricter bar than tool calls — no autonomous installation. Client examples are all Goose. One real AAIF maintained client, concretely, rather than only an abstraction over several Relationship to other work ⚠️ #42 should merge first. This is a content dependency, not just a link check. on still specifies the MCP Catalog at ; this doc tells implementors to publish and probe . Until #42 ("Use AI Catalog for Server Card discovery", ) lands, the two docs in disagree on the single most load-bearing URL. There is no textual conflict — this PR touches only and , and the anchors it uses survive #42 — but merging this first would ship an internally inconsistent directory. #33** (ETag + conditional requests) is anticipated client-side without restating it normatively — that belongs in if #33 lands. Closes #40. Verification [x] , , pass [x] Rebased onto current ; picks up the terminology change from #37 [x] Internal anchors resolve, and are checked against #42's post-merge headings [x] Field names checked against / ; remaining Goose citations re-verified against live docs (dead sandbox link dropped, AAIF attribution corrected) [x] No MCP-Catalog / references introduced (grep-clean) [x] No changes outside and