meta(wiki): ingest concepts/mcp-init-resilience in OpeItcLoc03/admin

.wiki/concepts/mcp-init-resilience.md

@@ -0,0 +1,59 @@
+---
+title: mcp-init-resilience
+type: concept
+ingested_at: '2026-06-10T10:58:09.003Z'
+ingested_by: OpeItcLoc03@DESKTOP-NSEF0UK
+source_project: OpeItcLoc03/workshop
+---
+# MCP init resilience — почему user-level MCP не стартуют
+
+Зафиксировано 2026-05-23. Round 2 не начат.
+
+## Класс инцидента
+
+Два прецедента (2026-05-21, 2026-05-23): Claude Code не поднимает часть user-level MCP-серверов
+при инициализации. `/reload-plugins` не помогает (он reload'ит только plugin-MCPs, не user-level entries).
+
+**Пострадавшие серверы:** interns, kicad, context7 — общее: все имеют **multi-step launcher**.
+- `interns` — `pass show` (blocking gpg-agent call) → exec python
+- `kicad` — node spawn'ит python helper (двойной spawn)
+- `context7` — `npx -y @upstash/context7-mcp` (npm fetch / cache lock при первом запуске)
+
+**4 успешных** используют прямой launcher (direct npx/node/uv).
+
+## Гипотеза root cause
+
+CC MCP supervisor запускает MCPs параллельно при init, ждёт `initialize` JSON-RPC в пределах
+timeout (значение неизвестно). Multi-step launchers не укладываются → помечаются disconnected.
+Retry в сессии не делается. Параллельная вторая CC сессия (+28с) — вероятный contributing factor.
+
+## 7 открытых вопросов
+
+1. Сколько секунд ждёт CC `initialize` ответа? Есть ли `mcp.startupTimeoutMs` knob в `settings.json`?
+2. Можно ли получить MCP transport stderr-логи? (`claude --mcp-debug` / `CLAUDE_MCP_DEBUG=1`)
+3. `pass show` в `interns-mcp-launcher.sh` — заменить на env-file (уже делается для других секретов)?
+4. Serial-launch wrapper между двумя CC окнами?
+5. MCPs как long-lived daemons + CC connect по сокету?
+6. Plugin MCP (context7) — почему тоже упал при `/reload-plugins`?
+7. Enhancement request Anthropic: `/reload-mcp` для user-level серверов
+
+## Fix-направления (не выбраны)
+
+| Направление | Эффект | Цена |
+|---|---|---|
+| Убрать `pass show` из interns launcher → env-file | устраняет gpg-blocking | API key plain at rest |
+| Serial-launch wrapper CC сессий | снимает race | UX friction (ждать 30s) |
+| Найти `mcp.startupTimeoutMs` knob | увеличить порог | если knob'а нет — null |
+| MCPs как long-lived daemons + sockets | устраняет per-session re-init | зависит от CC поддержки |
+| Push к Anthropic: `/reload-mcp` | runtime recovery | долго, off our hands |
+
+## Preemptive guards
+
+- **Не редактировать `interns-mcp-launcher.sh` импульсивно** — сначала воспроизвести без параллельной .admin сессии
+- **Не выпиливать `pass` без обсуждения** security trade-off
+- **Не предлагать `--mcp-debug` рестарт** в активной сессии
+
+## Round 2: первые два шага
+
+1. Проверить `mcp.startupTimeoutMs` в `~/.claude/settings.json` schema
+2. Воспроизвести в чистой сессии (только одна CC, без параллельной .admin) — если стартуют → виновен race; если нет → виноват launcher