Claude Code y MCP: conecta tu agente de código con cualquier herramienta

Qué es MCP en Claude Code: arquitectura cliente y descubrimiento de herramientas

El Model Context Protocol define un estándar de comunicación entre modelos de lenguaje y herramientas externas. Claude Code implementa el lado cliente de ese protocolo: al arrancar una sesión, se conecta a cada uno de los servidores MCP configurados, solicita la lista de herramientas que exponen y las incorpora al contexto disponible para el modelo junto con las herramientas nativas del agente (lectura de archivos, ejecución de shell, git, etc.).

Desde el punto de vista del modelo no hay diferencia entre una herramienta nativa y una herramienta MCP: ambas aparecen como opciones invocables con un nombre, una descripción y un esquema de parámetros. Cuando Claude Code decide llamar a una herramienta MCP, envía la solicitud al servidor correspondiente a través del canal de transporte configurado, recibe el resultado y lo incorpora al contexto de la sesión para continuar razonando.

Esta arquitectura permite un nivel de extensión que sería imposible con herramientas integradas: cualquier equipo puede publicar un servidor MCP que exponga la lógica específica de su negocio, sus APIs internas o sus fuentes de datos, y Claude Code puede consumirlo sin modificaciones en el propio agente. La documentación oficial de Anthropic sobre MCP en Claude Code mantiene la referencia técnica actualizada.

Cómo descubre Claude Code las herramientas disponibles

Al inicio de cada sesión Claude Code ejecuta una llamada de inicialización a cada servidor configurado. El servidor responde con la lista de herramientas que ofrece, incluyendo nombre, descripción y esquema JSON de los parámetros de entrada. Claude Code agrega todas estas definiciones y las envía al modelo junto con las instrucciones del sistema. A partir de ese momento el modelo puede decidir invocar cualquiera de ellas según lo que el usuario solicite.

Si un servidor MCP cae o devuelve error durante la inicialización, Claude Code lo registra en el log de la sesión y continúa con el resto de servidores disponibles. Las herramientas del servidor caído simplemente no aparecen en el conjunto disponible para esa sesión.

Cómo añadir servidores MCP a Claude Code

Hay dos formas principales de registrar un servidor MCP: mediante el comando claude mcp add desde el terminal, o editando directamente el archivo de configuración .claude/settings.json.

Mediante la CLI

El comando claude mcp add es la forma más rápida para empezar. Su sintaxis básica es:

claude mcp add <nombre> -- <comando> [argumentos]

El nombre es el identificador que usarás para referenciar el servidor. El comando es el proceso que Claude Code arrancará para comunicarse con el servidor vía stdio. Ejemplos reales:

# Servidor de sistema de archivos (acceso a directorios fuera del sandbox)
claude mcp add filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/proyectos

# Servidor de GitHub (gestion de PRs e issues)
claude mcp add github -- npx @modelcontextprotocol/server-github

# Servidor de Slack
claude mcp add slack -- npx @modelcontextprotocol/server-slack

# Servidor de base de datos PostgreSQL
claude mcp add postgres -- npx @modelcontextprotocol/server-postgres postgresql://localhost/midb

# Servidor con SSE (remoto via URL)
claude mcp add mi-api -- --transport sse https://api.miempresa.com/mcp

Para ver todos los servidores configurados en el proyecto actual:

claude mcp list

Y para eliminar uno:

claude mcp remove <nombre>

Mediante settings.json

La configuración se almacena en .claude/settings.json dentro del directorio del proyecto (configuración de proyecto) o en ~/.claude/settings.json (configuración global de usuario). La estructura para la sección de MCP es la siguiente:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/home/user/proyectos"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_aqui"
      }
    },
    "mi-api": {
      "transport": "sse",
      "url": "https://api.miempresa.com/mcp"
    }
  }
}

Editar el JSON directamente es útil cuando quieres controlar la versión del paquete, pasar variables de entorno o trabajar con configuraciones más complejas. Los cambios tienen efecto en la siguiente sesión de Claude Code.

Ámbitos de configuración

Claude Code aplica la configuración de MCP en dos ámbitos:

• Proyecto (.claude/settings.json en la raíz del repo): los servidores solo están disponibles cuando trabajas en ese proyecto concreto. Ideal para servidores específicos de un proyecto como su base de datos o sus APIs internas.
• Usuario (~/.claude/settings.json): los servidores están disponibles en todos tus proyectos. Útil para herramientas globales como el conector de GitHub o Slack.

Transportes: stdio y SSE

MCP define dos mecanismos de transporte para la comunicación entre cliente y servidor. Claude Code soporta ambos, y la elección depende de dónde vive el servidor que quieres conectar.

Stdio (Standard Input/Output)

Es el transporte por defecto y el más habitual para servidores locales. Claude Code lanza el proceso servidor como un subproceso y se comunica con él a través de su stdin y stdout usando mensajes JSON. El ciclo de vida del servidor está ligado al de la sesión de Claude Code: cuando la sesión termina, el proceso servidor se detiene.

Ventajas de stdio:

• Sin configuración de red: el servidor solo es accesible desde el proceso de Claude Code.
• Sin autenticación adicional: el aislamiento es el del propio sistema operativo.
• Latencia mínima al ser comunicación local entre procesos.

SSE (Server-Sent Events)

El transporte SSE permite conectar servidores MCP que corren como servicios HTTP, potencialmente en máquinas remotas. Claude Code establece una conexión HTTP con la URL del servidor y recibe eventos a través del mecanismo estándar de Server-Sent Events.

Para usar SSE se específica el transporte y la URL en la configuración:

claude mcp add mi-servicio -- --transport sse https://mcp.miempresa.com/claude

O en settings.json:

{
  "mcpServers": {
    "mi-servicio": {
      "transport": "sse",
      "url": "https://mcp.miempresa.com/claude",
      "headers": {
        "Authorization": "Bearer tu_api_key"
      }
    }
  }
}

SSE es el transporte adecuado cuando el servidor MCP es un microservicio compartido por varios desarrolladores del equipo, cuando necesita acceso a recursos que no están en la máquina local, o cuando quieres que el servidor persista entre sesiones de Claude Code.

Ejemplo práctico: configurar GitHub y una base de datos

Para ilustrar cómo funciona la integración en un proyecto real, vamos a configurar dos servidores que son un caso de uso típico para un equipo de desarrollo: acceso a GitHub para gestionar pull requests y acceso a una base de datos PostgreSQL para consultar datos.

Paso 1 — Preparar las credenciales

El servidor de GitHub necesita un token con permisos sobre el repositorio. Créalo en GitHub > Settings > Developer settings > Personal access tokens con los scopes repo y read:org. El servidor de PostgreSQL necesita la cadena de conexión de tu base de datos.

Paso 2 — Registrar los servidores

En la raíz del proyecto, edita o crea .claude/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tu_token_aqui"
      }
    },
    "base-de-datos": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-postgres",
        "postgresql://usuario:password@localhost:5432/mi_base_de_datos"
      ]
    }
  }
}

Alternativamente, puedes registrar cada servidor con el comando CLI:

# GitHub
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_tu_token \
  claude mcp add github -- npx @modelcontextprotocol/server-github

# PostgreSQL
claude mcp add base-de-datos -- npx @modelcontextprotocol/server-postgres \
  postgresql://usuario:password@localhost:5432/mi_base_de_datos

Paso 3 — Verificar la configuración

claude mcp list

La salida debe mostrar los dos servidores con su estado. Si algún servidor tiene un error de configuración lo indica en este listado.

Paso 4 — Usar los servidores en una sesión

Arranca Claude Code en el directorio del proyecto:

claude

Al iniciar la sesión, Claude Code se conecta a ambos servidores y descubre sus herramientas. Ahora puedes hacer peticiones que los involucren de forma natural:

Busca todos los pull requests abiertos en el repositorio que tengan el label "bug",
revisa el código de cada uno y dime cuál tiene mayor impacto potencial según
los datos de la tabla "errores_produccion" en la base de datos.

Claude Code orquestará las llamadas a las herramientas de GitHub (listar PRs, leer diffs) y de PostgreSQL (ejecutar la query) sin que tengas que especificar cómo hacerlo. La respuesta integra la información de ambas fuentes.

Paso 5 — Confirmar permisos

La primera vez que Claude Code invoca una herramienta de cada servidor muestra un prompt de confirmación con la herramienta, los parámetros y el servidor que la gestiona. Puedes aprobar la acción puntual o indicarle que la recuerde para el resto de la sesión.

Recursos MCP para inyección de contexto

Además de herramientas, el protocolo MCP define el concepto de recursos: datos que el servidor expone y que el cliente puede incorporar al contexto de la conversación. Los recursos permiten que un servidor no solo ejecute acciones sino que también proporcione información de referencia.

Ejemplos típicos de recursos en un servidor MCP:

• Un servidor de documentación que expone artículos técnicos como recursos de texto.
• Un servidor de base de datos que expone el esquema completo como recurso.
• Un servidor de configuración que expone los valores de variables de entorno del proyecto.
• Un servidor de diseño que expone tokens de diseño y guías de estilo.

Cuando Claude Code tiene acceso a estos recursos puede incorporarlos al contexto de la sesión para responder preguntas, generar código coherente con los patrones del proyecto o tomar decisiones informadas sin necesidad de que el usuario pegue documentación manualmente en el chat. La especificación completa de recursos está en modelcontextprotocol.io/docs/concepts/resources.

Seguridad y permisos en Claude Code con MCP

Ampliar las capacidades de un agente de código con herramientas externas introduce consideraciones de seguridad que conviene entender antes de poner servidores MCP en producción.

Modelo de permisos de Claude Code

Claude Code implementa un modelo de consentimiento explícito: antes de ejecutar cualquier herramienta MCP por primera vez en una sesión, muestra al usuario el nombre de la herramienta, los parámetros que se van a enviar y el servidor que la gestionará. El usuario puede aprobar la acción, rechazarla o aprobarla para todas las llamadas futuras a esa herramienta en la misma sesión.

Este mecanismo garantiza que el agente no ejecute acciones con efectos secundarios (enviar un mensaje, modificar un registro de base de datos, crear un PR) sin que el desarrollador sea consciente de ello.

Aislamiento de los servidores

Los servidores MCP que se conectan vía stdio se ejecutan como procesos separados en la máquina local, con los permisos del usuario que ejecuta Claude Code. No tienen acceso a las credenciales de Anthropic, al historial de la conversación ni a otros servidores MCP conectados. Cada servidor solo ve las llamadas que le llegan a través del protocolo.

Los servidores SSE remotos tienen el aislamiento adicional de correr en una infraestructura diferente. La comunicación viaja por HTTPS y puede protegerse con tokens de API o con otros mecanismos de autenticación HTTP.

Recomendaciones de seguridad

• Instala solo servidores de fuentes de confianza. Revisa el código fuente o usa paquetes publicados por organizaciones conocidas antes de ejecutar cualquier servidor en tu entorno.
• Usa variables de entorno para las credenciales. Nunca guardes tokens o cadenas de conexión directamente en settings.json si ese archivo va a entrar en el control de versiones. Usa variables de entorno referenciadas desde el JSON.
• Aplica el principio de mínimo privilegio. Configura los tokens con los permisos mínimos necesarios para las operaciones que el agente va a realizar. Un servidor de lectura de base de datos solo necesita permisos de SELECT.
• Usa entornos aislados para servidores de terceros. Si necesitas usar un servidor MCP de un proveedor externo, considera ejecutarlo en un contenedor Docker con acceso limitado a tu red.
• Revisa los logs de sesión. Claude Code registra todas las llamadas a herramientas MCP. Revisa periódicamente el historial para detectar patrones inusuales en sesiones automatizadas.
• Mantén los servidores actualizados. Los servidores MCP de la comunidad reciben actualizaciones de seguridad. Usa versiones fijadas en producción y actualiza con pruebas previas.

MCP y prompt injection

Un riesgo a tener en cuenta cuando el servidor MCP devuelve contenido generado por terceros (resultados de búsqueda, datos de APIs externas, contenido de páginas web) es el prompt injection: datos maliciosos disfrazados de instrucciones para el modelo. Claude Code mitiga este riesgo mediante su arquitectura de permisos, pero conviene ser cauteloso con servidores que exponen contenido no confiable sin sanitizar. La documentación de Anthropic sobre seguridad en Claude Code profundiza en este aspecto.