Configurar MCP Servers en Claude Code

Descripción de la cápsula

Este es el momento de verdad. Has construido MCP servers, los has testeado, les has agregado logging. Pero nada de eso importa hasta que Claude Code puede usarlos. Un MCP server perfectamente implementado que no está conectado a Claude Code es un programa que nadie usa.

La configuración de Claude Code para MCP servers involucra settings files, scopes (user vs project), permisos, y verificación. Cada paso es verificable — no vas a "esperar que funcione." Vas a confirmar en cada paso que Claude Code ve tu server, puede listar sus tools, y puede invocarlos.

Esta cápsula te guía paso a paso. Al terminar, tu MCP server estará conectado a Claude Code y funcionando en tus flujos de trabajo reales.

Anatomía de la configuración MCP en Claude Code

Dónde se configura

Claude Code busca configuración MCP en dos lugares:

Configuración MCP:
├── User scope (global)
│   └── ~/.claude/settings.json
│       → Aplica a TODOS tus proyectos
│       → Ideal para servers que usas siempre (filesystem, GitHub, etc.)
│
└── Project scope (por proyecto)
    └── .claude/settings.json (en la raíz del proyecto)
        → Aplica SOLO a este proyecto
        → Ideal para servers específicos del proyecto
        → Se puede versionar en git (compartir con el equipo)

Formato de configuración

La configuración MCP vive dentro del campo mcpServers del archivo de settings:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["ruta/al/server/dist/index.js"],
      "env": {
        "VARIABLE": "valor"
      }
    }
  }
}

Los campos:

Configurar un MCP server TypeScript

Paso 1: Compilar tu server

Asegúrate de que tu server está compilado y funciona:

cd ~/proyectos/my-mcp-server
npm run build
node dist/index.js < /dev/null  # Verifica que arranca sin errores

Paso 2: Agregar a Claude Code (user scope)

Usa el CLI de Claude Code para agregar tu server:

claude mcp add file-utils node ~/proyectos/my-mcp-server/dist/index.js

Este comando modifica ~/.claude/settings.json automáticamente:

{
  "mcpServers": {
    "file-utils": {
      "command": "node",
      "args": ["/Users/tu-usuario/proyectos/my-mcp-server/dist/index.js"]
    }
  }
}

Paso 3: Verificar la conexión

Abre Claude Code y verifica:

claude
# Dentro de Claude Code, ejecuta:
/mcp

El comando /mcp muestra todos los MCP servers conectados y su estado:

MCP Servers:
  file-utils: connected
    Tools: read_file, list_files
    Resources: status://server

Si ves connected y tus tools/resources listados, la configuración es correcta.

Paso 4: Probar un tool

Pide a Claude Code que use uno de tus tools:

Tú: "Lee el archivo ~/proyectos/my-mcp-server/README.md"

Claude Code: [Invoca read_file con filePath: "...README.md"]
El contenido del archivo es:
# Mi MCP Server
...

Si Claude Code invoca el tool y retorna el resultado correcto, la integración funciona end-to-end.

Configurar un MCP server Python

Paso 1: Verificar el server

cd ~/proyectos/my-mcp-server-python
python server.py  # Verifica que arranca sin errores (Ctrl+C para salir)

Paso 2: Agregar a Claude Code

claude mcp add python-utils python ~/proyectos/my-mcp-server-python/server.py

Resultado en settings:

{
  "mcpServers": {
    "python-utils": {
      "command": "python",
      "args": ["/Users/tu-usuario/proyectos/my-mcp-server-python/server.py"]
    }
  }
}

Con virtual environment

Si tu server Python usa un virtual environment:

claude mcp add python-utils \
  ~/proyectos/my-mcp-server-python/.venv/bin/python \
  ~/proyectos/my-mcp-server-python/server.py

O editando el settings manualmente:

{
  "mcpServers": {
    "python-utils": {
      "command": "/Users/tu-usuario/proyectos/my-mcp-server-python/.venv/bin/python",
      "args": ["server.py"],
      "cwd": "/Users/tu-usuario/proyectos/my-mcp-server-python"
    }
  }
}

Configurar servers con variables de entorno

Muchos MCP servers necesitan API keys u otras configuraciones:

{
  "mcpServers": {
    "github-server": {
      "command": "node",
      "args": ["/path/to/github-server/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_aqui"
      }
    }
  }
}

Advertencia de seguridad: Si pones tokens en .claude/settings.json del proyecto, no hagas commit de ese archivo sin antes verificar que no contiene secretos. Usa variables de entorno del sistema o un .env file cuando sea posible.

Alternativa: usar variables del sistema

{
  "mcpServers": {
    "github-server": {
      "command": "node",
      "args": ["/path/to/github-server/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Luego configura la variable en tu shell:

export GITHUB_TOKEN="ghp_tu_token_aqui"

Configurar múltiples servers

Claude Code puede conectarse a múltiples MCP servers simultáneamente:

{
  "mcpServers": {
    "file-utils": {
      "command": "node",
      "args": ["/path/to/file-utils/dist/index.js"]
    },
    "python-utils": {
      "command": "python",
      "args": ["/path/to/python-utils/server.py"]
    },
    "github-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Cómo Claude Code maneja múltiples servers

Cuando tienes múltiples servers:

Claude Code recibe un request del usuario
├── Lista tools de TODOS los servers conectados
├── Decide cuál tool usar basado en la descripción
├── Invoca el tool del server correspondiente
└── Retorna el resultado al usuario

Ejemplo:
  "Lee el README y busca issues abiertos en GitHub"
  ├── read_file → file-utils server
  └── search_issues → github-server

Claude Code maneja la orquestación automáticamente. Tú solo configuras los servers; Claude decide cuál usar basándose en las descripciones de los tools.

Nombres de servers

Los nombres deben ser únicos y descriptivos:

// ✅ Nombres claros
"file-utils": { ... }
"github-integration": { ... }
"project-database": { ... }

// ❌ Nombres confusos
"server1": { ... }
"my-server": { ... }
"test": { ... }

Project scope: configuración por proyecto

Cuándo usar project scope

Usa project scope cuando:

• El server es específico de un proyecto (e.g., accede a la base de datos del proyecto)
• Quieres compartir la configuración con el equipo (versionada en git)
• El server usa paths relativos al proyecto

Crear configuración de proyecto

mkdir -p .claude

Crea .claude/settings.json:

{
  "mcpServers": {
    "project-db": {
      "command": "node",
      "args": ["./tools/db-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Prioridad: project vs user

Si el mismo server está configurado en ambos scopes, Claude Code usa la configuración del project scope (más específica):

Resolución de configuración:
├── Project scope (.claude/settings.json) → prioridad alta
└── User scope (~/.claude/settings.json)  → prioridad baja

Si "file-utils" existe en ambos:
→ Se usa la configuración del project scope

Permisos y seguridad

Cómo funcionan los permisos

Cuando Claude Code quiere invocar un tool de tu MCP server, te pide confirmación la primera vez:

Claude Code: Quiero usar el tool "read_file" del server "file-utils".
             ¿Permitir? [y/n/always]

  y       → Permitir esta vez
  n       → Denegar
  always  → Permitir siempre para este tool

Configurar permisos persistentes

Si seleccionas "always," la configuración se guarda. También puedes gestionar permisos con el CLI:

# Ver permisos actuales
claude mcp list

# Ver detalles de un server específico
claude mcp get file-utils

Consideraciones de seguridad

Reglas de seguridad para MCP servers:
├── No expongas tools destructivos sin confirmación
│   (delete_file, drop_database, etc.)
├── No incluyas secrets en settings versionados
├── Usa paths absolutos para evitar ambigüedades
├── Limita el scope de acceso del server
│   (solo los directorios/APIs necesarios)
└── Revisa los permisos periódicamente

Verificación completa paso a paso

Después de configurar un server, sigue esta checklist:

1. ¿El server arranca?

# TypeScript
node dist/index.js < /dev/null 2>&1
# Debería terminar sin errores (exit code 0)

# Python
python server.py < /dev/null 2>&1

2. ¿Claude Code lo ve?

claude
# Dentro de Claude Code:
/mcp

Busca tu server en la lista. Estado debe ser connected.

3. ¿Los tools se listan?

En el output de /mcp, verifica que tus tools aparecen con sus nombres correctos.

4. ¿Un tool funciona?

Pide a Claude Code que use un tool específico:

"Usa el tool list_files para listar los archivos en el directorio actual"

5. ¿Los errores se manejan?

Pide a Claude Code algo que debería fallar:

"Usa read_file para leer /archivo/que/no/existe"

Verifica que Claude Code muestra un error descriptivo, no un crash.

Checklist resumen

□ Server compila y arranca sin errores
□ Settings configurado (user o project scope)
□ /mcp muestra el server como "connected"
□ Tools aparecen en la lista de /mcp
□ Al menos un tool funciona correctamente
□ Errores se manejan con mensajes descriptivos
□ Variables de entorno configuradas (si aplica)
□ Permisos aceptados para los tools

Gestión de servers con el CLI

Comandos útiles

# Agregar un server
claude mcp add <nombre> <command> [args...]

# Listar servers configurados
claude mcp list

# Ver detalles de un server
claude mcp get <nombre>

# Eliminar un server
claude mcp remove <nombre>

# Agregar con scope específico
claude mcp add --scope user <nombre> <command> [args...]
claude mcp add --scope project <nombre> <command> [args...]

Ejemplo: flujo completo con CLI

# 1. Agregar tu server
claude mcp add file-utils node ~/mcp-servers/file-utils/dist/index.js

# 2. Verificar que se agregó
claude mcp list
# → file-utils: node /Users/tu-usuario/mcp-servers/file-utils/dist/index.js

# 3. Abrir Claude Code y verificar
claude
# → /mcp
# → file-utils: connected

# 4. Si necesitas cambiar la configuración, edita directamente:
# ~/.claude/settings.json

# 5. Si necesitas remover:
claude mcp remove file-utils

Ejercicios

Ejercicio 1: Configurar tu server en user scope (Fácil)

Toma el MCP server que construiste en el módulo 4 o 5. Configúralo en Claude Code usando claude mcp add. Verifica con /mcp que aparece como connected.

# Para TypeScript
cd ~/proyectos/my-mcp-server-ts
npm run build
claude mcp add my-server-ts node ~/proyectos/my-mcp-server-ts/dist/index.js

# Para Python
claude mcp add my-server-py python ~/proyectos/my-mcp-server-py/server.py

# Verificar
claude
# /mcp → debería mostrar tu server como "connected"

Ejercicio 2: Configurar project scope (Fácil)

Crea una configuración de project scope en uno de tus proyectos. El server debe usar paths relativos al proyecto.

cd ~/proyectos/mi-proyecto
mkdir -p .claude

{
  "mcpServers": {
    "project-tools": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"]
    }
  }
}

Ejercicio 3: Múltiples servers (Medio)

Configura dos MCP servers diferentes (e.g., uno en TypeScript y uno en Python) en Claude Code. Verifica que ambos aparecen en /mcp y que puedes usar tools de ambos en la misma conversación.

claude mcp add file-utils-ts node ~/mcp-servers/file-utils/dist/index.js
claude mcp add api-utils-py python ~/mcp-servers/api-utils/server.py
claude mcp list
# → file-utils-ts, api-utils-py

# En Claude Code:
# /mcp → ambos como "connected"
# Prueba: "Lista los archivos en el directorio actual y luego consulta el status del API"

Ejercicio 4: Server con variables de entorno (Medio)

Configura un MCP server que requiere una variable de entorno (e.g., un API token). Configúralo usando variables del sistema, no hardcodeadas en el settings file.

# 1. Configura la variable en tu shell
echo 'export MY_API_TOKEN="token_seguro_aqui"' >> ~/.zshrc
source ~/.zshrc

# 2. Agrega el server con env
claude mcp add my-api-server node ~/mcp-servers/api-server/dist/index.js

# 3. Edita ~/.claude/settings.json para agregar env

{
  "mcpServers": {
    "my-api-server": {
      "command": "node",
      "args": ["/Users/tu-usuario/mcp-servers/api-server/dist/index.js"],
      "env": {
        "API_TOKEN": "${MY_API_TOKEN}"
      }
    }
  }
}

Ejercicio 5: Verificación completa (Difícil)

Ejecuta la checklist completa de verificación con uno de tus servers. Documenta el resultado de cada paso. Si algún paso falla, diagnostica y resuelve el problema antes de continuar.

Checklist de verificación — file-utils server:

1. ¿Server arranca?
   $ node dist/index.js < /dev/null 2>&1
   → Resultado: exit code 0 ✅

2. ¿Claude Code lo ve?
   /mcp → file-utils: connected ✅

3. ¿Tools se listan?
   → read_file, list_files ✅

4. ¿Tool funciona?
   "Lista los archivos en ~/proyectos"
   → Retorna lista de archivos ✅

5. ¿Errores se manejan?
   "Lee /archivo/inexistente"
   → "Error: ENOENT: no such file or directory" ✅

6. Variables de entorno: N/A (no requiere)
7. Permisos: aceptados ✅

Resultado: 7/7 pasos exitosos

Troubleshooting de configuración

"Server aparece como 'disconnected' en /mcp"

Causa probable: El server crashea al iniciar.

Solución:

# Ejecuta el server manualmente para ver el error
node dist/index.js < /dev/null 2>&1

# Errores comunes:
# - "Cannot find module" → npm run build
# - "ENOENT" → path incorrecto en settings
# - "SyntaxError" → error en el código

"Tool no aparece en la lista de /mcp"

Causa probable: El tool no se registra antes de que el server esté listo.

Solución: Verifica que el tool se registra en el scope correcto de tu server (antes de connect()).

"/mcp no muestra ningún server"

Causa probable: El settings file no está en la ubicación correcta o tiene JSON inválido.

Solución:

# Verifica que el archivo existe
cat ~/.claude/settings.json

# Valida el JSON
python -c "import json; json.load(open('$HOME/.claude/settings.json'))"

Resumen

En esta cápsula aprendiste:

• Dos scopes de configuración: user (~/.claude/settings.json) para servers globales, project (.claude/settings.json) para servers específicos
• El formato de configuración usa command, args, env, y opcionalmente cwd
• claude mcp add es la forma más rápida de configurar un server
• /mcp en Claude Code te muestra el estado de todos los servers conectados
• Variables de entorno se configuran en el campo env, preferiblemente con ${VAR} en vez de valores hardcodeados
• Múltiples servers funcionan simultáneamente — Claude Code orquesta automáticamente cuál usar
• La checklist de verificación de 8 pasos confirma que todo funciona end-to-end
• Permisos se gestionan interactivamente la primera vez y se pueden persistir

Este es el paso que hace que todo el trabajo de los módulos 4-6 sea útil. Tu MCP server ya no es solo un programa — es una herramienta que Claude Code usa nativamente.

Recursos adicionales

1. Claude Code MCP Documentation — Documentación oficial de MCP en Claude Code
2. Claude Code CLI Reference — Referencia del CLI incluyendo claude mcp
3. MCP Servers Registry — Servers oficiales para referencia de configuración
4. Claude Code Settings — Documentación de settings files

Siguiente cápsula: Troubleshooting y Errores Comunes — guía completa de los errores más frecuentes y cómo resolverlos, más un mini-proyecto que integra todo lo aprendido en este módulo.