Skip to content

SEP-2127: refactor to Extensions Track charter (delegate spec to experimental-ext-server-card)#2893

Open
tadasant wants to merge 8 commits into
sep/mcp-server-cardsfrom
sep-2127-extensions-track-refactor
Open

SEP-2127: refactor to Extensions Track charter (delegate spec to experimental-ext-server-card)#2893
tadasant wants to merge 8 commits into
sep/mcp-server-cardsfrom
sep-2127-extensions-track-refactor

Conversation

@tadasant

@tadasant tadasant commented Jun 8, 2026

Copy link
Copy Markdown
Member

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

  • Frontmatter: Type: Standards TrackType: Extensions Track; added Extension Identifier: io.modelcontextprotocol/server-card and "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).
  • Top-of-file <Note> pointing to experimental-ext-server-card as 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).
  • Slimmed to a charter (405 → 191 lines): kept Abstract, Motivation, Rationale, a high-level Specification pointer, a Security posture summary, Backward Compatibility, Reference Implementation, and WG/maintainers. Moved the detailed normative content out to the extension repo.
  • Charter stays agnostic on contested questions. Generic delegation references no longer presume a .well-known mechanism (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 to schema.ts for the precise field set instead.
  • Reference Implementation section points at the extension repo (schema source of truth + examples) and at python-sdk#2696, the experimental Python SDK implementation by @dsp-ant.
  • The SEP body is kept non-temporal. A published SEP is frozen and not updated over time (e.g. SEP-1865 as published), so process-y / in-flight notes do not belong in it. There is no "Open Items" section in the SEP; the unresolved cross-cutting questions surfaced by the open issues in the extension repo (discovery mechanism, media type, auth shape, primitives) are tracked here in this PR description and in the extension-repo issues instead — see the audit and reconciliation below.
  • Regenerated docs/seps/index.mdx (one line: track badge) and docs/seps/2127-mcp-server-cards.mdx. npm run check:seps is green.

Line anchors below pin SEP-2127 to its PR-head SHA aa59517 and the extension repo to its current head ffe58b0, 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-known registration; 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 translated

Deleted: SEP-2127 L80–158 (schema + example) and L159–175 (field descriptions: $schema, name, version, description, title, websiteUrl, repository, icons, remotes, _meta).

Counterpart: schema.tsinterface ServerCard, generated schema.json, and examples/ServerCard/valid/.

// schema.ts L27-L52
export interface ServerCard {
  /** ... @pattern ^https://static\.modelcontextprotocol\.io/schemas/v1/[^/]+\.schema\.json$ */
  $schema: string;
  /** Server name in reverse-DNS format. ... @pattern ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$ */
  name: string;
  ...
}

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 translated

Deleted: SEP-2127 L176–248 (the server.json superset adding packages) and its field descriptions L249–255.

Counterpart: schema.tsinterface Server extends ServerCard with the Package / PackageTransport types (L228+) and examples/Server/valid/with-package.json.

// schema.ts L135-L140
export interface Server extends ServerCard {
  /** Metadata for running and connecting to local instances of this MCP server. */
  packages?: Package[];
}

The "strict superset adds packages" relationship the SEP described is exactly modeled by Server extends ServerCard. Verdict: fully translated — deletion is safe.

3. ### Endpoints / .well-known URI mechanics — translated to docs/discovery.md; discovery mechanism being revised (ext-repo #12)

Deleted: SEP-2127 L257–305 — the .well-known path, 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.md carries the CORS block (L177–185), caching (L189–195), and HTTPS transport security (L197–200):

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: Content-Type

How the discovery mechanism is being handled. Rather than carry a .well-known path into the charter, we are going to propose dropping .well-known discovery for the single-server case entirely — letting an AI/MCP Catalog point to a Server Card hosted at any URI (e.g. a reserved GET <streamable-http-url>/server-card) instead of treating the card as site-wide .well-known metadata. 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 to docs/discovery.md and does not hard-code .well-known, so it stays correct as #12 lands.

Because the .well-known approach is on its way out, the old SEP's IANA .well-known URI-suffix registration (deleted SEP L389–399, the former "IETF Registration" section) is intentionally not carried into the charter — registering a .well-known suffix only makes sense if .well-known survives, 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-known and any IANA registration of it — is being revised under #12.

4. ## Security Implicationspartially 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:

SEP sub-section Repo counterpart Verdict
Information Disclosure discovery.md L168–175 translated
CORS Requirements discovery.md L177–187 translated
MITM / Transport Security discovery.md L197–200 translated
Primitive Information schema.ts L16–19 (correct) vs. discovery.md L143 (contradicts) ⚠️ #10
Denial of Service (none) gap
// schema.ts L16-L19 — primitives excluded (the SEP's correct position)
* They do not enumerate primitives (tools, resources, prompts)  those remain
* subject to runtime listing via the protocol's standard list operations.
// discovery.md L143 — contradicts: lists primitives as card contents
- **Capabilities** — Tools, resources, and prompts the server offers

Two caveats:

  • Gap — Denial of Service. The SEP's rate-limiting paragraph (L377–379) has no counterpart in 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.
  • ⚠️ Primitive contradiction (#10). schema.ts agrees with the SEP (primitives excluded); discovery.md L143 contradicts it. Deleting the SEP's "Primitive Information" paragraph is safe because the correct copy survives in schema.ts — but discovery.md is 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 Registrationfolded into §3 (obsoleted by the .well-known removal)

The deleted "IETF Registration" section (SEP-2127 L389–399) only existed to register the .well-known URI suffix with IANA. Since #12 proposes dropping .well-known discovery (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

  • Base is David's branch sep/mcp-server-cards, not main.
  • The published sep-guidelines.mdx / TEMPLATE.md still 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).

Tadas Antanavicius and others added 2 commits June 8, 2026 00:04
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>
@tadasant

tadasant commented Jun 8, 2026

Copy link
Copy Markdown
Member Author

Updated authorship in e99ebf6: removed Nick Cooper (@nickcoai) and added Sam Morrow (@SamMorrowDrums) to both the Author(s) frontmatter and the Extension Maintainers list. Author line is now:

David Soria Parra (@dsp-ant), Sam Morrow (@SamMorrowDrums), Tadas Antanavicius (@tadasant); on behalf of the Server Card Working Group

Regenerated the rendered SEP doc accordingly.

Tadas Antanavicius and others added 4 commits June 8, 2026 00:51
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>
Comment thread docs/seps/2127-mcp-server-cards.mdx Outdated
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@SamMorrowDrums SamMorrowDrums left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing the conversion work

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

proposal SEP proposal without a sponsor. SEP

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

3 participants