MCP server card: what the check tests and how to fix it

Tracked, not scored. Looks for an MCP Server Card at <endpoint>/server-card, in an ai-catalog.json entry or a legacy path. Needs name, version, description.

Agent Discovery · Tracked, not scored

How common is it?

6% of 1223 measured sites publish a passing result (observed adoption; this check does not change the score).

Latest audit of each site under rubric v3.1. A site with nothing published counts as not passing. A partial result does not count as a pass.

What this check tests

This is a tracked check: it does not change your score. It tries three places, in order, and passes on the first card that is valid:

  1. If the audit found an MCP endpoint on your site, it requests <that endpoint>/server-card.
  2. If /.well-known/ai-catalog.json exists, it takes up to three entries whose type is application/mcp-server-card+json and fetches each entry's url (relative URLs resolve against the catalog).
  3. It reads /.well-known/mcp/server-card.json, which the audit labels legacy.

In steps 1 and 2, each fetch asks for application/mcp-server-card+json or JSON, must answer 200 with a JSON content type, and is capped at 256 KB and 5 seconds, with 10 seconds in total for the two steps together. Step 3 does not use those limits: it takes the file the audit's crawler already fetched from that well-known path, which needs a 200, a JSON content type and a body that is not the site's catch-all page. A card is valid when name, version and description are all non-empty strings.

  • Pass: a valid card was found, and the result names where.
  • Fail: at least one JSON object was found but none had all three fields; the message says which field is missing.
  • Skip: no card in any of the three places, including a response that is not valid JSON or not a JSON object (an array or a bare value is ignored, not failed). Not having an MCP server is not a failure.

On sites where any made-up path returns a 2xx page (catch-all sites), same-origin candidates in steps 1 and 2 are not fetched, so a soft-404 cannot be mistaken for a card.

Why it matters to agents

An MCP client that only knows your domain has to guess where, or whether, you host a server. The Server Card proposal gives a static JSON document that describes a remote server before any connection is opened. The SEP page shows Final status (Extensions Track) on the verification date, and the detailed schema and discovery rules live in the extension's repository, not in the core protocol specification. Cards are optional, so servers without one work as before.

Per the extension's discovery document, the recommended card location is <streamable-http-url>/server-card, clients learn card URLs from an AI Catalog at /.well-known/ai-catalog.json, and a .well-known path for each card is listed among the placements considered and not recommended. That matches the order this check uses and is why the legacy path is only a fallback.

How to fix it

Only if you run a remote MCP server: publish a card, and list it in a catalog so clients can find it from your domain.

Card, served as JSON at https://example.com/mcp/server-card:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "example-org/docs-search",
  "version": "1.0.0",
  "description": "Search the Example Co documentation."
}

Catalog, served as JSON at https://example.com/.well-known/ai-catalog.json:

{
  "specVersion": "1.0",
  "entries": [
    {
      "identifier": "urn:air:example.com:mcp:docs-search",
      "type": "application/mcp-server-card+json",
      "url": "https://example.com/mcp/server-card"
    }
  ]
}
  • The extension repository has valid and invalid example cards; its fuller example adds a remotes list with the server URL.
  • Keep the card consistent with what the running server reports; the extension treats card fields as advisory.
  • If you have no MCP server, leave this check as skipped.

Related: A2A agent card, Agent Skills index, and the overview of agent servers. If your server requires sign-in, MCP authorization checks the 401 challenge that points clients to your OAuth metadata, and Client ID Metadata Documents covers how clients can register with your authorization server. For finding the server itself, see MCP endpoint; tools that run in the browser page are a separate, experimental mechanism, covered by WebMCP imperative and WebMCP declarative.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →