agentsready
API / Auth / MCP Сложно

MCP Server Card: как агенты находят ваш MCP-сервер

Что такое MCP Server Card, зачем агентам авто-обнаружение MCP-сервера, минимальный пример, правильно vs неправильно, ошибки и как проверить.

Обновлено:

Что это

MCP Server Card — JSON-манифест по адресу /.well-known/mcp/server-card.json, описывающий ваш MCP-сервер: имя, версию, транспорт, capabilities. MCP (Model Context Protocol) — открытый протокол для подключения AI-агентов к инструментам и данным. Карточка — это «вывеска» сервера, по которой агент находит его автоматически.

Зачем это AI-агентам

Без discovery каждая интеграция MCP — ручная: разработчик прописывает URL и инструменты. Это не масштабируется. Server Card даёт federated tool discovery: агент читает карточку по домену и сразу видит доступные tools/resources/prompts, версию протокола и требования авторизации. Особенно нужно SaaS, DevTools и корпоративным базам знаний, рассчитанным на агентов.

Минимальный рабочий пример

{
  "serverInfo": { "name": "My Service MCP", "version": "1.0.0" },
  "transport": { "type": "http", "endpoint": "https://api.example.com/mcp" },
  "capabilities": { "tools": true, "resources": false, "prompts": false }
}

С авторизацией добавьте блок authentication (oauth2/api-key) — см. гайд по OAuth Protected Resource.

Правильно vs неправильно

ПравильноНеправильно
Лежит по /.well-known/mcp/server-card.json, application/jsonПроизвольный путь
Есть serverInfo.name + serverInfo.versionПропущены обязательные поля
Есть transport.type + transport.endpointНет транспорта — агент не знает, куда подключаться
Есть объект capabilitiesНет capabilities — непонятно, что умеет сервер

Типичные ошибки

  • Невалидный JSON — карточка отбрасывается.
  • Нет transport.endpoint — discovery бесполезен.
  • Endpoint указывает не на работающий MCP — агент подключится и упадёт.
  • Карточка без CORS (Access-Control-Allow-Origin) — браузерные клиенты не прочтут.

Как проверить

Сканер по очереди пробует три пути: /.well-known/mcp/server-card.json, /.well-known/mcp/server-cards.json, /.well-known/mcp.json — и проверяет JSON + обязательные поля (serverInfo.name/version, transport, capabilities). Вручную:

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

Источники