# API и MCP для агентов: OpenAPI, MCP Server Card, OAuth discovery

> Как дать ИИ-агенту работать с продуктом: открытая документация API, OpenAPI по публичному адресу, MCP-сервер и MCP Server Card, OAuth discovery (RFC 8414, RFC 9728), API catalog (RFC 9727).

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

Прочитать сайт — полдела. Чтобы агент мог работать с продуктом, ему нужен программный интерфейс, который он найдёт и поймёт без человека.

## Зачем

- Документация API без логина — первое, что ищет агент, которого попросили интегрироваться. Если она рисуется только JavaScript, агент без браузера увидит пустую страницу.
- OpenAPI по публичному адресу превращает документацию в инструменты: агент сам строит вызовы.
- MCP-сервер — готовые инструменты для ассистентов вроде Claude и ChatGPT. Карточка /.well-known/mcp/server-card.json позволяет найти его без чтения документации.
- Сайт без API не теряет баллы за отсутствие MCP и OAuth — эти проверки к нему не применяются.

## Что сделать

1.  1

    ### Опубликуйте спецификацию

    Отдавайте OpenAPI по постоянному адресу и сошлитесь на него из документации и заголовком Link с главной.

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

2.  2

    ### Карточка MCP-сервера

    Если MCP-сервер есть, опишите его в /.well-known/mcp/server-card.json: имя, описание, адрес, транспорт, авторизация.

    ```
    curl -s https://example.ru/.well-known/mcp/server-card.json
    ```

3.  3

    ### OAuth discovery

    Метаданные сервера авторизации (/.well-known/oauth-authorization-server, RFC 8414) и защищённого ресурса (/.well-known/oauth-protected-resource, RFC 9728) позволяют агенту получить доступ без ручной настройки.

4.  4

    ### Ошибки в JSON

    Запрос без токена должен получать 401 с JSON-телом, а не HTML-страницу входа.

## Что проверяет сканер

- Есть открытая документация API или MCP-сервер

    Чтобы агент работал с продуктом, а не только читал сайт, ему нужен программный интерфейс с описанием без логина.

- Опубликовано описание API (OpenAPI)

    Файл со всеми методами API в формате для программ. По нему агент сам собирает запросы.

- Есть MCP-сервер

    MCP — способ подключить продукт к Claude, ChatGPT и другим ассистентам как набор готовых инструментов.

- Агент может сам найти, как авторизоваться

    Служебный файл с адресами входа по OAuth. Без него агенту нужен человек, который объяснит, где брать токен.

- API отвечает на ошибку понятно для программы

    Запрос без токена должен вернуть отказ в формате JSON, а не HTML-страницу. Тогда агент понимает, что пошло не так.

- Есть каталог API

    Один файл по стандартному адресу со ссылками на все API компании и их описания.

- Опубликованы навыки для агентов

    Готовые инструкции, как агенту выполнять типовые задачи в продукте.

- API сообщает, какой сервер выдаёт доступ

    Служебный файл: к какому серверу авторизации идти за токеном для этого API.

- MCP-сервер отвечает на подключение

    Мы подключаемся к серверу так, как это делает ассистент. Адрес в документации бесполезен, если сервер по нему не отвечает.

- У инструментов MCP есть описания

    Ассистент выбирает инструмент по описанию. Без него он не поймёт, что инструмент делает, и не вызовет его.

- Отказ в доступе подсказывает, где авторизоваться

    Когда агенту отвечают «нужна авторизация», в ответе должна быть ссылка, где её пройти. Иначе это тупик.

- Есть карточка для связи между агентами

    Файл по стандарту A2A: кто вы, что умеете и как к вам обратиться другому агенту.

- Есть инструкция, как агенту получить доступ

    Файл auth.md по шагам объясняет агенту, как получить ключ или токен без помощи человека.

- Есть общий каталог интерфейсов для ИИ

    Один файл по стандартному адресу со списком MCP-серверов и других интерфейсов компании для агентов.

Проверьте свой сайт

Вставьте адрес и получите такой же разбор за полминуты.

[Проверить сайт →](https://pachca.com/agent-ready)

## Источники

- [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)

## Другие гайды

- [Сайт открывается агенту: без капчи, без JavaScript, с честным 404](https://pachca.com/agent-ready/guide/site-access)
- [robots.txt для нейросетей: YandexAdditional, GPTBot, ClaudeBot и Content-Signal](https://pachca.com/agent-ready/guide/robots-txt)
- [llms.txt и llms-full.txt: что это и нужно ли вашему сайту](https://pachca.com/agent-ready/guide/llms-txt)
- [Markdown для ИИ-агентов: .md-версии страниц и Accept: text/markdown](https://pachca.com/agent-ready/guide/markdown)
- [sitemap, метаданные и JSON-LD: как агент понимает, кто вы](https://pachca.com/agent-ready/guide/structured-data)