MCP discovery: how an assistant finds out you have tools

Tools nobody can find are scraping with extra steps

The Model Context Protocol gives an assistant a typed way to call your functions: look up a price, check stock, score a domain. Claude Desktop, Cursor, Claude Code and a growing list of hosts speak it. But every one of them needs to be told where your server is, and today that mostly happens by a person copying a URL into a config file.

Discovery closes that gap. If your domain publishes a document at a predictable path that says 'here is my MCP endpoint, here are its tools, here is how to authenticate', a host or an agent can connect from the domain name alone. Cloudflare's readiness scanner probes for an MCP Server Card under Protocol Discovery; Qomvia's MCP or A2A discovery document check does the same.

What the document contains

There is no single ratified format yet. The MCP specification defines the wire protocol and, for authorization, points at RFC 9728 protected-resource metadata; the server-card and .well-known/mcp.json conventions grew up around it and scanners accept several shapes. The safe approach is a document that any reader can use: server name and version, the endpoint URL, the transport, the authentication model, and a list of tools with one-line descriptions.

{
  "name": "Qomvia AI readiness",
  "version": "1.0.0",
  "protocolVersion": "2024-11-05",
  "description": "Score any website for AI-agent readiness, read the rubric and re-measure a domain.",
  "transport": "streamable-http",
  "endpoint": "https://qomvia.com/api/mcp",
  "authentication": "none",
  "tools": [
    { "name": "get_ai_readiness_score", "description": "Cached score, grade, rank and failing checks for a domain." },
    { "name": "scan_website", "description": "Run a fresh crawl and score (one per domain per hour)." },
    { "name": "list_readiness_checks", "description": "The rubric: every check, weight and fix." }
  ],
  "documentation": "https://qomvia.com/mcp",
  "openapi": "https://qomvia.com/openapi.json"
}

• Endpoint and transport. Streamable HTTP is the current remote transport in the MCP spec; name it so a host does not have to probe.
• Authentication. none for public read-only tools. For anything else, point at OAuth metadata as the OAuth discovery article describes.
• Tools with descriptions. A host can show these to the user before connecting, and a model can decide whether the server is relevant without a handshake.
• Links to human docs and OpenAPI. The same functions are often available as a REST API; say so.

Serve it as application/json, cache it, and keep it in sync with the server's real tool list. Generate it from the same source as the server so it cannot drift.

Advertise it in more than one place

• A Link: </.well-known/mcp.json>; rel="mcp" header on HTML responses, as in the Link header article.
• An entry in llms.txt under a 'Machine access' section.
• A human page (/mcp) with the config snippet a person can paste into Claude Desktop or Cursor, because most connections still start that way.
• An _index._agents DNS record or an ARD document if you also want DNS-level discovery; the DNS-AID article covers that layer.

{
  "mcpServers": {
    "qomvia": { "type": "http", "url": "https://qomvia.com/api/mcp" }
  }
}

What Qomvia checks and what it means for your class of agent

The MCP or A2A discovery document check under Discovery is worth 5 points and passes when /.well-known/mcp.json, /.well-known/agent.json or /.well-known/agent-card.json returns 200. It is also a required check for the 'MCP tool-callers' agent class on your site page, so a missing document turns that class red regardless of how good the server behind it is. qomvia.com itself failed this class until the document was published, although the server at /api/mcp already worked.

Questions

We do not have an MCP server. Is publishing the document pointless?

Yes; it must describe a real endpoint. If you have an OpenAPI description, publish that and an API catalog first. An MCP server wrapping a few read-only endpoints is usually a day of work.

What is the A2A agent card?

Google's Agent2Agent protocol publishes an agent card at /.well-known/agent.json (or agent-card.json) describing an agent's skills and endpoint. Qomvia accepts it as an alternative discovery document.

Does the discovery document need authentication details?

State the model at minimum: none, API key, or OAuth. For OAuth, publish the RFC 9728 protected-resource metadata the MCP spec references and link it.