Integración de Claude Code MCP: Conecta herramientas al agente

Última actualización: June 28, 2026

De fábrica, Claude Code lee y edita archivos y ejecuta comandos shell. No puede leer tus issues de GitHub, consultar tu base de datos ni controlar un navegador. El Model Context Protocol (MCP) cierra esa brecha: es el conector estándar que permite al agente hablar con herramientas y datos externos. Esta guía muestra los comandos exactos claude mcp add, cuándo elegir un servidor local versus remoto, cómo funcionan los scopes, qué servidores merecen la pena conectar, y las comprobaciones de seguridad que debes realizar antes de confiar en uno.

Respuesta rápida: ¿cómo añades un servidor MCP a Claude Code?

Registras un servidor con el comando claude mcp add, y luego Claude Code puede llamar a sus herramientas durante una sesión.

Para un servidor local que se ejecuta como un proceso en tu máquina:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Para un servidor remoto alcanzado a través de HTTPS:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Después de añadir un servidor, ejecuta /mcp dentro de Claude Code para ver su estado de conexión y completar cualquier inicio de sesión OAuth. Usa claude mcp list para confirmar que se ha registrado. La referencia oficial de comandos está en la documentación MCP de Claude Code.

¿Qué es MCP y por qué conectarlo a Claude Code?

MCP es un protocolo abierto, publicado por primera vez por Anthropic, que define cómo un cliente de IA y un servidor de herramientas intercambian capacidades. Un servidor anuncia herramientas (acciones que puede realizar el agente), recursos (datos que puede leer) y prompts. Cualquier cliente consciente de MCP puede usar cualquier servidor MCP, por lo que un servidor GitHub funciona en Claude Code, en un IDE u otro agente sin necesidad de pegamento personalizado. La especificación y el registro de servidores están en modelcontextprotocol.io.

El beneficio práctico: en lugar de pegar el cuerpo de un issue en el chat, conectas el servidor GitHub una vez y pides al agente que lea, etiquete y responda a los issues directamente. Para un fondo más profundo sobre el protocolo en sí, consulta nuestro explicador MCP, y para la guía completa de herramientas en contexto, la guía definitiva de Claude Code.

Un servidor puede ser un pequeño script stdio que escribiste, una imagen Docker o un endpoint SaaS alojado por un proveedor. Claude Code los trata todos de la misma manera una vez que hablan MCP.

¿Qué transporte debes usar: local o remoto?

El transporte es cómo llega Claude Code al servidor. Los servidores locales se ejecutan en tu máquina a través de stdio; los servidores remotos se ejecutan en otro lugar y responden a través de HTTP o SSE. La elección suele seguir dónde residen los datos.

Usa un servidor stdio local cuando la herramienta necesite archivos o servicios en tu portátil, como una carpeta de activos del proyecto o una instancia Postgres en localhost. Usa un servidor HTTP o SSE remoto cuando un proveedor ya lo aloja, porque te saltas la instalación y obtienes actualizaciones sin tocar tu configuración. Los servidores remotos casi siempre te inician sesión a través de OAuth, lo que se activa desde el menú /mcp.

Elegir un scope: local, proyecto o usuario

El Scope decide quién ve el servidor y dónde se almacena la configuración. Claude Code admite tres, y elegir el correcto mantiene los secretos fuera de tu repo mientras sigue compartiendo servidores seguros con el equipo.

Establece el scope con la bandera --scope, por ejemplo claude mcp add --scope project .... El scope de proyecto escribe un .mcp.json versionado, así que nunca pongas un token sin procesar allí; haz referencia a una variable de entorno en su lugar. El scope local es el predeterminado y el lugar más seguro para probar un nuevo servidor antes de comprometerte a compartirlo. Si también creas habilidades de Claude Code, mantén el scope del servidor y el scope de la habilidad consistentes para que un compañero de equipo que extraiga el repo obtenga una configuración funcional.

¿Cómo añadir un servidor con claude mcp add?

El patrón es el mismo para cada servidor: un nombre, una bandera de transporte opcional y el comando o URL. El separador -- marca el inicio del comando local y sus argumentos.

Añade un servidor de sistema de archivos local limitado a una carpeta para que el agente solo pueda tocar lo que permitas:

claude mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem ~/projects/my-app

Pasa los secretos como variables de entorno en lugar de codificarlos directamente:

claude mcp add my-api --env API_KEY=your_key_here -- node ./my-mcp-server.js

Añade un servidor remoto con su transporte y URL:

claude mcp add --transport sse linear https://mcp.linear.app/sse

Luego gestiona lo que tienes:

• claude mcp list muestra cada servidor registrado y su estado.
• claude mcp get <nombre> imprime la configuración de un servidor.
• claude mcp remove <nombre> desregistra el servidor.
• /mcp (escrito en una sesión) muestra el estado de conexión en vivo y ejecuta OAuth.

Mantén el uso de banderas cerca de la documentación oficial; los proveedores cambian ocasionalmente el nombre del paquete o la URL de un servidor, así que copia el valor actual del README propio del servidor en lugar de adivinarlo.

Servidores MCP comunes que merecen la pena conectar

Empieza con un servidor que elimine una tarea real, pruébalo y luego añade más. Estos son los que los desarrolladores buscan primero, y lo que cada uno desbloquea.

El Playwright MCP server es destacado para el trabajo front-end: el agente abre tu página, hace clic a través de un flujo e informa lo que falló con una captura de pantalla. Un servidor de base de datos es útil para preguntas de esquema solo de lectura, pero escópalo a un réplica de solo lectura para que nunca pueda escribir una consulta errante. Cuando empiezas a encadenar varios servidores juntos, dirige el trabajo pesado a un worker dedicado usando subagentes de Claude Code para que la sesión principal permanezca receptiva.

Escenario: conectar un servidor MCP de GitHub para abrir PRs

Supongamos que quieres que el agente clasifique issues y abra pull requests en un repositorio. GitHub aloja un servidor MCP remoto oficial, por lo que no tienes que instalar nada localmente.

1. Registrar el servidor alojado:

   claude mcp add --transport http github https://api.githubcopilot.com/mcp/
   

2. Escribe /mcp en Claude Code, selecciona github y completa el inicio de sesión OAuth en tu navegador. El token se queda con GitHub; nunca lo pegas en un archivo.

3. Confirma las herramientas cargadas con claude mcp list.

4. Ahora pregunta en lenguaje natural:

   • "Lista los issues abiertos etiquetados como bug y resume los tres principales."
   • "Abre un PR borrador de fix/login-redirect a main con una descripción corta."
   • "Lee el PR #214 y marca cualquier cosa que toque la autenticación."

El agente lee hilos de issues, redacta el cuerpo del PR y enlaza el issue correcto, todo sin que tengas que salir de la terminal. Concede acceso a la aplicación GitHub a un único repositorio primero, revisa lo que propone el agente, y amplía el acceso solo cuando confíes en el flujo. La lista completa de herramientas del servidor y la opción de autoalojamiento se documentan en el repo del servidor MCP de GitHub.

¿Es seguro conectar un servidor MCP?

Un servidor MCP puede ejecutar código en tu máquina o actuar sobre tus cuentas, así que trátalo como instalar una dependencia: conecta solo los servidores en los que confíes. El riesgo es real porque un servidor malicioso o con errores podría exfiltrar archivos o realizar acciones destructivas con tus credenciales.

Recorre esta lista de verificación antes de añadir un servidor:

• Confirma la fuente. Prefiere los servidores oficiales del proveedor (GitHub, Sentry) o los servidores de referencia publicados sobre un paquete desconocido.
• Lee qué herramientas expone. Un servidor de "leer mis issues" no debería solicitar acceso de escritura a todo tu disco.
• Escópalos estrechamente. Señala los servidores de sistema de archivos a una carpeta de proyecto y los servidores de bases de datos a un réplica de solo lectura.
• Mantén los secretos fuera de .mcp.json. Usa variables de entorno y nunca commitees un token real.
• Concede el menor privilegio en OAuth. Dale a una aplicación GitHub un repo, no toda tu organización, hasta que confíes en ello.
• Revisa las acciones antes de aprobar. Lee el PR o consulta lo que propone el agente; no apruebes automáticamente escrituras de un servidor nuevo.

Anthropic marca el riesgo de inyección de prompts para servidores que obtienen contenido web no confiable, así que ten especial cuidado con cualquier servidor que extraiga páginas arbitrarias. La guía de seguridad actual está en la documentación MCP de Claude Code.

Solución de problemas de conexiones MCP

La mayoría de los fallos son de configuración o autenticación, no del protocolo. Trabaja con estos en orden:

• Servidor no listado: vuelve a ejecutar claude mcp list. Si falta, es probable que el comando add haya fallado; comprueba si hay un error tipográfico en el separador -- o en el nombre del paquete.

• Estado muestra fallido en /mcp: el proceso no pudo iniciarse. Para servidores stdio, ejecuta el comando sin procesar (por ejemplo la línea npx) en tu terminal para ver el error real.

• Fallo de autenticación: abre /mcp, selecciona el servidor y repite el flujo OAuth. Para servidores basados en tokens, confirma que la variable de entorno está configurada en la shell que lanzó Claude Code.

• Herramientas no aparecen: reinicia la sesión de Claude Code para que recargue las capacidades del servidor, luego verifica que el scope sea uno visible para el proyecto actual.

• Scope incorrecto: un servidor añadido con --scope local no aparecerá para los compañeros de equipo; vuelve a añadirlo con --scope project si debe compartirse.

Cuando un servidor remoto cambia su URL o se renombra un paquete, tu configuración guardada queda obsoleta. Extrae el valor actual del README del servidor y añádelo de nuevo en lugar de editar a ciegas.

Conclusión clave

MCP transforma Claude Code de un agente de archivos y shell a uno que habla con tus herramientas reales. Añade servidores con claude mcp add, elige stdio para datos locales y HTTP/SSE para servicios alojados, y establece el scope por quién debería ver el servidor. Conecta primero un servidor útil; el servidor GitHub es un buen comienzo, y verifica la fuente y los permisos de cada servidor antes de confiar en él. Mantén los tokens en variables de entorno, limita estrechamente el acceso a archivos y bases de datos, y revisa las acciones del agente hasta que un nuevo servidor se lo haya ganado.