Start here
Before You Fix It: What This Check Means
Agent Protocol Discovery Documents Missing or Broken shows whether this part of your site is behaving the way users and search systems expect. In plain terms, this tells you whether AI crawlers and answer systems can understand and reuse your content correctly. Scavo probes common public discovery documents for MCP Server Cards, Agent Skills, A2A Agent Cards, and API Catalogs. It also uses advertised `Link` headers when present, then validates whether the discovered document returns usable JSON.
Why this matters in practice: unclear machine-facing signals can reduce retrieval quality and citation consistency.
How to use this result: treat this as directional evidence, not final truth. Answer-engine retrieval behavior can shift over time even when your technical setup is stable. First, confirm the issue in live output: verify bot-facing output and policy files on the final URL Then ship one controlled change: If you publish an API catalog, use the standard well-known path `/.well-known/api-catalog` and return a valid machine-readable document. Finally, re-scan the same URL to confirm the result improves.
TL;DR: Only publish discovery documents for the protocols you actually support. If you publish them, keep them public, valid, and easy to find.
If "Agent Protocol Discovery Documents Missing or Broken" is red right now in your Scavo scan result, treat it as a focused operations task, not a rewrite. The payoff is more reliable AI crawl and citation signals over time. Assign a single owner, fix the root cause, and re-scan.
This check is deliberately broad because the agent tooling ecosystem is still early. Different protocols use different documents, but the underlying idea is the same: a client should be able to discover what your service offers before trying to connect or call anything.
Scavo treats missing protocol discovery as info because most sites do not need public MCP, A2A, skills, or API catalog endpoints. The action here is for products that really do expose machine-usable capabilities and want them to be discoverable.
What Scavo checks (plain English)
Scavo probes common public discovery documents for MCP Server Cards, Agent Skills, A2A Agent Cards, and API Catalogs. It also uses advertised Link headers when present, then validates whether the discovered document returns usable JSON.
A pass means at least one protocol document was found and looked valid. A warning means a document was advertised or returned 200, but was broken or incomplete. An info result means no discovery documents were detected.
- Scan key:
ai_protocol_discovery - Category:
AI_VISIBILITY
How Scavo scores this check
- Warning: at least one published or advertised discovery document was invalid, incomplete, or not reachable.
- Pass: Scavo found at least one usable discovery document for MCP, agent skills, A2A, or an API catalog.
- Info: no public discovery documents were detected.
Why fixing this matters
Discovery documents are the difference between “here is a public capability” and “you need a manual setup guide and tribal knowledge to find it.” They matter most when you want third-party tools, agents, or partner teams to integrate without hand-holding.
Because these standards are still evolving, broken discovery is a strong negative signal. It tells callers that something exists, then forces them into debugging mismatched paths, stale JSON, or obsolete schema shapes.
Common reasons this check flags
- A well-known document path changed during development, but the old public URL stayed linked or documented.
- The endpoint returns HTML, a SPA shell, or a login wall instead of the expected JSON.
- A Link header points to a stale document location that no longer exists.
- The team published multiple overlapping experiments and never cleaned them up into one supported public surface.
If you are not technical
- Start by deciding whether your product genuinely offers public machine-usable capabilities. If not, an info result is the right outcome.
- If yes, ask engineering to list the supported protocol surface in plain English: API catalog, MCP server, agent card, or skills index.
- Do not ask the team to publish every emerging standard. Publish the one or two discovery surfaces that match the product you actually operate.
Technical handoff message
Copy and share this with your developer.
Scavo flagged Agent Protocol Discovery (ai_protocol_discovery). Please review the live public discovery surface for MCP, Agent Skills, A2A, and API Catalog endpoints, remove stale or broken documents, and keep only the protocol documents we actively support on production.If you are technical
- If you publish an API catalog, use the standard well-known path
/.well-known/api-catalogand return a valid machine-readable document. - If you expose an MCP server, publish a server card only when you can keep its endpoint, auth expectations, and tool list current.
- If you expose an A2A agent, publish the agent card at the well-known path used by the protocol version you support and keep the card in sync with the real endpoint.
- Advertise discovery URLs with
Linkheaders only when the target is stable and public. - Choose one canonical discovery document per capability and redirect or retire old experiments so callers do not see multiple competing entry points.
How to verify
- Fetch every public discovery document directly and confirm it returns stable JSON in production.
- If you advertise discovery through
Linkheaders, check the final headers on the canonical URL. - For each published protocol, run one real client-side discovery flow instead of only validating the document by eye.
- Re-run Scavo and confirm the result matches the capabilities you intentionally expose.
What this scan cannot confirm
- Scavo does not fully validate each protocol schema or execute every protocol method. It checks for public discovery presence and basic machine-readable validity.
- The agent ecosystem is moving quickly. Some discovery conventions are still emerging, so “info” is often the correct state for sites that are not building agent-facing products.
Owner checklist
- [ ] Name one owner for this check and note where it is controlled (app, CDN, server, or CMS).
- [ ] Add a release gate for this signal so regressions are caught before production.
- [ ] After deploys that touch this area, run a follow-up scan and confirm the result is still healthy.
- [ ] Re-check AI crawler and citation signals after robots, schema, or author metadata changes.
FAQ
What does Scavo actually validate for Agent Protocol Discovery Documents Missing or Broken?
Scavo checks live production responses using the same logic shown in your dashboard and weekly report.
Will AI visibility changes show immediately after we ship fixes?
Usually not instantly. Crawlers and answer engines refresh on different schedules, so confirm technical signals first, then monitor citations and mentions over time.
What is the fastest way to confirm the fix worked?
Run one on-demand scan after deployment, open this check in the report, and confirm it moved to pass or expected info. Then verify at source (headers, HTML, or network traces) so the fix is reproducible.
How do we keep this from regressing?
Keep one owner, keep config in version control, and watch at least one weekly report cycle. If this regresses, compare the release diff and edge configuration first.
Sources
- Cloudflare Blog: Agent Readiness
- RFC 9727: api-catalog
- MCP Server Card Working Group Charter
- MCP Apps: Agent Skills
- A2A Protocol Roadmap
Need stack-specific help? Send support your stack + check key and we will map the fix.
