Cómo añadir un servidor MCP a Claude Code

Añadir un servidor remoto por HTTP

Un servidor remoto es una URL. Claude Code habla HTTP en streaming con él, así que todo el registro cabe en una línea:

claude mcp add --transport http hosttracker https://mcp.host-tracker.com/mcp

El primer argumento tras el transporte es el nombre que verás en /mcp y en los nombres de las herramientas; el segundo es el endpoint. Los servidores que se autentican con OAuth no necesitan nada más en la línea de comandos: la primera vez que abres /mcp, seleccionas el servidor y Claude Code abre el navegador para el inicio de sesión y el paso de consentimiento, y luego guarda el token resultante y lo renueva por su cuenta. Desde Claude Code 2.1.186 también puedes lanzar el inicio de sesión sin la sesión interactiva, con claude mcp login hosttracker, y añadir --no-browser en una máquina sin navegador para obtener una URL que pegar en otro sitio.

Los servidores que esperan un token estático lo reciben en cambio como cabecera:

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Unos pocos servidores antiguos todavía hablan el transporte SSE. Está en desuso a favor de HTTP, y desde Claude Code 2.1.265 --transport http prueba primero con HTTP y recurre a SSE si el servidor lo rechaza, así que rara vez necesitarás ya --transport sse.

Añadir un servidor local

Un servidor local es un programa que Claude Code arranca por ti y con el que habla por la entrada y salida estándar. Coloca su comando y sus argumentos tras un doble guion para que los propios indicadores de Claude Code no se confundan con los del servidor:

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

Las variables de entorno que necesite el servidor se pasan con --env (forma corta -e), repetido una vez por cada variable. Un detalle documentado: el analizador de opciones interpreta lo que siga a --env KEY=value como otro par, así que no pongas el nombre del servidor justo después; coloca otra opción entre medias o pon --env antes de --transport:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Si ya tienes la configuración del servidor en JSON, por ejemplo procedente de su README, claude mcp add-json <name> '<json>' la toma tal cual, incluidos type, command, args y env.

Elegir un ámbito: este proyecto, el equipo o todo el sistema

Por defecto un servidor se añade en el ámbito local, es decir, solo para este proyecto y guardado en tu propio ~/.claude.json. Existen otros dos ámbitos:

• --scope project escribe la entrada en un archivo .mcp.json en la raíz del repositorio. Si lo subes al control de versiones, cada colaborador obtiene el mismo servidor; Claude Code le pide a cada persona que lo apruebe la primera vez.
• --scope user hace que el servidor esté disponible en todos los proyectos de tu máquina, pero siga siendo privado para ti.

Cuando el mismo nombre existe en más de un ámbito, el local gana al de proyecto, y el de proyecto gana al de usuario. Toda la entrada se toma del ámbito ganador; los campos nunca se combinan entre ámbitos. Una división sensata es usar --scope user para servicios ligados a tu propia cuenta, como un servidor de monitorización o de tickets, y --scope project para herramientas que debería compartir todo el equipo.

Comprobar que funciona

Ejecuta claude mcp list fuera de una sesión. Cada servidor muestra uno de estos estados: conectado, necesita autenticación, no se pudo conectar (con el código HTTP o el error añadido desde la versión 2.1.219), pendiente de aprobación para un servidor de proyecto sin aprobar, o desactivado para este proyecto. Dentro de una sesión, /mcp muestra los mismos servidores con su número de herramientas, te deja iniciar el inicio de sesión de uno que lo necesite, borrar su autenticación o desactivarlo para el proyecto actual sin eliminarlo.

Una prueba funcional rápida es una petición que solo el servidor pueda responder. Con el servidor de HostTracker conectado, pregunta "¿cuáles de mis monitores están caídos ahora mismo?" o "ejecuta una comprobación HTTP sobre example.com desde tres ubicaciones"; el asistente debería llamar a una herramienta con el nombre del servidor y citar un resultado que no podría conocer de otro modo. Si no pasa nada, la lista de herramientas suele ser la causa: /mcp muestra cero herramientas para un servidor que se conectó pero falló la autorización.

Eliminar, inspeccionar e importar

claude mcp get <name> muestra la configuración completa y el ámbito de un servidor. claude mcp remove <name> lo elimina junto con cualquier token de OAuth guardado. Si primero configuraste los servidores en Claude Desktop, claude mcp add-from-claude-desktop los importa de forma interactiva; funciona en macOS y en Windows Subsystem for Linux, no en Windows nativo ni en Linux nativo, y se salta un servidor de Desktop cuyo nombre contenga caracteres que Claude Code no permite (solo letras, dígitos, guiones y guiones bajos).

Un servidor de monitorización como primera prueba

Un servicio de monitorización es un buen primer servidor para conectar porque el resultado de una llamada a una herramienta se puede verificar al instante: el asistente dice que un sitio está activo y tú puedes abrirlo. El servidor de HostTracker no necesita instalación local, se autentica con OAuth en el navegador y expone comprobaciones instantáneas desde 300 o más ubicaciones, además de los monitores, incidencias, ventanas de mantenimiento y páginas de estado de tu cuenta, de modo que "¿está activa la producción?" se responde con comprobaciones reales y no con datos de entrenamiento. La guía relacionada sobre la configuración y solución de problemas de .mcp.json cubre el formato del archivo, las variables de entorno y los fallos que aparecen en la práctica.