SEP-2127: refactor to Extensions Track charter (delegate spec to experimental-ext-server-card)#2893
Open
tadasant wants to merge 7 commits into
Open
SEP-2127: refactor to Extensions Track charter (delegate spec to experimental-ext-server-card)#2893tadasant wants to merge 7 commits into
tadasant wants to merge 7 commits into
Conversation
Re-type SEP-2127 (MCP Server Cards) from Standards Track to Extensions Track and slim the body to a charter (SEP-1865 shape), delegating the detailed wire format to the experimental-ext-server-card repository. - Type -> Extensions Track; add Extension Identifier and Server Card Working Group attribution to the frontmatter (SEP-2663 conventions). - Add a top-of-file <Note> pointing to the extension repo as spec home. - Move out the Server Card schema, server.json schema, field tables, .well-known endpoint mechanics, full Security Implications, and IETF Registration; keep Abstract, Motivation, Rationale, a high-level Specification pointer, and a Security posture summary. - Replace the empty Reference Implementation section with a pointer to the incubation work; note the SDK reference implementation remains a Final-gating item. - Record open items: IANA registration, media-type and .well-known path convergence, and the discovery-doc primitives contradiction. - Regenerate docs/seps/index.mdx and docs/seps/2127-mcp-server-cards.mdx. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace Nick Cooper (@nickcoai) with Sam Morrow (@SamMorrowDrums) in the author and Extension Maintainers lines. Regenerate the rendered SEP doc. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Member
Author
|
Updated authorship in e99ebf6: removed Nick Cooper (@nickcoai) and added Sam Morrow (@SamMorrowDrums) to both the
Regenerated the rendered SEP doc accordingly. |
Soften the high-level pointers that delegate discovery to the extension repo so they read 'discovery mechanics / discovery path / Discovery' rather than presuming a '.well-known' mechanism, which is not yet settled. The deliberate design-choice references (the 'Why .well-known?' rationale, RFC 5785 discussion, and the IANA-registration / path-spelling open items) are intentionally left as-is. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The high-level Specification bullet asserted that Server Cards omit primitive listings; that decision may still change. Replace the detail with a pointer to the extension repo's schema.ts for the precise field set, keeping the charter agnostic on the contested question. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Cross-referenced the open issues in experimental-ext-server-card so the charter does not assert things the WG is still deciding: - Reference Implementation: cite python-sdk#2696 (open, in review) as the in-progress SDK reference impl instead of claiming none exists (#16). - Stop presenting .well-known as locked: add a discovery-mechanism open item for the .well-known-vs-GET-on-URL question (#12) and make the IANA registration conditional on that outcome. - Align the path/media-type open items with the reference impl's slash-form vote (#11) and the application/mcp-server-card+json direction (#9). - Add an auth-shape open item flagging the limited initial shape and the additive SEP-2742 auth fast-follow / forward-compat requirement (#13, #17). - Note that whether to add primitive listings is itself open (#10). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A published SEP is frozen and not updated over time, so process-y and temporal notes (open questions, in-progress status) do not belong in the body. Remove the "Open Items" section and rephrase Reference Implementation to a non-temporal description of the incubation repo and python-sdk#2696. These tracking notes now live in the PR description instead. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tadasant
commented
Jun 8, 2026
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refactors SEP-2127 (MCP Server Cards) from Standards Track to Extensions Track, slimming the body to a charter (SEP-1865 shape) that delegates the detailed wire format to
modelcontextprotocol/experimental-ext-server-card. Implements the "Proposed refactor" in experimental-ext-server-card#15.What changed
Type: Standards Track→Type: Extensions Track; addedExtension Identifier: io.modelcontextprotocol/server-cardand "on behalf of the Server Card Working Group" author attribution (SEP-2663 conventions). Authors are now David Soria Parra (@dsp-ant), Sam Morrow (@SamMorrowDrums), Tadas Antanavicius (@tadasant).<Note>pointing toexperimental-ext-server-cardas the spec home (closes the previously one-directional cross-reference — the repo's README already says it "tracks SEP-2127", but the SEP never pointed back)..well-knownmechanism (the deliberate "Why .well-known?" rationale and RFC 5785 discussion are kept); the high-level Specification bullet no longer states primitive exclusion as settled fact, pointing toschema.tsfor the precise field set instead.docs/seps/index.mdx(one line: track badge) anddocs/seps/2127-mcp-server-cards.mdx.npm run check:sepsis green.Line anchors below pin SEP-2127 to its PR-head SHA
aa59517and the extension repo to its current headffe58b0, so they don't rot.Translation / deletion audit
For every block removed from the SEP, where it now lives, an inline excerpt of the surviving copy, a permalink, and a verdict. TL;DR: the two schemas and field tables are fully translated (and stricter) in the repo; endpoint mechanics + security live in
docs/discovery.md; the discovery mechanism itself is being revised (proposal to drop.well-known, #12), which also obsoletes the old IANA.well-knownregistration; the one security gap (DoS) is now filed as an extension-repo issue, and the primitives contradiction is tracked in #10.1.
### MCP Server Card Schema+ Field Descriptions — fully translatedDeleted: SEP-2127 L80–158 (schema + example) and L159–175 (field descriptions:
$schema,name,version,description,title,websiteUrl,repository,icons,remotes,_meta).Counterpart:
schema.ts→interface ServerCard, generatedschema.json, andexamples/ServerCard/valid/.The repo carries all ten fields plus validation constraints (length/pattern) the SEP described only in prose, so this is a strict superset of the deleted content. Verdict: fully translated — deletion is safe.
2.
### server.json Schema+ Field Descriptions — fully translatedDeleted: SEP-2127 L176–248 (the
server.jsonsuperset addingpackages) and its field descriptions L249–255.Counterpart:
schema.ts→interface Server extends ServerCardwith thePackage/PackageTransporttypes (L228+) andexamples/Server/valid/with-package.json.The "strict superset adds
packages" relationship the SEP described is exactly modeled byServer extends ServerCard. Verdict: fully translated — deletion is safe.3.
### Endpoints/.well-known URImechanics — translated todocs/discovery.md; discovery mechanism being revised (ext-repo #12)Deleted: SEP-2127 L257–305 — the
.well-knownpath, multi-server sub-path, HTTPS/CORS/caching requirements. (Alternatives — DNS- and header-based discovery, L306–310 — were kept in the SEP under Rationale → "Other Considered Discovery Mechanisms", as design rationale rather than wire format.)Counterpart:
docs/discovery.mdcarries the CORS block (L177–185), caching (L189–195), and HTTPS transport security (L197–200):How the discovery mechanism is being handled. Rather than carry a
.well-knownpath into the charter, we are going to propose dropping.well-knowndiscovery for the single-server case entirely — letting an AI/MCP Catalog point to a Server Card hosted at any URI (e.g. a reservedGET <streamable-http-url>/server-card) instead of treating the card as site-wide.well-knownmetadata. That proposal is tracked in experimental-ext-server-card#12, which is the thread that will settle the canonical retrieval mechanism. The charter therefore delegates the path/mechanism todocs/discovery.mdand does not hard-code.well-known, so it stays correct as #12 lands.Because the
.well-knownapproach is on its way out, the old SEP's IANA.well-knownURI-suffix registration (deleted SEP L389–399, the former "IETF Registration" section) is intentionally not carried into the charter — registering a.well-knownsuffix only makes sense if.well-knownsurvives, which #12 proposes it won't. (Whether to register a content media type is a separate question, tracked in #9.)Verdict: endpoint mechanics translated to
docs/discovery.md; the discovery mechanism — and with it the need for.well-knownand any IANA registration of it — is being revised under #12.4.
## Security Implications— partially translated; one gap (now filed), one contradiction (#10)Deleted: SEP-2127 L354–384 — Information Disclosure, Primitive Information, CORS, Denial of Service, MITM. A condensed posture summary of all five was kept inline in the charter (SEP-1865 keeps a short Security Implications section + pointer), so nothing was dropped without a charter-level trace.
Counterparts in
docs/discovery.md→ Security Considerations:schema.tsL16–19 (correct) vs. discovery.md L143 (contradicts)Two caveats:
docs/discovery.md. Rather than silently drop it, the rate-limiting guidance is retained in the charter's Security summary, and I filed experimental-ext-server-card#21 to add DoS / rate-limiting guidance to the repo's Security Considerations.schema.tsagrees with the SEP (primitives excluded);discovery.mdL143 contradicts it. Deleting the SEP's "Primitive Information" paragraph is safe because the correct copy survives inschema.ts— butdiscovery.mdis the wrong copy and must be fixed per #10. The charter no longer states primitive exclusion as a locked fact (whether to add primitives is itself open), but keeps the "Why Exclude Primitives?" rationale describing the current shape.Verdict: posture translated + summarized inline; the DoS gap is now filed as an extension-repo issue; the primitives contradiction is tracked in #10.
5.
## IETF Registration— folded into §3 (obsoleted by the.well-knownremoval)The deleted "IETF Registration" section (SEP-2127 L389–399) only existed to register the
.well-knownURI suffix with IANA. Since #12 proposes dropping.well-knowndiscovery (see §3), that registration is no longer needed and is intentionally not carried into the charter. (Media-type registration is a separate, still-open question — #9.)Notes
sep/mcp-server-cards, notmain.sep-guidelines.mdx/TEMPLATE.mdstill list only three SEP types; the Extensions Track added by SEP-2133 was never backfilled there. Backfilling them is out of scope for this PR (worth a separate process issue) — but this refactor relies on the precedent set by the two Final Extensions Track SEPs (1865, 2663).