MCP server cards and discovery

A server card describes an MCP endpoint for clients that support the relevant discovery convention. The card, the live endpoint and the client's protocol support must agree.

The server card lives in two places that have not converged. Deployed cards, turva.dev's among them, commonly sit at /.well-known/mcp/server-card.json. The proposal behind the card, SEP-2127, now develops as an experimental MCP extension, and its text sets a different default, the MCP endpoint URL followed by /server-card. It does not recommend a /.well-known path for the card itself, and site-level discovery instead sits in a catalog: the experimental Server Card document keeps an AI Catalog at /.well-known/ai-catalog.json, while ARD v0.91 names /.well-known/ard.json. The convention is still moving, so a client that checks only one location may miss a card that exists at the other. On 2026-10-06 SEP-2127 was merged, and its text now reads Status: Final on the Extensions Track. It recommends the MCP endpoint URL followed by /server-card, lets a card be hosted at any unreserved URI, lets an AI Catalog at /.well-known/ai-catalog.json link to or embed cards and leaves tools, resources and prompts out of the card, while the extension repository's README still labels itself Experimental. The two locations have still not converged in deployment.

An MCP server card is a small JSON file that describes a site's Model Context Protocol server so a client can find it and learn what it offers. The Model Context Protocol itself is a standard way for agents to use external tools and data. A server implements the protocol and may expose tools, resources or prompts, and the card is how that server announces itself before any connection is made.

What the card states

A useful card states the server name, the endpoint and the transport, in a shape a client can parse without guessing. Many published cards, including turva.dev's, also list the tools the server offers. The accepted proposal leaves that list to the live MCP connection instead, since a tools list answer from the running server does not depend on a separate static copy the way a list in a card does. A client may still cache that answer, and the protocol treats the cache lifetime as a freshness hint that does not guarantee the list is current.

Where discovery can fail

Finding a card is not the same as confirming the server works. A card can exist at a stale path, point to an endpoint that has moved, or name a transport the client does not support, and a client that stops at the card being found has not checked any of that. The card, the live endpoint and the client's own protocol support all have to agree before a connection succeeds, and only the connection attempt itself confirms that they do. The extension specification adds that a client MUST NOT treat a card's contents as authoritative for security or access-control decisions, and SHOULD verify the card's claims against the live connection, preferring the runtime values where the two disagree.

How it fits with other discovery files

A server card sits in the same family as other well-known manifests a client looks for, such as an API catalog, an OpenAPI description and OAuth discovery. Each one removes a guess. The card answers which MCP server a site runs and how to reach it, the API catalog answers what endpoints exist, and OAuth discovery answers how to authenticate. turva.dev publishes a server card that points to a read-only MCP server, which exposes the same agent-readiness data that the site shows to people, so a client can query the data directly rather than scraping a page.

Practical steps

Publish the card at the deployed convention your target clients actually check, and confirm it with a live connection attempt rather than a directory listing. The extension's discovery document requires HTTPS with TLS 1.2 or later in production, and CORS headers that let a browser-based client read the card, such as Access-Control-Allow-Origin: *. turva.dev's own card is served with those CORS headers. Where a client supports the location the proposal recommends, publish there too rather than choosing one over the other, since the two conventions have not converged. turva.dev itself does not yet serve its card at the MCP endpoint URL followed by /server-card. The card is a low-cost step for a site that wants to expose a capability to agents, and it only becomes useful once a client can reach and use the endpoint it names. For an audit of whether a site's MCP server card and its live endpoint agree, contact info@turva.dev.

Frequently asked

What is an MCP server card?

An MCP server card is a small JSON file that describes a site's Model Context Protocol server, its endpoint and its transport, so a client can attempt a connection without a human wiring it up first. The accepted proposal leaves the tool list to the live connection rather than to the card.

Why publish an MCP server card?

Without a card or a registry listing, a client that knows only the domain has no standard way to find the server or learn what it offers before it connects. The card is optional, so a client that is already configured with the endpoint still connects and learns the capabilities at runtime. Publishing the card is a low-cost way to make the server discoverable from the domain, though discovery alone does not confirm the endpoint works.

Where does an MCP server card live?

Deployed cards commonly sit at /.well-known/mcp/server-card.json, and turva.dev serves one there. The accepted proposal recommends a different default, the MCP endpoint URL followed by /server-card, so a client may need to check both locations until the convention settles.