103 lines
6.3 KiB
Markdown
103 lines
6.3 KiB
Markdown
# Fix: los MCPs custom (gitea, docmost, github-personal, penpot, atlassian) dejaron de cargar
|
|
|
|
## Context
|
|
|
|
El usuario preguntó a qué MCPs tenía acceso Claude Code en esta sesión. Solo apareció el
|
|
conector cloud de Atlassian (vía claude.ai) — ninguno de los 5 servidores custom definidos en
|
|
`dev-environment/managed-mcp.json` (gitea, docmost, github-personal, penpot, atlassian-vía-npx)
|
|
está cargado. El usuario confirmó que **antes sí funcionaban** y no sabe por qué dejaron de
|
|
hacerlo.
|
|
|
|
Investigación (todo lectura, sin cambios):
|
|
|
|
1. `claude mcp list` solo lista los conectores cloud de claude.ai (Atlassian, Gmail, Google
|
|
Drive, etc.) — cero rastro de gitea/docmost/github-personal/penpot/atlassian-custom. Esto
|
|
confirma que Claude Code no está leyendo esos 5 servidores desde ninguna fuente.
|
|
2. Existe un plan previo del propio usuario
|
|
(`~/.claude/plans/creo-que-hay-un-rosy-unicorn.md`) que documenta la causa raíz genérica:
|
|
**`settings.json` no soporta la clave `mcpServers`** (se ignora). Los MCP solo se leen desde
|
|
`.mcp.json`, `~/.claude.json`, `--mcp-config`, o el mecanismo enterprise
|
|
**`/etc/claude-code/managed-mcp.json`** (ruta fija del sistema).
|
|
3. En [dev-environment/vscode-server/docker-compose.yaml](dev-environment/vscode-server/docker-compose.yaml#L60)
|
|
(y su análogo en `vscode-server-telus/docker-compose.yaml`), el volumen monta
|
|
`managed-mcp.json` en **`/home/aleleba/.claude/managed-mcp.json`** — una ruta que Claude Code
|
|
nunca lee. Esa línea se agregó en el commit `b81ffda` pero con la ruta equivocada; el plan
|
|
`rosy-unicorn` (que especifica la ruta correcta `/etc/claude-code/managed-mcp.json`) nunca se
|
|
llegó a aplicar en el compose.
|
|
4. La razón de que "antes funcionara": el commit HEAD de
|
|
[dev-environment/.claude.json](dev-environment/.claude.json) (mismo archivo que se monta como
|
|
`~/.claude.json` dentro del contenedor) sí tiene el bloque `mcpServers` con los 5 servidores.
|
|
Pero el archivo **actual en disco** (working tree, sin commitear) **perdió por completo esa
|
|
clave** — el resto del archivo también cambió drásticamente (`numStartups` bajó de 11 a 2,
|
|
aparecieron/desaparecieron decenas de feature flags `tengu_*`), lo que indica que Claude Code
|
|
reescribió ese archivo (por ejemplo tras una actualización de versión) y no preservó la clave
|
|
custom `mcpServers` que se había agregado manualmentente.
|
|
|
|
En resumen: el mecanismo que sí funcionaba (`mcpServers` dentro de `~/.claude.json`) es frágil
|
|
porque ese archivo lo administra/reescribe Claude Code y puede perder claves custom en cualquier
|
|
reinicio o actualización — que es exactamente lo que pasó. El mecanismo robusto
|
|
(`/etc/claude-code/managed-mcp.json`, que Claude Code no reescribe) está definido y documentado
|
|
pero nunca se aplicó realmente en el compose.
|
|
|
|
## Approach
|
|
|
|
Aplicar las dos capas de arreglo que el propio usuario ya había diseñado, pero que quedaron a
|
|
medias — decisión confirmada con el usuario: usar directamente la ruta enterprise correcta
|
|
(`/etc/claude-code/managed-mcp.json`) en vez de restaurar el `mcpServers` frágil dentro de
|
|
`~/.claude.json`.
|
|
|
|
### 1. Fix inmediato en este ambiente (sin recrear el contenedor)
|
|
|
|
Crear el archivo `/etc/claude-code/managed-mcp.json` directamente en el filesystem de este
|
|
contenedor ya corriendo, con el mismo contenido (5 servidores) que
|
|
[dev-environment/managed-mcp.json](dev-environment/managed-mcp.json). Al no venir de un volumen
|
|
todavía, este archivo puntual no persiste si el contenedor se recrea — por eso el paso 2 es
|
|
necesario para que sobreviva a futuros rebuilds/restarts.
|
|
|
|
### 2. Fix durable en ambos docker-compose (requiere recrear el contenedor — acción del usuario)
|
|
|
|
Corregir la ruta de montaje de `managed-mcp.json` en ambos docker-compose, de
|
|
`/home/aleleba/.claude/managed-mcp.json` a `/etc/claude-code/managed-mcp.json`, tal como
|
|
especifica `rosy-unicorn.md`:
|
|
|
|
- [dev-environment/vscode-server/docker-compose.yaml](dev-environment/vscode-server/docker-compose.yaml#L60)
|
|
- `dev-environment/vscode-server-telus/docker-compose.yaml` (línea equivalente, mismo patrón)
|
|
|
|
Esto hace que el origen de verdad para estos 5 MCP sea un archivo que Claude Code trata como
|
|
enterprise-managed (solo lectura para él) y por lo tanto no lo va a volver a pisar en una futura
|
|
actualización — eliminando la causa raíz de fondo, no solo el síntoma.
|
|
|
|
**Importante:** este cambio de docker-compose no toma efecto hasta que el contenedor se recree
|
|
(`docker-compose up -d --force-recreate` o equivalente), lo cual reinicia todo el entorno de
|
|
desarrollo (VS Code server, túnel, sesión actual). Esta acción disruptiva **no se ejecuta como
|
|
parte de este plan** — se deja documentada para que el usuario la corra cuando le convenga.
|
|
|
|
### Nota de seguridad (fuera de alcance, solo aviso)
|
|
|
|
`dev-environment/managed-mcp.json` y `dev-environment/.claude.json` contienen tokens en texto
|
|
plano (gitea, github, docmost, etc.) y **ambos ya están commiteados al repo** (no en
|
|
`.gitignore`). Esto es preexistente, no introducido por este fix. Se menciona como riesgo a
|
|
evaluar aparte (rotar tokens / gitignore / limpiar historial), no se toca en este plan.
|
|
|
|
## Files to change
|
|
|
|
1. `/etc/claude-code/managed-mcp.json` (dentro de este contenedor, fuera del repo) — crear con
|
|
el contenido de [dev-environment/managed-mcp.json](dev-environment/managed-mcp.json) (5
|
|
servidores). Fix inmediato, no persistente por sí solo.
|
|
2. `dev-environment/vscode-server/docker-compose.yaml` — cambiar el target del volumen de
|
|
`managed-mcp.json` de `/home/aleleba/.claude/managed-mcp.json` a
|
|
`/etc/claude-code/managed-mcp.json`.
|
|
3. `dev-environment/vscode-server-telus/docker-compose.yaml` — mismo cambio de ruta en la línea
|
|
análoga.
|
|
|
|
## Verification
|
|
|
|
1. Tras crear el archivo en `/etc/claude-code/managed-mcp.json`: reiniciar la sesión/proceso de
|
|
Claude Code (o `claude` CLI) dentro del contenedor y correr `claude mcp list` — deben aparecer
|
|
`gitea`, `docmost`, `github-personal`, `penpot` y `atlassian` (el custom, vía npx) como
|
|
`Connected`.
|
|
2. Tras el fix durable (cuando el usuario recree cada contenedor con el compose corregido):
|
|
`cat /etc/claude-code/managed-mcp.json` debe mostrar el JSON de los 5 servidores sin haber
|
|
sido creado a mano, y `claude mcp list` debe seguir mostrándolos `Connected` incluso después
|
|
de reinicios — confirmando que ya no depende de un paso manual ni de `~/.claude.json`.
|