MCP and A2A manifests under .well-known: what squirrel finds

What a well-known agent manifest is

A manifest at a fixed path lets an agent discover a service without a person reading documentation first. Three are in use.

• An MCP server card describes a Model Context Protocol endpoint: where it is and what transport it speaks.
• An A2A agent card, at /.well-known/agent-card.json, describes an agent another agent can talk to.
• An agent-skills manifest, at /.well-known/agent-skills/index.json, lists a packaged set of skills.

One older path is worth removing rather than adding. /.well-known/ai-plugin.json described a ChatGPT plugin, a format that has been retired. A stale one still sitting on a server describes a service that no longer works.

What squirrel checks

The rule runs once per crawl against probed well-known paths. A probe counts as a hit when it returned 200, the body parsed as JSON, and it did not sniff as HTML. It emits one or more checks:

• well-known-agent: reports at info status with Agent manifests not checked: <reason> and the value not-checked when no well-known probe ran, or when there is no hit and at least one manifest path was never requested or got no answer (listed in details.notChecked). The reason is the discovery probe was not sent, or the discovery probe got no answer when any of those went out. With every path answered and no hits it reports at info status with No MCP server card, A2A agent card, or agent-skills manifest found and the value absent.
• well-known-agent-present: one check per manifest kind, at info status, with the message <kind> found at <path>. Only the first hit for each kind is reported. When the JSON carries none of the keys url, name, transport, endpoint or version, matched case-insensitively, the message gains the suffix (JSON present, but no plausible manifest fields recognized).
• well-known-agent-deprecated: emitted only when /ai-plugin.json or /.well-known/ai-plugin.json is a hit. It warns with the message Found deprecated OpenAI plugin manifest at <path> — this format was retired; remove it to avoid confusing modern agents.

The MCP card is probed at four paths: /.well-known/mcp/server-card.json, /.well-known/mcp.json, /.well-known/mcp and /.well-known/mcp-server. Absence of every manifest is a single quiet info result and never a warning, because adoption is still rare. The one thing this rule warns about is the stale file.

A probe goes unsent when discovery probes are turned off, when no rule that reads it was enabled for the crawl, or when the crawl’s preamble time budget ran out first. A probe that went out and got no answer, a refused connection or a timeout, counts the same. None of those says anything about the site, so the result is not-checked, never absent.

How to fix it

There is nothing to add unless the site backs an MCP server, an A2A agent or a skill set. If it does, publish the manifest at its conventional path:

{
  "name": "Acme MCP",
  "version": "1.0.0",
  "url": "https://mcp.example.com",
  "transport": "streamable-http"
}

If the report names a deprecated plugin manifest, delete the file. It describes a format that no client uses.

There is no common false positive. A JSON document that happens to 200 at one of these paths is reported with the note about unrecognised fields rather than being counted as a working manifest.

Enable / disable

Disable this rule

[rules]
disable = ["ax/well-known-agent"]

Disable all Agent Experience rules

[rules]
disable = ["ax/*"]

Enable only this rule

[rules]
enable = ["ax/well-known-agent"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• ax/api-discovery: OpenAPI and OAuth documents, the other half of what an agent needs to call something.
• ax/agents-md: the human-readable instructions for a coding agent.
• ax/llms-txt: the curated content index at the site root.
• ax/markdown-response: serving clean Markdown for the pages themselves.

Agent experience findings ship in every audit next to the SEO, performance and security rules. See llms.txt for how an agent works through a report.

References

• Model Context Protocol
• Agent2Agent protocol specification

Check your site

Run squirrel audit https://example.com and open the Agent Experience section of the report. Each manifest is listed with its path and the JSON keys it declared. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.