claritos
deenru

MCP (Model Context Protocol)

Весь API как набор инструментов для ИИ-агентов — один инструмент на конечную точку, те же права, что и у доступа, с которым входит агент.

Что это за сервер

POST /api/mcp/v1 говорит на MCP поверх Streamable HTTP (без состояния). Каждая конечная точка API — инструмент с именем <domain>_<action> (например contacts_list, invoices_issue); описание и схема ввода берутся из того же источника, что и этот справочник. Чего доступу нельзя (scopes, включение клиентских данных), в списке инструментов вообще не появляется.

Подключение

Инструменты разработчика (Claude Code, Cursor, VS Code, n8n): URL сервера плюс заголовок Authorization с API-ключом. Чат-коннекторы (claude.ai, ChatGPT), не умеющие ставить заголовки: укажите только URL — без токена сервер отвечает 401 и через WWW-Authenticate указывает на OAuth-discovery; клиент регистрируется сам и получает доступ через согласие.

json
{
  "mcpServers": {
    "claritos": {
      "url": "https://www.claritos.io/api/mcp/v1",
      "headers": { "Authorization": "Bearer capi_…" }
    }
  }
}
curl
curl -X POST https://www.claritos.io/api/mcp/v1 \
  -H "Authorization: Bearer capi_…" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Несколько организаций в одном инструменте

Чат-коннектор различает подключения по адресу, поэтому по короткому адресу одновременно подключена только ОДНА организация. У каждой следующей есть свой адрес с идентификатором организации; готовый к копированию, он находится в настройках организации в разделе «Токены доступа». Организация становится частью адреса: экран согласия подставляет её заранее, а доступ, принадлежащий другой организации, по этому адресу отклоняется. Короткие адреса продолжают работать.

http
POST https://www.claritos.io/api/mcp/v1/o/<orgId>
POST https://www.claritos.io/api/mcp/o/<orgId>

Вызов инструментов

Аргументы структурированы как HTTP-вызовы: params (ID пути), query (фильтры/курсор), body (полезная нагрузка). Пишущие инструменты дополнительно принимают idempotencyKey. Ответы — JSON конечной точки; ошибки приходят как Problem Details (RFC 9457) с isError.

json
{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "contacts_create",
    "arguments": {
      "body": { "type": "PERSON", "firstName": "Anna", "lastName": "Muster", "email": "anna@example.com" },
      "idempotencyKey": "2f1c…"
    }
  }
}

Компактно: четыре инструмента для всего

По адресу /api/mcp/v1/compact (и для каждой организации /api/mcp/v1/compact/o/<orgId>) находится тот же MCP с четырьмя инструментами вместо одного на адрес: guide (обзор, область или руководство), search_endpoints (поиск по словам на всех языках), describe_endpoint (входные данные в виде JSON Schema, права, пример) и call_endpoint (вызов с теми же правами, лимитами и журналом). Со всеми правами список инструментов полного адреса занимает около 130 000 токенов; компактный остаётся в пределах нескольких тысяч, и ассистент всё равно видит весь объём. Оба адреса при подключении передают обзор claritos (области, правила, процессы). Вход и права, как выше.

http
POST https://www.claritos.io/api/mcp/v1/compact
POST https://www.claritos.io/api/mcp/v1/compact/o/<orgId>
json
{ "name": "search_endpoints", "arguments": { "query": "finalize invoice" } }
{ "name": "describe_endpoint", "arguments": { "id": "invoices.issue" } }
{ "name": "call_endpoint", "arguments": { "id": "invoices.issue", "params": { "id": "inv_…" }, "idempotencyKey": "7a3e…" } }

OAuth для чат-клиентов

Оба MCP-сервера — защищённые ресурсы по RFC 9728: MCP API (/api/mcp/v1, метаданные в /.well-known/oauth-protected-resource/api/mcp/v1, все scopes API) и MCP конструктора сайтов (/api/mcp, метаданные в …/api/mcp, scopes sites:read и sites:write). Сервер авторизации — сам claritos (руководство «OAuth 2.1»). После согласия доступ действует для выбранной организации. В MCP конструктора сайтов scopes проверяются для каждого инструмента: get_/list_/verify_/suggest_ читают, остальные пишут; при отсутствии scope сервер отвечает 403 insufficient_scope. Статические cmcp_-токены остаются действительными; API-ключи (capi_) там намеренно не работают. Список инструментов там также показывает только разрешённое — доступ с sites:read вообще не видит инструменты записи.

Лимиты и протокол

Каждый вызов инструмента — вызов API: лимиты (чтение/запись), идемпотентность, протокол вызовов и оповещения действуют без изменений. Большие списки постраничны (передавайте курсор из ответа).