Яндекс.Метрика

API and MCP for agents: OpenAPI, MCP Server Card, OAuth discovery

Reading the site is half the job. For an agent to work with the product, it needs a programmatic interface it can find and understand without a human.

Why it matters

  • Public API docs without a login are the first thing an agent looks for when asked to integrate. If they are rendered only by JavaScript, an agent without a browser sees an empty page.
  • OpenAPI at a public URL turns docs into tools: the agent builds the calls itself.
  • An MCP server gives assistants like Claude and ChatGPT ready-made tools. A card at /.well-known/mcp/server-card.json lets them find it without reading the docs.
  • A site without an API does not lose points for missing MCP and OAuth — those checks do not apply to it.

What to do

  1. 1

    Publish the spec

    Serve OpenAPI at a stable URL and point to it from the docs and with a Link header on the homepage.

    Link: <https://example.com/openapi.yaml>; rel="service-desc"; type="application/yaml"
  2. 2

    An MCP server card

    If you have an MCP server, describe it in /.well-known/mcp/server-card.json: name, description, URL, transport, auth.

    curl -s https://example.com/.well-known/mcp/server-card.json
  3. 3

    OAuth discovery

    Authorization server metadata (/.well-known/oauth-authorization-server, RFC 8414) and protected resource metadata (/.well-known/oauth-protected-resource, RFC 9728) let an agent get access without manual setup.

  4. 4

    JSON errors

    A request without a token should get a 401 with a JSON body, not an HTML login page.

What the scanner checks

  • Open API docs or an MCP server exist

    To work with the product and not just read the site, an agent needs a programmatic interface documented without a login.

  • An API description (OpenAPI) is published

    A file listing every API method in a machine format. An agent builds requests from it.

  • An MCP server exists

    MCP is a way to plug a product into Claude, ChatGPT and other assistants as a set of ready-made tools.

  • An agent can find how to sign in

    A service file with OAuth endpoints. Without it an agent needs a person to explain where to get a token.

  • The API reports errors in a machine format

    A request without a token should return a JSON refusal, not an HTML page. Then the agent knows what went wrong.

  • An API catalog exists

    One file at a standard URL linking to all of the company’s APIs and their descriptions.

  • Agent skills are published

    Ready-made instructions for how an agent does common tasks in the product.

  • The API says which server grants access

    A service file: which authorization server issues tokens for this API.

  • The MCP server answers a connection

    We connect to the server the way an assistant does. An address in the docs is useless if the server does not answer.

  • MCP tools have descriptions

    An assistant picks a tool by its description. Without one it cannot tell what the tool does and will not call it.

  • An access refusal says where to sign in

    When an agent is told “authorization required”, the response should point to where to get it. Otherwise it is a dead end.

  • An agent-to-agent card exists

    A file in the A2A standard: who you are, what you can do and how another agent reaches you.

  • There is a guide for how an agent gets access

    An auth.md file walks an agent through getting a key or token without a person’s help.

  • A catalog of AI interfaces exists

    One file at a standard URL listing the company’s MCP servers and other interfaces for agents.

Check your own site

Paste the address and get the same breakdown in half a minute.

Check a site →

Sources

Other guides