MCP Integration¶

Статус. V6.1+, optional. Только после явного G0 trigger (см. PLAN-MCP-INBOUND.md §9). Auth mode — pre-issued bearer token, НЕ full OAuth 2.1 / MCP Authorization spec compliance (AD-24). Public third-party GA требует отдельного B7 mini-plan.

Что это и зачем¶

Inbound MCP — это второй протокол управления Axon (помимо REST). Он позволяет внешним MCP-aware агентам (Claude Desktop, IDE-агенты, кастомные клиенты на Pydantic AI / OpenAI Responses API tool use) управлять процессами Axon одной строкой конфигурации — без кастомного HTTP-bridge.

Эндпоинт:

POST/GET /api/v1/mcp

Mount embedded в app-api, не отдельный сервис. Каждый MCP tool — тонкий адаптер, делегирующий в существующий CommandProcessor (мутации) или query handler (чтения). RBAC, idempotency, policy gate и audit — те же, что у REST.

Подключение клиента¶

Поддерживаются два пути; рекомендован Claude Code (native HTTP).

Вариант A — Claude Code (native HTTP MCP)¶

claude.json или project/user .mcp.json:

{
  "mcpServers": {
    "axon": {
      "type": "http",
      "url": "https://axon.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer axon_mcp_<key_id>.<secret>"
      }
    }
  }
}

Вариант B — Claude Desktop через `mcp-remote` bridge¶

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

{
  "mcpServers": {
    "axon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://axon.example.com/api/v1/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "axon_mcp_<key_id>.<secret>"
      }
    }
  }
}

Pre-requisite: node ≥ 18 + npx. При self-signed cert на dev01 — добавьте "NODE_TLS_REJECT_UNAUTHORIZED": "0" в env (только для dev окружения; в проде обязательно удалить).

Claude Desktop's built-in custom-connector UI оптимизирован под OAuth. Если ваша Desktop-версия не позволяет инжектить статический Authorization: Bearer … header, оставайтесь на mcp-remote bridge.

IDE-агенты / кастомные клиенты на MCP Python SDK¶

Любой клиент, поддерживающий mcp.client.streamable_http.streamablehttp_client(...) с headers={"Authorization": "Bearer ..."}, подключается без доработок.

Pydantic AI / OpenAI Responses API через MCP-tool¶

Поднимите MCP клиент в вашем агенте и зарегистрируйте его tools в runtime tool registry. Tool names в namespace axon.*.

Выпуск ключа¶

См. deploy/runbooks/mcp-api-key-lifecycle.md. Короткий путь: Console → Settings → MCP API Keys → New key.

Plaintext-токен показывается один раз на экране создания — сохраните его сразу. Ротация: revoke + create new (in-place rotation не поддерживается, инвариант I-MCP-5).

Канонический набор tools (MVP)¶

Чтения¶

Tool	Что	Permission
`axon.workflow.list`	Список workflows проекта	READ
`axon.workflow.get`	Один workflow по id	READ
`axon.run.get`	Run snapshot + step timeline	READ
`axon.run.history`	Recent runs проекта	READ
`axon.run.steps`	Step timeline run-a	READ
`axon.approval.list`	Список approvals	READ
`axon.approval.get`	Один approval по id	READ
`axon.project.list`	Проекты, доступные ключу	implicit (по scope)
`axon.project.get`	Один проект	READ
`axon.health`	Health probe (без project-scope)	valid key only
`axon.conversation.list`	Список conversations проекта	READ
`axon.conversation.get`	Conversation + recent messages	READ
`axon.case.list`	Список cases проекта (redacted projection)	READ
`axon.case.get`	Один case по id (redacted projection)	READ

Мутации¶

Tool	Permission	Notes
`axon.workflow.create`	CREATE_WORKFLOW (MANAGER+)	Inline definition or definition_id via payload
`axon.workflow.start`	START_WORKFLOW (OPERATOR+)	Downstream effects могут быть external_high
`axon.workflow.pause`	PAUSE_WORKFLOW (MANAGER+)
`axon.workflow.resume`	RESUME_WORKFLOW (MANAGER+)
`axon.workflow.cancel`	CANCEL_WORKFLOW (MANAGER+)	Destructive
`axon.approval.decide`	APPROVE / REJECT_APPROVAL	Verb `approve`/`reject`
`axon.conversation.send_reply`	SEND_MESSAGE (OPERATOR+)	Outbound reply через durable command (`external_low`, policy/approval/outbox/audit). Не alias `send_message` — `send_message` остаётся inbound-append. Phase 4 caveat: финальный provider-call живёт в activity `send_conversation_reply`, которая сейчас stub, разделяемый с Console-driven flow. MCP-envelope, policy gate, audit chain, workflow signal проходят полностью; реальная Telegram-доставка — follow-up worker extension, не MCP-specific.

Excluded из MVP: axon.workflow.retry / .replan / .undo. Их permissions (RETRY_WORKFLOW / REPLAN_WORKFLOW) есть только у OWNER/ADMIN через HUMAN_PERMISSIONS, а OWNER/ADMIN внешнему агенту не выдаются. Pre-requisite — отдельный мини-план (PLAN-MCP-INBOUND §11).

Idempotency¶

Каждая мутирующая команда требует idempotency_key: str (1..256 chars, free-form). Симметрично REST. Рекомендуемые паттерны:

<uuid4> (crypto.randomUUID()).
<tool>:<resource_id>:<utc-iso>.
Клиентский монотонный счётчик внутри одной сессии агента.

Replay (тот же ключ + тот же envelope) возвращает существующий row. Replay c другим envelope → CallToolResult(isError=true, failure_code="idempotency_conflict") (B0.6 fingerprint guard).

Error semantics¶

Pre-dispatch / protocol failures (malformed token, unknown tool, auth, transport-security, rate limit) → HTTP 401/403/421/429 или JSON-RPC error.
Tool execution failures внутри известного tools/call (validation, RBAC, version_conflict, idempotency_conflict, project_suspended, target_not_found, forbidden, handler reject) → CallToolResult(isError=true) со структурой {failure_code, correlation_id, command_id?} (AD-12 / I-MCP-17).

Это позволяет LLM видеть ошибку tool execution и самокорректироваться, вместо того чтобы валиться на уровне JSON-RPC.

Best practices¶

Не комитьте ключ в git. Display-once показ это последний раз, когда вы его увидите.
Минимальная роль. read_only для discovery-агентов, operator для trigger-only flows, manager только когда нужны pause/cancel/approve.
Узкий allowed_tool_names. Для integration partner ограничьте набор tools на уровне ключа: ["axon.workflow.start", "axon.workflow.get"]. Это уже the second RBAC plane сверх роли.
Стабильные idempotency_key. Не используйте message id JSON-RPC envelope — он не stable между retry. Генерируйте UUID4 один раз и переиспользуйте при повторных попытках.
Smart MCP клиенты — читайте _meta.axon. Tool descriptor несёт command_type, side_effect_class, triggers_workflow_side_effects, downstream_side_effect_ceiling. Используйте для budget reasoning и safety prompting.

Что НЕ делает MCP¶

Не управляет credentials (Gmail / OAuth — отдельная Console-only зона).
Не публикует AgentDefinition / Prompt versions.
Не релейит коннекторы Axon наружу — это V7+ (§26.10).
Не имеет stdio transport (Axon — HTTP server).
Не открывает streaming notifications обратно агенту (MVP — polling через axon.run.get).

Troubleshooting¶

Симптом	Действие
HTTP 401 `missing_token`	Header `Authorization: Bearer ...` отсутствует
HTTP 401 `malformed_token`	Формат должен быть `axon_mcp_<key_id>.<secret>` (точка, не подчёркивание)
HTTP 401 `unknown_key` / `revoked` / `expired` / `disabled_owner`	Ключ невалиден — выпустите новый
HTTP 429 / `failure_code=rate_limited`	Превышен per-key лимит (default 60/min) — ждите `retry_after`
HTTP 421 / `transport_security`	`Host` / `Origin` не в allowlist — операторская проблема
`failure_code=forbidden`	Project scope или per-key tool whitelist отказал
`failure_code=target_not_found`	Workflow / approval / run не существует или находится в другом проекте
`failure_code=version_conflict`	`expected_version` устарел — перечитайте через `axon.*.get`

См. также¶

PLAN-MCP-INBOUND.md — полный дизайн-документ.
deploy/runbooks/mcp-api-key-lifecycle.md — операции с ключами.
deploy/runbooks/mcp-key-compromised.md — incident response.
RULES-CODDING-DEVOPS.md §4.2.1 — операторская дисциплина app-api для MCP.