MCP — для ИИ-агентов

Read-only доступ для LLM-агентов (Claude Code, Claude Desktop, Cursor). Два transport'а: Streamable HTTP (рекомендуется) и stdio через бинарник bcs-mcp.

:::info Что даёт MCP Шесть read-only tools: list_companies, list_bank_accounts, get_balance, list_statements, get_statement, search_operations. Никаких write-операций (платежи / заказ выписок / refresh balance) — read-only по дизайну, на 4+ уровнях защиты (admin UI / admin API / backend middleware / tool registry). :::

Два transport'а

Оба пути дают одни и те же шесть tools, одну и ту же ACL и один и тот же audit. Выбор — про ergonomics клиента, не про функциональность.

• Streamable HTTP (рекомендуется, без бинарника): Claude Code CLI ≥ 1.0, Cursor ≥ 0.43, любой HTTP-MCP-клиент. Backend сам отвечает по MCP JSON-RPC 2.0 на POST /api/v1/mcp.
• stdio через bcs-mcp (fallback): Claude Desktop, embedded LLM-tools без HTTP-transport. Локальный бинарник на машине оператора.

Вариант A — Streamable HTTP (рекомендуется)

Claude Code CLI

# Добавить MCP-сервер в Claude Code:
claude mcp add bsc --transport http https://bsc.example.com/api/v1/mcp \
  --header "Authorization: Bearer bcs_live_<TOKEN>"
 
# Проверить, что добавился:
claude mcp list

Файл, в который Claude Code пишет конфиг MCP-серверов: ~/.claude.json (user-scope) или .mcp.json в корне проекта (project-scope). Можно править его руками вместо claude mcp add.

Cursor

~/.cursor/mcp.json (user) или .cursor/mcp.json (project):

{
  "mcpServers": {
    "bsc": {
      "transport": "http",
      "url": "https://bsc.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer bcs_live_<TOKEN>"
      }
    }
  }
}

Wire-контракт

POST /api/v1/mcp — JSON-RPC 2.0. Методы: initialize, initialized (notification), ping, tools/list, tools/call. Body ≤ 16 KB.

GET /api/v1/mcp — 405 Method Not Allowed + Allow: POST, DELETE. SSE upgrade не реализован.

DELETE /api/v1/mcp — Терминирование сессии. Требует Mcp-Session-Id. 204 No Content на успех.

Заголовки

Session lifecycle

1. Клиент шлёт POST /api/v1/mcp с method=initialize. Backend генерит UUIDv4, сохраняет сессию в Redis (mcp:sessions:<uuid>, TTL 8 часов), возвращает header Mcp-Session-Id + результат initialize.
2. Клиент шлёт tools/list / tools/call / ping с тем же Mcp-Session-Id. Backend валидирует сессию + token-binding + продлевает TTL.
3. Сессия истекла → JSON-RPC error «Сессия истекла…», клиент сам должен вызвать initialize заново.
4. Redis недоступен → 503 service_unavailable (fail-closed — без session store нельзя держать lifecycle / audit гарантии).

Manual smoke (curl)

curl --silent --show-error -i -X POST \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
          "params":{"protocolVersion":"2025-03-26"}}' \
     "https://bsc.example.com/api/v1/mcp"

Возьмите Mcp-Session-Id из response header и продолжайте:

curl --silent --show-error -X POST \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     -H "Mcp-Session-Id: <uuid-from-initialize>" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
     "https://bsc.example.com/api/v1/mcp"

curl --silent --show-error -X POST \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     -H "Mcp-Session-Id: <uuid>" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
          "params":{"name":"list_companies","arguments":{}}}' \
     "https://bsc.example.com/api/v1/mcp"

Вариант B — stdio через bcs-mcp (fallback)

Используйте, если ваш AI-хост не поддерживает HTTP-transport (например, старый Claude Desktop, embedded LLM-tools), либо если нужен offline-deploy без сетевого доступа к backend в момент запуска.

Сборка бинарника

cd backend
go build -o ./bcs-mcp ./cmd/bcs-mcp
install -m 0755 ./bcs-mcp ~/.local/bin/bcs-mcp

Бинарник статический (Go), ~9 MB. Если Go на машине агента не установлен — попросите администратора BCS прислать готовый под вашу ОС.

Claude Code CLI через stdio

claude mcp add bsc \
  --env BCS_API_URL=https://bsc.example.com/api/v1 \
  --env BCS_API_TOKEN=bcs_live_<TOKEN> \
  -- ~/.local/bin/bcs-mcp

Claude Desktop / Cursor через stdio

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "bsc": {
      "command": "/Users/<you>/.local/bin/bcs-mcp",
      "env": {
        "BCS_API_URL": "https://bsc.example.com/api/v1",
        "BCS_API_TOKEN": "bcs_live_<TOKEN>",
        "BCS_MCP_LOG_DIR": "~/Library/Logs/bcs-mcp"
      }
    }
  }
}

ВАЖНО: два разных адреса

Шесть tools

У каждого tool — annotation readOnlyHint=true. Каждый успешный response содержит _meta.notice — guardrail против prompt-injection из ответов банка.

Audit и observability

Каждый вызов любого tool пишется в /admin/audit-log с action mcp.<tool_name>, привязкой к api_token_id и mcp_session_id. Каждое action: mcp.initialize, mcp.tools_list, mcp.tools_call, mcp.<tool_name>, mcp.ping, mcp.session.terminate, mcp.notification.<method>.

Ошибки HTTP-transport'а

JSON-RPC-уровень (HTTP 200, ошибка внутри body)

Troubleshooting

MCP НЕ может (по дизайну)

• Отправить платёж (send_payment) — никаких write tools в registry.
• Заказать новую выписку (create_statement) — используйте REST integration-токен.
• Обновить баланс из банка (refresh_balance) — get_balance возвращает только cached значение.
• Изменить любой другой data — read-only по архитектуре.

Если вам нужна write-операция в MCP-агенте — выпустите отдельный integration-токен и попросите агента ходить в REST endpoint'ы (POST /integration/…) не через MCP, а через обычный HTTP-tool.