Skip to content

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

Open
tadasant wants to merge 7 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 7 commits into
sep/mcp-server-cardsfrom
sep-2127-extensions-track-refactor

Conversation

@tadasant
Copy link
Copy Markdown
Member

@tadasant tadasant commented Jun 8, 2026

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
Copy link
Copy Markdown
Member Author

tadasant commented Jun 8, 2026

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>
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.

2 participants