MCP Server Card — /.well-known/ai-catalog.json
TL;DR
An MCP Server Card is a small JSON file that tells an MCP client (Claude, an IDE, an agent) where your remote MCP server is and which protocol versions it speaks — before it connects. SEP-2127, final since October 2026, puts the card behind an AI Catalog at /.well-known/ai-catalog.json. The card lists no tools: the client asks the server for those after it connects.
Explain Simply
A building has a directory board in the lobby. The board does not list everything each office does; it says which floor the office is on and which door to use. You go there and ask what they can do for you.
The two files (SEP-2127 + AI Catalog 1.0):
GET /.well-known/ai-catalog.json
Content-Type: application/ai-catalog+json
{"specVersion": "1.0",
"entries": [
{"identifier": "urn:air:example.com:mcp:weather",
"type": "application/mcp-server-card+json",
"url": "https://example.com/mcp/server-card"}
]}
GET https://example.com/mcp/server-card
Accept: application/mcp-server-card+json
{"$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
"name": "com.example/weather",
"version": "1.0.0",
"description": "Weather forecasts for any city.",
"remotes": [{"type": "streamable-http", "url": "https://example.com/mcp"}]}The rules that matter:
- Domain discovery goes through the AI Catalog: specVersion and an entries array; an MCP entry has type application/mcp-server-card+json, an identifier, and exactly one of url (the card is elsewhere — any host) or data (the card inline).
- The card needs $schema (exactly the /v1/ server-card schema URL), name in namespace/name form with one slash, version (a version, not a range such as ^1.2.0) and description (1-100 characters).
- remotes lists the endpoints: type streamable-http or sse, and a url. A card without remotes is valid but tells the client nothing about where to connect.
- No tools, resources or prompts: they can differ per user and session, so the client gets them from tools/list after connecting.
- The reserved default location for a card is <your MCP URL>/server-card, e.g. https://example.com/mcp/server-card.
Not the final format: /.well-known/mcp.json (SEP-1649, closed) and /.well-known/mcp/server-card.json (an earlier SEP-2127 draft, often with a serverInfo object and a tools list) are pre-final. A client that follows SEP-2127 reads only the AI Catalog.
⚡Why It Matters
Today a user has to copy an MCP URL into each client by hand. With a catalog and a card, a client can be pointed at your domain and set itself up, and registries can index your server. On 24 October 2026 CiteStat checked 7 sites: github.com passed (catalog → card on api.githubcopilot.com); developers.cloudflare.com had the right catalog, but its card description is 355 characters (the limit is 100); blog.cloudflare.com and isitagentready.com used the pre-final path; vercel.com has a catalog with no MCP card. A site without a remote MCP server does not need a card — that is why a missing card is low severity.
🔍How CiteStat Checks
CiteStat fetches /.well-known/ai-catalog.json, picks the entries of type application/mcp-server-card+json, and reads up to 5 cards (inline, or fetched from the entry's url — only public addresses). It passes when one card is valid against the v1 schema and lists at least one remote. A valid card with no remotes, a catalog with no MCP entry, or a JSON file only at /.well-known/mcp/server-card.json or /.well-known/mcp.json is low. A catalog without specVersion/entries or a card that breaks the schema is medium. An HTML page at the path counts as no file.
CiteStat Score Impact
One of the 9 core checks on the Agent Readiness card (score = core checks passed / 9 × 10). It does not change the headline SEO score.
Fix Difficulty
Editor: Hard | Developer: Easy | AI Agent: Easy