ADR 0165: Стратификация транспорта MCP — stdio, HTTP-first, матрица хостов

Статус: Proposed
Дата: 2026-06-25

Резюме

Стек MCP в экосистеме IOP/CIDE сегодня в основном stdio (хост порождает subprocess). Это корректно для локальных IDE-хостов (Cursor, Claude Desktop), но не покрывает веб-агентов (ChatGPT, Claude в браузере), shared remote MCP и multi-client без fork процесса.

Принято направление: не переписывать тулы; разделить handler (SSOT) и транспорт-адаптер. Сервисы с общим состоянием и удалённым доступом — HTTP-first (Streamable HTTP MCP на loopback или forge API); локальные language/debug драйверы — stdio навсегда; Cascade IDE — stdio для внешнего хоста + loopback HTTP в GUI-процессе (0082).

Связанные ADR

Вне репо (смежные решения)

1. Контекст

1.1 Два класса MCP-хостов

MCP-спека допускает оба; stdio не «устарел» — он правильный там, где хост владеет жизненным циклом subprocess.

1.2 Текущий стек (2026-06)

Проблема не в «всё stdio плохо», а в том, что весь стек только stdio закрывает контур Cursor/IDE, но не ChatGPT, не shared forge для нескольких клиентов одновременно, не лёгкий attach к уже запущенной IDE-сессии.

1.3 Известные боли

2. Решение

2.1 Три слоя (обязательная модель)

flowchart TB
  subgraph hosts ["Хосты"]
    Desktop["Desktop host\n(stdio child)"]
    Web["Web host\n(HTTP URL)"]
    InProc["CIDE in-proc agent"]
  end

  subgraph adapters ["Транспорт-адаптеры"]
    Stdio["stdio MCP process"]
    HttpMcp["Streamable HTTP MCP"]
    Direct["in-proc call / CLI"]
  end

  subgraph ssot ["SSOT handlers"]
    ForgeApi["Forge API"]
    NotesCore["AgentNotes.Core"]
    IdeCatalog["IdeMcpToolCatalog"]
    LocalBin["roslyn / python / debug"]
  end

  Desktop --> Stdio
  Web --> HttpMcp
  InProc --> Direct

  Stdio --> ForgeApi
  Stdio --> NotesCore
  Stdio --> IdeCatalog
  Stdio --> LocalBin
  HttpMcp --> ForgeApi
  HttpMcp --> NotesCore
  HttpMcp --> IdeCatalog
  Direct --> NotesCore
  Direct --> IdeCatalog

Инвариант: tools/list и tools/call реализуются один раз на уровне SSOT; stdio и HTTP — тонкие JSON-RPC фасады.

2.2 Тиры серверов

Tier A — stdio only (не мигрировать на HTTP)

Локальные драйверы машины разработчика:

• roslyn-mcp, python-mcp, python-debug-mcp, dotnet-debug-mcp, dotnet-build-test-mcp
• Причины: PDB, netcoredbg, venv, PATH, безопасность (отладчик не экспонировать в сеть)

Для веб-хостов: не подключать напрямую. Допустим только локальный desktop-агент.

Tier B — HTTP-first, stdio-bridge сохранить

Tier C — хост-специфичные исключения

• ChatGPT: Custom connector → HTTP URL (forge, notes, позже CIDE loopback через туннель только dev)
• Claude Desktop: claude_desktop_config.json → command/args (stdio); на Windows MSIX — виртуализированный путь к config
• Cursor: .cursor/mcp.json → stdio; для forge/notes — bridges как сейчас

2.3 Cascade IDE — два контура (не смешивать)

Реализация loopback не дублирует каталог тулов: тот же pipeline, что IdeMcpServer.

Настройки (целевые ключи в [mcp]):

[mcp]
# существующие: external_servers_json, acp_auto_inject_ide_mcp, …

# целевое (фаза 3):
loopback_enabled = true
loopback_bind = "127.0.0.1"
loopback_port = 0          # 0 = ephemeral
loopback_token_rotate = "session"  # session | launch
acp_ide_mcp_transport = "loopback" # loopback | stdio (default loopback когда GUI жив)

2.4 Agent Forge — нативный HTTP MCP (фаза 1)

Поверх существующего invoke:

1. Добавить Streamable HTTP endpoint на forge-server (/mcp или /api/v1/mcp/stream).
2. ListTools → тот же GET /api/v1/capabilities.
3. CallTool → тот же POST /api/v1/mcp/invoke.
4. Auth: FORGE_API_TOKEN / device login (уже есть).
5. AgentForge.Mcp не удалять — остаётся для Cursor/Claude Desktop.

2.5 agent-notes — HTTP рядом с status (фаза 2)

1. Handlers уже в Core (0118).
2. Поднять Streamable HTTP на loopback (рядом с /health из 2.0).
3. Stdio-процесс → второй адаптер к тем же handlers.
4. CIDE in-proc без изменений контракта knowledge_path.

2.6 Безопасность loopback / tunnel

2.7 Явные non-goals

1. Единый HTTP-сервер на весь стек — отклонено (разные trust boundary).
2. Убрать stdio — отклонено; desktop-хосты останутся на child process.
3. Переписать каждый тул под HTTP — отклонено; только адаптеры.
4. mcp-remote поверх всего stdio как архитектура — костыль для ChatGPT; допустим временно, не SSOT.
5. Смешивать Intercom team transport с MCP — 0132, 0142.

3. Фазы внедрения

Критерий готовности фазы 1: ChatGPT connector и Cursor forge-mcp работают параллельно к одному forge API.

4. Матрица хостов (нормативная)

5. Последствия

Плюсы

• Один контур тулов для desktop и web без форка логики.
• Forge и KB готовы к multi-client и Docker без смены Cursor-конфига.
• CIDE перестаёт плодить полные вторые экземпляры при ACP (0082).

Минусы / долг

• Два транспорта на сервис → тестировать оба пути.
• Документация хостов (Cursor vs ChatGPT vs Claude Desktop) усложняется.
• Windows MSIX paths для Claude Desktop — операционный overhead.

Документы к обновлению при реализации

• MCP-PROTOCOL.md — § транспорт, loopback, матрица хостов
• 0082 — ссылка на 0165 как ecosystem frame
• agent-forge docs/mcp.md — Streamable HTTP endpoint
• agent-notes-mcp README — HTTP + stdio parity

6. Открытые вопросы

1. Streamable HTTP vs SSE на forge и CIDE — зафиксировать по фактической поддержке в cursor-agent и MCP SDK .NET (приоритет: Streamable HTTP в спеке 2025+).
2. Стабильный порт loopback в settings.toml vs ephemeral — нужен ли пользователям для firewall-скриптов.
3. Multi-window CIDE (0017): один loopback на процесс приложения vs per-window endpoint.
4. Публикация forge HTTP за пределы localhost — отдельный ADR (auth, TLS, tenancy).

7. Отклонённые альтернативы