MCP Server Discovery: How .well-known/mcp/server-card (SEP-2127) Works

The Model Context Protocol has always had a discovery gap. Once a client knows a server's URL, the protocol specifies everything — the initialize handshake, capability negotiation, tools/list. But finding that URL was left to READMEs, registry listings, and word of mouth. SEP-2127 closes part of that gap with the MCP server card: a JSON document at a well-known URI that describes an HTTP-based MCP server before any client connects.

This post covers what the server card contains, its current standardization status (experimental — worth knowing before you depend on it), and how it fits alongside the other ways MCP servers get discovered today.

The Well-Known Path

Following RFC 8615 — the same mechanism behind OpenID Connect's /.well-known/openid-configuration and A2A's /.well-known/agent-card.json — a server card lives at:

https://{domain}/.well-known/mcp/server-card

A client, crawler, or registry that knows only your domain can fetch this one document and learn what MCP surface you expose. For hosts running multiple servers, the proposal also sketches a catalog variant listing several servers on one domain.

What a Server Card Contains

The card deliberately stays at the discovery altitude — enough to decide whether to connect, not a dump of the server's contents:

Field group	What it covers
Identity	Server name, title, version, description
Links	Website, repository, documentation
Remotes	Transport endpoints (Streamable HTTP URL), one entry per remote
Auth	Authentication configuration per remote (e.g. OAuth 2.0)
Capabilities	Coarse indicators of what the server offers

Notably absent: the full tools, resources, and prompts listings. That's intentional. Primitive listings change frequently and can be large; clients get them from tools/list after connecting. The card answers "should I connect?" — the protocol answers "what exactly is here?"

Standardization Status: Experimental, Not Final

SEP-2127 was merged, then refactored to MCP's extensions track and delegated to an experimental extension repository for continued iteration. Concretely, that means:

The exact path and media type may still shift before final standardization.
Client support is opt-in and sparse — publishing a card today is a bet on the direction, not a compatibility requirement.
The charter direction is settled: HTTP-based MCP servers should eventually advertise themselves via well-known metadata.

The cost of publishing is one static JSON file; the upside is being indexable by every early crawler and registry that adopts the convention. That asymmetry is why publishing early is rational even while the spec is experimental.

How Discovery Works Without a Card

Since most MCP servers don't publish cards yet, clients and scanners fall back to active probing — and understanding this explains what your server broadcasts whether or not you publish anything:

The /mcp path convention. Remote servers overwhelmingly serve Streamable HTTP at https://domain.com/mcp. Probing tools POST a JSON-RPC initialize there.
The initialize handshake as fingerprint. A real MCP server answers initialize with serverInfo, protocolVersion, and capabilities — a definitive, unforgeable identification. The response may arrive as plain JSON or as an SSE-framed text/event-stream; both are valid Streamable HTTP.
The OAuth challenge as signal. An auth-protected server returns 401 with a WWW-Authenticate header pointing at RFC 9728 protected-resource metadata (/.well-known/oauth-protected-resource). To a scanner, that combination reads "MCP server present, authentication required" — GitHub's api.githubcopilot.com/mcp is the canonical example.

In other words: a remote MCP server is already discoverable through its protocol behavior. The server card just makes discovery cheap, passive, and crawlable.

Checklist for Server Operators

Serve Streamable HTTP at /mcp (or document why not — a nonstandard path costs you probe-based discovery).
Answer initialize correctly from a cold client, including the SSE response framing if you use it.
If authenticated: return 401 + WWW-Authenticate with resource_metadata, and serve valid RFC 9728 metadata. A bare 403 with no challenge makes your server indistinguishable from a broken one.
Publish a server card at /.well-known/mcp/server-card with name, version, description, remotes, and auth config.
Set Cache-Control: public, max-age=3600 on the card so crawlers don't hammer your origin.

You can verify all of it from the outside in one pass with the MCP Inspector — it fetches your server card, runs a live initialize handshake (SSE-aware), enumerates tools/list, and correctly classifies OAuth-protected servers instead of reporting them as failures.

Where This Is Heading

Server cards are one layer of a discovery stack that's assembling quickly: MCP server cards describe one server, A2A agent cards describe one agent, and the new ARD ai-catalog.json spec from Google, Microsoft, and Hugging Face indexes all of them per-domain for registry crawling. The direction is unmistakable — agent capabilities are becoming crawlable infrastructure, the way web pages became crawlable in 1998. Publishing the metadata now costs an afternoon; being absent from the first generation of agent registries costs distribution.