MCP Discoverability — How AI Agents Find Your API

The Model Context Protocol (MCP) is an open standard (created by Anthropic, now widely adopted) that defines how AI agents connect to external tools and data sources. Instead of building custom integrations for each AI platform, you build one MCP server and every compatible agent can use it.

MCP defines three primitives: Tools (functions the agent can call), Resources (data the agent can read), and Prompts (templates the agent can use). An MCP server exposes these via a standardized JSON-RPC transport — either over stdio (for local tools) or HTTP with Server-Sent Events (for remote APIs).

As of MCP v2.1, the protocol includes a server card specification for discovery. This is the piece most teams overlook — they build a working MCP server but never publish the metadata that lets agents find it.

Building an MCP server solves the "how do agents interact with my API" problem. But it does not solve the "how do agents findmy API" problem. Without discovery, your MCP server only works when someone manually configures it in their IDE or agent platform.

Discovery is the difference between an API that requires a developer to read docs and manually set up, versus one that an agent can find, evaluate, and connect to autonomously. In the agentic web, discovery is distribution.

There are three layers of MCP discovery, each targeting a different audience:

The MCP server card is a JSON file that describes your server before an agent connects to it. It tells agents what tools are available, how to authenticate, and what transport to use.

{
  "name": "your-company-mcp",
  "version": "1.0.0",
  "description": "MCP server for Your Company API",
  "transport": {
    "type": "sse",
    "url": "https://api.example.com/mcp/sse"
  },
  "authentication": {
    "type": "bearer",
    "token_url": "https://example.com/oauth/token"
  },
  "tools": [
    {
      "name": "search_products",
      "description": "Search product catalog by query",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "limit": { "type": "integer", "default": 10 }
        },
        "required": ["query"]
      }
    }
  ],
  "resources": [
    {
      "uri": "products://catalog",
      "name": "Product Catalog",
      "description": "Full product listing with prices"
    }
  ]
}

Critical fields: The transport object tells agents how to connect (stdio, SSE, or streamable HTTP). The tools array lets agents evaluate whether your server is useful before establishing a connection — saving time and tokens.

The authentication field is optional but important. If your MCP server requires auth, declaring it in the server card lets agents handle credentials proactively rather than failing on the first request.

When an agent needs a capability (e.g., "search for flights" or "create a Jira ticket"), it follows a discovery chain. First, it checks its pre-configured MCP servers. If none match, it searches registries. If the agent is browsing a specific website, it checks /.well-known/mcp.json to see if the site has tools available.

IDE-based agents (like Claude Code or Cursor) typically discover MCP servers through project configuration files (.mcp.json in the repo root). Autonomous web agents discover them through the well-known endpoint or llms.txt references. Platform agents discover them through registry search.

The pattern mirrors DNS: there is no single discovery mechanism, but a hierarchy of lookups that agents traverse until they find what they need. Publishing your server card at all three layers maximizes your reach.

MCP Discovery is its own named check in the AX Audit, worth up to 10 of the 100 points. Having a valid .well-known/mcp.jsonserver card, or MCP discovery meta tags, earns credit here directly — independent of whatever else your site publishes.

AX Audit practices what this guide teaches: it publishes its own server card at /.well-known/mcp.json and runs a real, remote MCP server at https://ainative.ax/mcp over Streamable HTTP. There is nothing to npxinstall — it’s a hosted server your MCP client connects to directly, the same way it would any other remote MCP server.

Add it in Claude Code with the CLI:

claude mcp add --transport http ax-audit https://ainative.ax/mcp

Or add it directly to a client config (Claude Desktop and others that read an mcpServers block):

{
  "mcpServers": {
    "ax-audit": {
      "url": "https://ainative.ax/mcp"
    }
  }
}

Once connected, two tools are available: scan_site (a quick 0–100 score with per-check breakdown) and run_full_audit (adds an agent-simulation task and an industry benchmark, with the result persisted as a retrievable report). Neither requires authentication.