Cómo configurar MCPs en Claude Code: guía paso a paso

¿Qué son los MCPs?

Los Model Context Protocol (MCP) servers son la forma de conectar Claude Code con herramientas externas. Un MCP server expone herramientas (funciones que Claude puede llamar), recursos (datos que Claude puede leer) y prompts (templates reutilizables).

Lanzado formalmente por Anthropic a finales de 2024 como un estándar abierto, este protocolo resuelve el problema de la fragmentación de integraciones de software para modelos de lenguaje. En lugar de desarrollar conectores propietarios para cada cliente o agente, el protocolo estandariza la comunicación bidireccional mediante JSON-RPC 2.0 sobre transporte estándar (stdio) o HTTP con Server-Sent Events (SSE). Según reportes de arquitectura técnica publicados por Anthropic, estandarizar el contexto a través de MCP permite reducir hasta en un 35% el consumo de tokens en tareas iterativas de depuración frente al envío manual de registros y esquemas de datos completos.

¿Cómo saber si tu equipo realmente necesita implementar un servidor MCP en Claude Code?

Un equipo necesita un servidor MCP cuando requiere que Claude Code interactúe directamente con entornos de ejecución, bases de datos o servicios de monitoreo sin recurrir a copiar y pegar datos manualmente. Si tu flujo de desarrollo depende de consultar telemetría, manipular contenedores o auditar APIs externas frecuentemente, MCP ahorra fricción operativa inmediata.

Para organizaciones con operaciones técnicas consolidadas, la adopción de MCP representa el salto de un asistente de código pasivo a un agente ejecutor con permisos controlados. Claude Code deja de depender exclusivamente de suposiciones sobre el código local y pasa a validar el comportamiento en tiempo real contra bases de datos en pruebas o clústeres de despliegue.

Archivo de configuración

Los MCPs se configuran en ~/.claude/.mcp.json. La estructura es simple:

Cada entrada en mcpServers tiene un nombre, comando para ejecutar el server, argumentos opcionales, y variables de entorno.

Un archivo típico de configuración contiene definiciones estructuradas con llaves bien definidas. Es fundamental estructurar los parámetros evitando exponer credenciales maestras en texto plano:

{
  "mcpServers": {
    "docker": {
      "command": "mcp-server-docker",
      "args": [],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Comparativa técnica de servidores MCP comunes

La siguiente tabla describe las características operativas y requisitos de infraestructura de los servidores más adoptados para flujos de trabajo de ingeniería de software:

Servidor MCP	Tipo de Transporte	Requisitos Previos	Consumo de Recursos	Nivel de Riesgo Operativo
Docker	stdio (binario local)	Socket de Docker o túnel SSH activo	Bajo (menos de 50 MB de RAM)	Alto (modificación directa del estado de contenedores)
Grafana	stdio (vía Python/pip)	Instancia accesible y Service Account Token	Medio (depende de consultas PromQL/Loki)	Bajo (modo lectura recomendado)
Firecrawl	stdio (vía Node/npm)	Node.js 18+ y API Key de servicio	Medio (tráfico de red e intermediación web)	Medio (costos variables por consumo de tokens/API)
PostgreSQL	stdio (npx / node)	Cadena de conexión y permisos de usuario	Bajo (gestión de pools de conexión)	Crítico (lectura y escritura sobre esquemas)

Ejemplo: Docker MCP

Para controlar Docker desde Claude Code:

1. Instala el binario: descarga mcp-server-docker para tu plataforma
2. Agrega la configuración con el DOCKER_HOST apuntando a tu daemon (local o remoto via SSH)
3. Reinicia Claude Code
4. Ahora Claude puede listar containers, ver logs, start/stop servicios

Este flujo permite diagnósticos directos cuando una prueba de integración falla dentro del contenedor. En lugar de abrir otra terminal para inspeccionar los logs de un servicio de Redis o Postgres, puedes solicitar a Claude Code: "Revisa los últimos 50 registros del contenedor web-backend e infiere por qué ocurrió un kernel panic". El agente ejecutará la llamada a la herramienta interna sin salir del contexto de edición.

Ejemplo: Grafana MCP

Para consultar dashboards y alertas:

1. Instala via pip: pip install mcp-grafana
2. Crea un Service Account Token en Grafana (Admin > Service Accounts)
3. Configura con GRAFANA_URL y GRAFANA_SERVICE_ACCOUNT_TOKEN
4. Claude ahora puede consultar métricas, listar dashboards, verificar alertas

En entornos de guardia o resolución de incidentes, esta integración permite que el agente correlacione una modificación reciente en el código con picos de latencia en percentil 99 (p99) reportados por Prometheus o alertas en estado de disparo dentro de Grafana Alerting.

Ejemplo: Firecrawl MCP

Para scraping web inteligente:

1. Instala: npm install -g firecrawl-mcp
2. Obtén tu API key en firecrawl.dev
3. Configura con FIRECRAWL_API_KEY
4. Claude puede extraer contenido limpio de cualquier URL

Esta capacidad resulta crítica para solventar la desactualización natural de la ventana de contexto de los modelos fundacionales. Claude Code puede consultar documentación técnica de librerías lanzadas recientemente, transformar páginas web saturadas de JavaScript en Markdown depurado y aplicar la sintaxis correcta sin inventar parámetros obsoletos.

Consideraciones operativas para equipos de ingeniería en América Latina

La adopción de herramientas impulsadas por IA conectadas a infraestructura interna exige evaluar aspectos estructurales específicos en la región:

• Latencia de red y túneles SSH: La mayoría de los clústeres de servidores en la región operan en zonas como us-east-1 o sa-east-1 (São Paulo). Conectar MCPs locales a hosts Docker remotos en la nube mediante conexiones residenciales con jitter alto puede provocar caídas de sesión JSON-RPC. Es preferible ejecutar Claude Code en instancias intermedias tipo Cloud Workstations dentro del mismo VPC.
• Gestión de credenciales y soberanía de datos: El uso de variables de entorno locales en ~/.claude/.mcp.json requiere precauciones estrictas. Equipos distribuidos que comparten dotfiles en repositorios git corren el riesgo de filtrar tokens con permisos de escritura hacia clústeres de producción o bases de datos de clientes corporativos regulados por leyes locales de protección de datos personales.
• Costos indirectos de red y APIs: Integraciones como Firecrawl consumen cuotas por llamada. En presupuestos de tecnología cotizados en monedas locales con alta volatilidad cambiaria frente al dólar estadounidense, los consumos no monitoreados por bucles de reintento de un agente de IA pueden impactar el presupuesto operativo mensual imprevistamente.

Troubleshooting

MCPs no cargan: Se inicializan al arrancar Claude Code. Si los agregaste o cambiaste config, reinicia la sesión.

Timeout: MCPs que conectan a servicios remotos (Docker vía SSH, Grafana) pueden tardar. Verifica conectividad primero.

Windows: Usa rutas con forward slashes en .mcp.json. Binarios deben estar en PATH o usar ruta absoluta.

Errores comunes con permisos de sockets y Node.js

Cuando se utiliza el servidor Docker en Linux o macOS, es frecuente que el proceso hijo del servidor MCP falle silenciosamente si el usuario que ejecuta Claude Code no pertenece al grupo del sistema correspondiente (por ejemplo, el grupo docker en Linux). Si la llamada devuelve un error 13 (Permission Denied), se debe verificar el acceso directo ejecutando un comando de prueba con la herramienta de línea de comandos habitual antes de configurar el archivo JSON.

En servidores MCP implementados con npx, asegúrate de contar con la versión activa de Node en el entorno global. Los gestores de versiones como nvm o fnm a menudo no propagan las variables de entorno si Claude Code se ejecuta desde interfaces no interactivas o IDEs integrados, provocando errores donde el ejecutable de Node no es localizado.