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

> How to let an AI agent work with your product: public API docs, OpenAPI at a public URL, an MCP server and MCP Server Card, OAuth discovery (RFC 8414, RFC 9728), API catalog (RFC 9727).

Источник: https://pachca.com/en/agent-ready/guide/api-mcp

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 →](https://pachca.com/en/agent-ready)

## Sources

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728)
- [RFC 9727: api-catalog](https://www.rfc-editor.org/rfc/rfc9727)

## Other guides

- [An agent can open your site: no CAPTCHA, no JavaScript wall, an honest 404](https://pachca.com/en/agent-ready/guide/site-access)
- [robots.txt for AI: YandexAdditional, GPTBot, ClaudeBot and Content-Signal](https://pachca.com/en/agent-ready/guide/robots-txt)
- [llms.txt and llms-full.txt: what they are and whether you need them](https://pachca.com/en/agent-ready/guide/llms-txt)
- [Markdown for AI agents: .md page versions and Accept: text/markdown](https://pachca.com/en/agent-ready/guide/markdown)
- [sitemap, metadata and JSON-LD: how an agent learns who you are](https://pachca.com/en/agent-ready/guide/structured-data)