Standardize the Server Card well-known path on /.well-known/mcp/server-card (slash form) across schema.ts, discovery.md, and SEP-2127

[tadasant]

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

Summary

The Server Card well-known path is spelled two different ways across the spec surface:

• slash / namespaced form /.well-known/mcp/server-card — used in this repo's README.md
• dash / flat form /.well-known/mcp-server-card — used in schema.ts, docs/discovery.md, and SEP-2127

We should converge on the slash form /.well-known/mcp/server-card everywhere, and update schema.ts, docs/discovery.md, and (upstream) SEP-2127 to match. The dash form is the one to retire.

Why the slash form

1. It nests Server Cards inside the shared /.well-known/mcp/ namespace directory. The MCP Catalog already lives at /.well-known/mcp/catalog.json (discovery.md#L29-L31). Putting the card at /.well-known/mcp/server-card keeps every MCP discovery artifact under one mcp/ directory, instead of having mcp/catalog.json and a sibling mcp-server-card that merely look related. One namespace for the protocol, many resources under it — this is exactly what a per-protocol .well-known subtree is for.
2. Postfix sub-paths for multi-server hosts fall out naturally — /.well-known/mcp/server-card/{name} sits cleanly inside the same mcp/ tree. (Note: the dash form technically supports a postfix too — SEP-2127 spells it /.well-known/mcp-server-card/{server-name} — so this isn't unique to the slash form, but the slash form keeps the postfix inside the shared namespace rather than hanging off a flat sibling.)
3. It already matches the AI Catalog's own MCP example, which uses the slash form: https://api.example.com/.well-known/mcp/server-card.json (ai-catalog.md#L124-L129).

Evidence — the current split

Slash form — README.md#L13 (link):

A **Server Card** is a JSON document, typically published at `https://<host>/.well-known/mcp/server-card`, describing:

Dash form — schema.ts#L13-L14 (link):

 * A static metadata document describing a remote MCP server, suitable for
 * publishing at a `.well-known/mcp-server-card` URI for pre-connection discovery.

Dash form — docs/discovery.md example urls (#L74-L75, #L92-L105):

      "url": "https://example.com/.well-known/mcp-server-card"
      ...
      "url": "https://acme.com/.well-known/mcp-server-card/code-review"

Dash form — SEP-2127 Endpoints (seps/2127-mcp-server-cards.md#L257-L274, PR #2127):

Servers using HTTP-based transports SHOULD provide their server card at:

    /.well-known/mcp-server-card

Hosts that serve multiple MCP servers from the same origin SHOULD expose each
server's card under a named sub-path:

    /.well-known/mcp-server-card/{server-name}

Why it matters

Clients doing path-based discovery hard-code one of these strings; a split guarantees some clients miss cards. Beyond consistency, the choice of which form is canonical is a small but real design decision: the slash form treats mcp as a namespace directory (extensible to future MCP discovery resources), whereas the dash form treats mcp-server-card as a single flat resource name that happens to share a prefix with nothing else.

.json suffix

For parity with the spelling decisions already made: the catalog carries .json (/.well-known/mcp/catalog.json) while the Server Card path is left without an extension so it can support the postfix sub-path form (/.well-known/mcp/server-card/{name}). The AI Catalog example writes server-card.json; we should pick one and state it explicitly when we converge — recommend no extension on server-card to preserve the postfix convention, matching the rationale used for the catalog-vs-card distinction.

Proposed resolution

1. Adopt /.well-known/mcp/server-card (slash form, no extension) as the canonical single-server path, and /.well-known/mcp/server-card/{name} for multi-server hosts.
2. In this repo: update schema.ts (the .well-known/mcp-server-card doc comment) and all docs/discovery.md example urls from the dash form to the slash form. README.md is already correct.
3. Upstream: raise the same change against SEP-2127 (PR #2127), whose Endpoints section currently specifies the dash form — the SEP is the canonical source the other files follow, so it needs to move too.
4. Explicitly document the .json-vs-no-extension decision for the card path while we're here.

Related: #12 (whether to use .well-known at all for single-server cards, vs a GET on the server URL — orthogonal to this spelling question).