# MCP server card: the path, an example, and how an agent finds it > Where to publish an MCP server card, a server-card.json example, and how /.well-known/ard.json lists it. The path question, checked against SEP-2127. - Source: /learn/mcp-server-card - Updated: 2026-10-27 - Reading time: 6 minutes - Tags: MCP, server cards, ARD, discovery --- 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](https://modelcontextprotocol.io/seps/2127-mcp-server-cards) is an Extensions Track proposal, created on 21 January 2026. Its [pull request](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) 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](https://agenticresourcediscovery.org/spec/), 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](https://developers.googleblog.com/announcing-the-agentic-resource-discovery-specification/) 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](https://github.com/modelcontextprotocol/experimental-ext-server-card/blob/main/docs/discovery.md), read on 27 October 2026, tell clients to try `/.well-known/ai-catalog.json` and do not mention ARD. [Lighthouse 13.5.0](https://github.com/GoogleChrome/lighthouse/releases/tag/v13.5.0), released on 18 September 2026, added an `ard-schema` audit titled “`ai-catalog.json` schema is valid”. Its [gatherer](https://github.com/GoogleChrome/lighthouse/blob/v13.5.0/core/gather/gatherers/agentic/ard.js) reads an `Agentmap:` line in robots.txt, then a `rel="ai-catalog"` link, then `/.well-known/ai-catalog.json`. A reader [reported](https://github.com/GoogleChrome/lighthouse/issues/17251) on 22 September that the audit ignores `ard.json`. The fix, [pull request #17258](https://github.com/GoogleChrome/lighthouse/pull/17258), was merged into the main branch on 9 October, and [main's gatherer](https://github.com/GoogleChrome/lighthouse/blob/main/core/gather/gatherers/agentic/ard.js) 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](/checks/ard-manifest) 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](/checks/mcp-card) and the [MCP server check](/checks/mcp-server) 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](/learn/ard-json-agentic-resource-discovery) 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: ```json { "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`: ```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](https://github.com/modelcontextprotocol/experimental-ext-server-card/blob/main/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 `/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](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/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](https://blog.modelcontextprotocol.io/posts/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`](https://modelcontextprotocol.io/specification/2026-07-28/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 ```sh 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](/learn/test-mcp-server-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](/aws/resend.com) has the full detail, and [the 5-site comparison](/learn/five-sites-agent-readiness-october-2026) has the rest of each record. ## How AgenticWebScore reads a card The [MCP server card check](/checks/mcp-card) 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](/checks/mcp-server) 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](/methodology#readiness-levels) 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. `/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](/learn/agent-tools-not-pages). To see which card the scanner finds on your site, and whether the server behind it answers, [scan your site](/scan).