MCP server card: the path, an example, and how an agent finds it

An agent finds your MCP server through a server card, a JSON file that names the server and says where to connect. List the card in a manifest at /.well-known/ard.json, the path Agentic Resource Discovery (ARD) v0.91 names. Serve the same manifest at /.well-known/ai-catalog.json too, because the MCP extension that defines the card and the released Lighthouse still read that older path.

The card comes from SEP-2127, merged on 6 October 2026 as an optional MCP extension, not as part of the core protocol.

What SEP-2127 is, and its status

SEP-2127 is an Extensions Track proposal, created on 21 January 2026. Its pull request was merged on 6 October 2026, and the SEP page now shows the status Final. The SEP charters the extension. The wire format lives in the extension's own repository, where schema.ts is the source of truth.

The extension is optional. In the SEP's words, servers without a card “continue to work normally” over a standard connection. A card saves a client from being given the endpoint by hand. The client still learns what the server offers by connecting to it.

Which manifest path: ard.json or ai-catalog.json?

Serve both. The manifest has had two paths, and the readers you want to be found by sit on both sides of the rename.

ARD names ard.json. ARD v0.91, a proposal dated 26 August 2026, puts the manifest at /.well-known/ard.json (§5.1). Consumers must fetch that path and honour a rel="ard" link. The spec calls /.well-known/ai-catalog.json and rel="ai-catalog" the predecessor: a consumer may still read them, and a publisher on the old path should move. Google's announcement of 17 June 2026 had publishers hosting an ai-catalog.json file, 10 weeks before the rename.

The MCP extension and Lighthouse name ai-catalog.json. The extension's discovery notes, read on 27 October 2026, tell clients to try /.well-known/ai-catalog.json and do not mention ARD. Lighthouse 13.5.0, released on 18 September 2026, added an ard-schema audit titled “ai-catalog.json schema is valid”. Its gatherer reads an Agentmap: line in robots.txt, then a rel="ai-catalog" link, then /.well-known/ai-catalog.json.

A reader reported on 22 September that the audit ignores ard.json. The fix, pull request #17258, was merged into the main branch on 9 October, and main's gatherer now tries ard.json before ai-catalog.json. On 27 October the newest numbered release was still 13.5.0, so the released Lighthouse reads only the old path.

The scanner reads ard.json with one gap. The ARD manifest check requests /.well-known/ard.json, /.well-known/agent-resources.json, /.well-known/ai-catalog.json and /ard.json, and follows a rel="ard" link on the homepage. The MCP server card check and the MCP server check read the catalog only at /.well-known/ai-catalog.json. A card listed only in ard.json is not found through the catalog. ard.json and ai-catalog.json explained covers the manifest's fields and what Lighthouse reads.

An ARD manifest entry and a server card

ARD requires identifier, displayName and type on every entry, and exactly one of url or data. The MCP notes' example leaves out displayName, so add it for ARD readers. specVersion comes from the AI catalog format, and ARD v0.91 does not define it. This is the manifest for 1 server:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:example.com:mcp:docs",
      "displayName": "Example docs MCP server",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card"
    }
  ]
}

The card it points to, server-card.json:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "com.example/docs",
  "version": "1.2.0",
  "title": "Example docs",
  "description": "Search and read the public documentation of example.com.",
  "websiteUrl": "https://example.com/docs",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "supportedProtocolVersions": ["2025-11-25"]
    }
  ]
}

What each field holds, from the current schema.ts:

• name is required: a reverse-DNS name with exactly 1 slash, such as com.example/docs.
• version and description are required. The description is at most 100 characters.
• title, websiteUrl, repository and icons are optional display fields.
• remotes lists the endpoints. Each has a type (streamable-http or sse), a url, and optional headers, variables and supportedProtocolVersions.
• _meta holds namespaced vendor data.
• $schema is marked required, with 1 fixed URL. On 27 October 2026 that URL answered 404.

The discovery notes ask for application/ai-catalog+json on the catalog and application/mcp-server-card+json on the card, and have a client request the card with Accept: application/mcp-server-card+json. They also ask the card's host for Access-Control-Allow-Origin: *, Cache-Control: public, max-age=3600 and an ETag.

/.well-known/mcp.json or /.well-known/mcp/server-card.json: which path?

Neither path is in SEP-2127. Publish the card at <your MCP endpoint>/server-card, list it in the manifest, and add /.well-known/mcp/server-card.json if you want today's readers to find it.

The two paths come from SEP-1649, the earlier proposal, opened on 14 October 2025 and closed on 26 January 2026 with its work continued in the pull request for SEP-2127. Its abstract named .well-known/mcp.json. Its specification section named /.well-known/mcp/server-card.json, and a commenter asked which one was meant.

SEP-2127 dropped a well-known path for individual cards. The discovery notes say .well-known is for site-wide metadata and that the catalog's url already says where a card is. Neither the SEP nor the notes mention mcp.json.

Servers use the second path anyway. Cloudflare, Resend and this site serve /.well-known/mcp/server-card.json, and the scanner reads it before the legacy paths /.well-known/mcp.json and /mcp.json. The question is not closed: the MCP roadmap of 22 August 2026 says the Server Card working group “continues to work through the .well-known metadata conventions”.

The notes also advise against serving the card on a GET to the MCP endpoint itself. In the Streamable HTTP transport, that GET already has a meaning.

What a server card does not hold

A card lists no tools, resources or prompts, and the SEP leaves them out on purpose. The tools a server exposes can change with the user, the session and the deployment, and a static file cannot track that. Capabilities are left out for the same reason. An agent learns the tools from tools/list after it connects.

A card is also unverified when it is read. The discovery notes say clients must not base security or access-control decisions on it, and should prefer the live values when the 2 disagree. The live values come from server/discover on a 2026-07-28 server, or from initialize on an older one. Generate the card from the running server, so its name, version and protocol versions match.

Some cards carry a tools array anyway. This site's own card at /.well-known/mcp/server-card.json carries tools and capabilities. The extension defines neither field, so no client can rely on them.

How to check a card with curl

curl -sS https://example.com/.well-known/ard.json \
  | jq '.entries[] | select(.type == "application/mcp-server-card+json")'

curl -sS -H 'Accept: application/mcp-server-card+json' \
  https://example.com/mcp/server-card \
  | jq '{name, version, remotes}'

Then open a session with the URL in remotes. Testing an MCP server with curl walks through the 3 requests. The discovery notes call an inaccurate card a mild confusion or downgrade vector: an agent configures the endpoint it names, and the connection fails.

What the scan records show

On 20 October 2026, AgenticWebScore measured 5 well-known sites. Three of them publish something for MCP discovery:

• Cloudflare. Its card at /.well-known/mcp/server-card.json names https://docs.mcp.cloudflare.com/mcp. That server answered and listed 2 tools.
• Resend. Its AI catalog lists a card on mcp.resend.com. Its card at /.well-known/mcp/server-card.json names the server resend, which is not a reverse-DNS name, and has 0 remotes entries. An agent learns that the server exists and not where it is.
• GitHub. Its AI catalog lists a card at https://api.githubcopilot.com/mcp/server-card, on another site.

The scan record for Resend has the full detail, and the 5-site comparison has the rest of each record.

How AgenticWebScore reads a card

The MCP server card check reads the card the AI catalog lists first, then /.well-known/mcp/server-card.json, then the legacy paths /.well-known/mcp.json and /mcp.json. A card counts when it has a reverse-DNS name, a version and a description. It also needs at least 1 remotes entry with a transport type, a URL and protocol versions. A remote marked "status": "declared" is a promise and does not count.

The check accepts $schema and does not require it, because the schema URL does not resolve. It is an unscored check, so it earns no points.

The MCP server check then connects to the endpoint the card names. It opens a remote only on the site's own host or a subdomain of it. A card on another site, such as GitHub's, is never requested.

Since 25 October 2026, the check also reads a card that a site's catalog lists on its own subdomain, such as Resend's on mcp.resend.com. The records of 20 October predate that change. Level 5 counts an MCP server only when a card or the catalog led to it and it lists a tool.

Publish a card in 4 steps

1. Pick the card URL. <your MCP endpoint>/server-card is the reserved default.
2. Write the card from the running server's own values, and serve it with the media type, CORS and cache headers above.
3. List it in /.well-known/ard.json, with type set to application/mcp-server-card+json. Serve the same file at /.well-known/ai-catalog.json.
4. Serve the same card at /.well-known/mcp/server-card.json too, if you want readers of the older path to find it. This scanner is one of them.

The comparison of cards, skills and in-page tools is in Tools, not pages. To see which card the scanner finds on your site, and whether the server behind it answers, scan your site.