Resolves#12.
## What & why
Moves the **single-server Server Card** off a `.well-known` path. We
reserve `GET <streamable-http-url>/server-card` as the recommended
location while allowing **any unreserved URI** — the Catalog
(`/.well-known/mcp/catalog.json`) is the discovery entrypoint and
already carries each card's `url`, so clients never need to guess where
a card lives.
Adopts wording close to the resolution discussed in #12 (credit: Darrel
Miller's point that `.well-known` is for *site-wide* metadata, not
application-level metadata like an individual server's card; proposed
wording from @SamMorrowDrums and @tadasant):
> MCP Servers MAY host their Server Card at `GET
<streamable-http-url>/server-card`, which we reserve for this purpose,
though any unreserved URI is valid. MCP Servers SHOULD respect the
agreed media type wherever they choose to host it. After a client
identifies a Server Card URL from an AI Catalog or MCP Catalog, it
SHOULD request that URL expressing the Server Card media type.
### Content negotiation
A client fetching a Server Card requests its preferred representation
with the `Accept` header (`Accept: application/mcp-server-card+json`) —
the request-side content-negotiation header for a GET. The server echoes
the type it actually served back in the response's `Content-Type`.
> **Note on media type:** this PR is scoped to *placement* only and does
**not** perform the `application/mcp-server+json` →
`application/mcp-server-card+json` rename — that is handled in a
separate PR. So the two coexist deliberately here:
> - **Pre-existing strings** (catalog-entry description, the four
example `mediaType` values, validation prose, and the "Server Cards use
the media type" line) are left as `application/mcp-server+json`,
untouched, for the rename PR to sweep.
> - **New prose introduced by this PR** (the reserved-location
blockquote and the `Accept`-header example in the "Server Card Location"
section) names the type explicitly as the **post-rename
`application/mcp-server-card+json`**, since the rename PR's diff is
against `main` and would not touch text that doesn't yet exist there.
>
> The temporary mix resolves to a single consistent type once both PRs
land.
## Rationale for `/server-card` (also captured permanently in
`docs/discovery.md` → "Alternatives considered")
- **Not `.well-known`:** site-wide vs. application-level metadata; the
Catalog already provides the `url`, so `.well-known` adds no value for
the card.
- **Not the bare streamable-HTTP endpoint** (`GET <url>` with no
suffix): a GET there already opens the SSE stream in Streamable HTTP.
Hosting the card there overloads the connection-establishing endpoint
and forces content negotiation to disambiguate. Spec-*allowed*,
explicitly **not recommended** — this is the primary motivation for a
distinct suffix.
- **Not domain-root `/mcp/` nesting:** `/mcp` denotes the *transport
endpoint itself* in MCP's canonical-URI examples; there's no precedent
for `/mcp/` as a metadata sub-namespace, and it collides conceptually
with "the JSON-RPC endpoint."
- **Elegant consequence:** because the suffix is appended to the
streamable-HTTP URL, a server at `https://host/mcp` naturally yields
`https://host/mcp/server-card` — path-namespacing for free.
## Scope guardrail
This applies **only to the single-server Server Card**. `.well-known` is
unchanged and remains correct for the **Catalog**
(`/.well-known/mcp/catalog.json`) and OAuth metadata
(`/.well-known/oauth-protected-resource`, etc.) — those are genuinely
site-wide. The doc calls this out explicitly so it doesn't read as
"abandon `.well-known` everywhere."
## Files changed
- **`docs/discovery.md`** — new "Server Card Location" section with the
reserved convention + `Accept`-header guidance; permanent "Alternatives
considered" subsection; rewritten single- and multi-server example URLs
(`https://example.com/mcp/server-card`;
`https://acme.com/code-review/server-card`, `/docs-search/server-card`,
`/ci-cd/server-card`).
- **`schema.ts`** — updated the two `.well-known` doc comments
(`ServerCard` and `Server`) to the new convention.
- **`schema.json`** — regenerated from `schema.ts` (`npm run generate`).
- **`README.md`** — updated the "What is a Server Card?" line to the new
convention, normalizing the pre-existing README-vs-schema `.well-known`
mismatch.
## Verification
- [x] `npm run check` passes (schema.json in sync with schema.ts + `tsc
--noEmit` clean)
- [x] `npm run generate` run and regenerated `schema.json` committed in
the same change
- [x] `npm run validate` passes — all 7 examples validate against the
regenerated schema
- [x] `npm run format` run (prettier clean)
- [x] No single-server-card `.well-known` references remain in
`README.md`, `schema.ts`, `schema.json`, or `docs/discovery.md`
(verified via grep); remaining `.well-known` references are
Catalog/OAuth/the "Alternatives considered" explainer only
- [x] Pre-existing media-type strings left untouched — `git diff
origin/main` shows zero changes to existing
`application/mcp-server+json` strings (rename owned by a separate PR);
only the new placement prose names the post-rename
`application/mcp-server-card+json`
- [x] Examples updated and internally consistent with the new prose
- [x] Fresh-eyes subagent review performed; its one cosmetic finding was
addressed and CI re-confirmed green
- [x] CI green (see checks on this PR)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Agent (Claude) <peter@tadasant.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The 'A Server Card includes:' list in docs/discovery.md mentioned
'Capabilities — Tools, resources, and prompts the server offers',
which contradicts schema.ts and SEP-2127: Server Cards do not
enumerate primitives. Primitives remain subject to runtime listing
via the protocol's standard list operations.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace application/mcp-server+json with application/mcp-server-card+json
in docs/discovery.md to match the AI Catalog specification, which
discovery.md cites as the standard MCP Catalog entries are a subset of.
Fixes#9
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replaces the prior reconstruction with the canonical content from commit
bb3bd697 on SamMorrowDrums/modelcontextprotocol@sammorrowdrums/mcp-catalog-specification,
adapted from .mdx to plain .md (frontmatter and Mintlify components stripped,
content preserved verbatim).
Covers all of tadasant's review feedback: internal MCP Server Cards subsection,
.json well-known path, reverse-DNS identifiers, identifier MUST constraint,
cross-domain advertising language, SHOULD-publish recommendation.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add MCP Server Card subsection defining application/mcp-server+json
and link 'MCP Server Cards' references internally rather than to SEP-2127
- Reframe domain hosting language to support cross-host advertising
(catalog MAY reference servers on different web hosts)
- Switch well-known URI to /.well-known/mcp/catalog.json
- Add SHOULD-publish recommendation for organizations offering MCP services
- Make specVersion OPTIONAL with note about pushing AI Catalog to align
- Tighten identifier definition: MUST begin with urn:mcp:server: and the
remainder MUST exactly match the server card's name
- Update all examples to use reverse-DNS identifiers
- Keep Content-Type: application/json for the catalog itself
- Add cross-host advertising example and trust considerations
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add docs/discovery.md defining the MCP Catalog format for config-free
auto-discovery of MCP server cards via a well-known URI. The catalog is
a minimal, MCP-scoped subset of the AI Catalog specification.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
