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

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

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

Зачем

  • Документация 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-серверов и других интерфейсов компании для агентов.

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

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

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

Источники

Другие гайды