Cada resultado de claude mcp add depende de dos decisiones: el ámbito y el transporte. Descubre dónde guarda sus datos cada ámbito (local, de proyecto y de usuario), cuál prevalece cuando los nombres coinciden, cómo registrar servidores HTTP con cabeceras u OAuth y cómo lanzar servidores stdio en Windows.
Pegas la URL de un servidor en claude mcp add, pulsas Enter y el servidor aparece en un proyecto, pero desaparece en el siguiente. O acaba en la copia de trabajo de un compañero y pide una aprobación que nadie esperaba. Casi todos los resultados confusos de este comando se deben a dos decisiones: qué ámbito elegiste y qué transporte usaste. Este artículo repasa el comando flag a flag, muestra dónde guarda sus datos cada ámbito, explica cómo interactúan los ámbitos de usuario y de proyecto y ofrece ejemplos que funcionan para servidores HTTP y stdio, incluida la peculiaridad de Windows que da problemas a mucha gente.
claude mcp add registra un servidor del Model Context Protocol en Claude Code para que el asistente pueda llamar a sus herramientas, leer sus recursos y ejecutar sus prompts. El comando no instala nada por sí solo. Escribe una pequeña entrada de configuración, y Claude Code la lee la próxima vez que se inicie una sesión o cuando vuelvas a conectarte desde el menú /mcp.
Tres decisiones configuran cada llamada:
http, sse o stdio).local, project o user).claude mcp get, claude mcp remove y en el menú /mcp.Dos formas cubren casi todo lo que vas a ejecutar:
# Remote server reached over a URL
claude mcp add [options] <name> <url>
# Local process started by Claude Code
claude mcp add [options] <name> -- <command> [args...]
Coloca --transport, --scope y --env antes del nombre del servidor. En los procesos locales, el doble guion indica al analizador que todo lo que viene después pertenece al servidor y no a Claude Code.
💡 Consejo: incluye
--transportsiempre, aunque un valor por defecto funcionara. Un flag explícito hace que el comando se lea igual en el historial de la terminal, en los archivos README y en el chat del equipo, sea cual sea la versión que use cada persona.
Claude Code guarda cada servidor en uno de tres lugares, y el flag --scope (forma corta -s) elige el lugar. Si omites el flag, obtienes local.
| Ámbito | Se carga en | Compartido con el equipo | Se guarda en |
|---|---|---|---|
local (por defecto) | Solo el proyecto actual | No | ~/.claude.json, bajo la ruta del proyecto |
project | Solo el proyecto actual | Sí, mediante el control de versiones | .mcp.json en la raíz del proyecto |
user | Todos los proyectos de tu equipo | No | ~/.claude.json |
La palabra local confunde a mucha gente porque suena a "en mi equipo", y el ámbito de usuario también está en tu equipo. La diferencia es el alcance. Local es privado y se limita a un proyecto, mientras que el de usuario también es privado, pero te acompaña a todos los repositorios.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Usa el ámbito local para hacer pruebas, para servidores vinculados a un repositorio y para cualquier cosa que lleve una credencial personal. No se escribe nada en el repositorio, así que no hay riesgo de subir un token por accidente. También es el ámbito en el que acabas si olvidas el flag, por eso un servidor añadido a toda prisa parece desaparecer cuando abres otra carpeta.
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp
Esto crea o actualiza .mcp.json en la raíz del proyecto. Si lo confirmas, cada compañero obtiene la misma lista de servidores después de hacer pull. Como un archivo de un repositorio puede iniciar procesos en tu equipo, Claude Code pide a cada persona que apruebe los servidores del proyecto la primera vez que aparecen. Si alguien rechazó por error, claude mcp reset-project-choices borra las respuestas anteriores para que vuelva a aparecer la solicitud.
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp
El ámbito de usuario es ideal para herramientas personales que quieres en todos los repositorios: una app de notas, un servidor de búsqueda de documentación, un asistente para el navegador. La entrada vive en ~/.claude.json, viaja con tu cuenta en ese equipo y nunca toca un repositorio.
La elección entre el ámbito de usuario y el de proyecto se reduce a una pregunta: ¿quién más necesita este servidor? Si la respuesta es "todos los que clonen este repositorio", usa proyecto. Si la respuesta es "solo yo, pero en todos los repositorios", usa usuario. Si la respuesta es "solo yo, solo aquí", quédate con local.
| Situación | Mejor ámbito | Por qué |
|---|---|---|
| Todo el equipo necesita el mismo servidor | project | Una .mcp.json confirmada sustituye una página de la wiki con los pasos de configuración |
| Un asistente personal para todos tus repositorios | user | Lo añades una vez y te sigue a todas partes |
| Probar un servidor durante una tarde | local | Nada se filtra al repositorio, y eliminarlo es trivial |
| Apuntar un servidor del equipo a una URL de staging | local | Solo anula la definición compartida en tu equipo |
| Un servidor que necesita tu propio token | local o user | Las credenciales personales nunca deben ir en un archivo confirmado |
Cuando el mismo nombre de servidor existe en más de un ámbito, Claude Code usa la definición más específica: local gana a proyecto, y proyecto gana a usuario. Ese orden te permite anular una entrada compartida en tu propio equipo sin editar un archivo que usan todos los demás.
Supón que el .mcp.json del equipo define un servidor llamado docs que apunta a producción. Puedes ejecutar esto en tu copia de trabajo:
claude mcp add --transport http docs https://staging.example.com/mcp
La entrada local gana, así que tu sesión habla con staging mientras tus compañeros siguen hablando con producción. Si eliminas la entrada local, vuelves a la compartida.
Una entrada de ámbito de proyecto es JSON simple, así que también puedes escribirla a mano:
{
"mcpServers": {
"docs": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${DOCS_TOKEN}"
}
}
}
}
Claude Code expande ${VAR} y ${VAR:-default} dentro de command, args, url, headers y env. Es el patrón seguro para los archivos compartidos: confirma la estructura y deja que cada persona aporte su propio secreto mediante una variable de entorno. Un token real pegado en .mcp.json acaba en el historial de git, y rotarlo es la única solución fiable.
HTTP es el transporte recomendado para los servidores remotos: no hay proceso local, no hay que instalar ningún entorno de ejecución y el proveedor se encarga de las actualizaciones. La mayoría de los servidores MCP alojados publican una URL que termina en /mcp, y esa es la dirección que pasas al comando.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
| Transporte | Mejor para | Estado |
|---|---|---|
http | Servidores remotos a los que se accede mediante una URL | Recomendado |
sse | Servidores remotos antiguos con un endpoint /sse | Obsoleto, usa http cuando el proveedor lo ofrezca |
stdio | Procesos locales iniciados en tu equipo | Totalmente compatible |
Si la documentación de un proveedor todavía muestra una dirección /sse, comprueba si el mismo servicio ofrece un endpoint /mcp antes de registrar la versión antigua. Los servidores con el transporte obsoleto siguen funcionando por ahora, pero las configuraciones nuevas no deberían empezar por ahí.
Los servidores que aceptan una credencial estática la leen de una cabecera de la petición. Pásala con --header (forma corta -H) y repite el flag si necesitas más de una:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_TOKEN"
claude mcp add --transport http api https://example.com/mcp \
--header "Authorization: Bearer YOUR_TOKEN" \
--header "X-Team: platform"
💡 Cuidado con el shell: si escribes
$GITHUB_TOKENentre comillas dobles, el shell lo expande antes de que Claude Code vea el comando, así que la entrada guardada contiene el token real. En cualquier configuración compartida, escribe mejor la forma${VAR}en.mcp.json.
Muchos servidores alojados prescinden de los tokens estáticos y usan OAuth. Añade el servidor sin cabeceras, inicia Claude Code y ejecuta /mcp. Elige el servidor de la lista y sigue el inicio de sesión en el navegador. Claude Code guarda las credenciales resultantes y las renueva por ti, así que no hay nada que pegar en un archivo de configuración ni nada que subir por error.
Con stdio, Claude Code inicia el servidor como proceso hijo y se comunica con él a través de la entrada y salida estándar. Elige este transporte para herramientas que deben ejecutarse en tu equipo: un asistente de base de datos local, una herramienta de sistema de archivos o un script que hayas escrito tú. Las variables de entorno viajan con el flag --env (forma corta -e).
claude mcp add --transport stdio --env API_TOKEN=YOUR_TOKEN myserver \
-- npx -y my-mcp-server
Todo lo que va antes de -- es para Claude Code. Todo lo que va después es el comando exacto que inicia tu servidor, con sus argumentos. Olvidar el separador es el error más común con stdio:
# Wrong: --port is parsed as a Claude Code option
claude mcp add --transport stdio myserver npx server --port 8080
# Right: the server command sits after the double dash
claude mcp add --transport stdio myserver -- npx server --port 8080
En Windows nativo (no WSL), npx es un envoltorio por lotes y no un ejecutable real, así que Claude Code no puede lanzarlo directamente. Envuelve el comando en cmd /c:
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
Sin el envoltorio, normalmente verás un error "Connection closed" en /mcp, que parece un fallo del servidor pero solo es un fallo al iniciarlo. La misma solución se aplica cuando escribes la entrada a mano: define "command": "cmd" y empieza args con "/c", seguido de "npx".
Registrar un servidor es solo la mitad del trabajo. Tres comandos se encargan del resto de su vida:
claude mcp list # every server and its connection status
claude mcp get docs # details for one server
claude mcp remove docs # delete it
Dentro de una sesión, /mcp muestra el mismo estado en tiempo real y es también el lugar donde inicias sesión en los servidores OAuth o reconectas uno que se haya caído.
Ejecuta claude mcp list primero siempre que algo no cuadre. Muestra lo que Claude Code conoce realmente, de todos los ámbitos, para que veas de inmediato si el servidor falta o simplemente falla. Usa claude mcp get <name> para ver de dónde procede una entrada. Si el mismo nombre existe en más de un ámbito, pasa --scope a claude mcp remove para eliminar la copia correcta.
Cuando un proveedor te entrega un fragmento JSON, omite los flags y pásaselo directamente al comando:
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
add-json acepta el mismo flag --scope, así que puedes colocar un fragmento en el ámbito de usuario o de proyecto en un solo paso. Si ya creaste un conjunto de servidores en Claude Desktop, claude mcp add-from-claude-desktop los importa de forma interactiva en macOS y WSL.
La mayoría de los fallos encajan en una lista corta. Identifica primero el síntoma y solo entonces empieza a editar archivos.
| Síntoma | Causa probable | Solución |
|---|---|---|
| El servidor no aparece en otra carpeta | Añadido en ámbito local | Vuelve a añadirlo con --scope user |
| Los compañeros no ven el servidor | Añadido en ámbito local o de usuario | Vuelve a añadirlo con --scope project y confirma .mcp.json |
| "Connection closed" en Windows | npx se lanzó sin envoltorio | Usa -- cmd /c npx ... |
| Los flags del servidor se rechazan | Falta -- antes del comando | Coloca el doble guion después del nombre |
| El servidor del proyecto nunca se carga | Aprobación rechazada antes | Ejecuta claude mcp reset-project-choices |
| Un servidor lento agota el tiempo al arrancar | Límite de inicio demasiado corto | Inicia Claude Code con MCP_TIMEOUT=30000 |
| La salida de la herramienta se corta | Se alcanzó el límite de tokens de salida | Sube MAX_MCP_OUTPUT_TOKENS |
| Un token está en un archivo confirmado | Secreto literal en .mcp.json | Rótalo y luego cambia a ${VAR} |
Cuando la tabla no resuelve el problema, haz estas cuatro comprobaciones en orden:
claude mcp list para confirmar que el servidor está registrado y ver su estado.claude mcp get <name> para leer el comando o la URL exactos que usa Claude Code./mcp dentro de una sesión para ver el estado de la conexión en tiempo real y reconectar.Cuando un servidor no se conecta: en un servidor remoto, abre la URL en un navegador o llámala con curl. Un 401 o un 403 significa que la cabecera o el inicio de sesión están mal, un 404 suele indicar que la ruta es incorrecta (/mcp frente a /sse) y un tiempo de espera apunta a la red. En un servidor stdio, el comando exacto que registraste debe funcionar por sí solo con las mismas variables de entorno definidas.
Una vez resueltos los ámbitos, MCP se convierte en una forma de dar a Claude capacidades reales, y las imágenes son un buen ejemplo. PicassoIA expone sus modelos de generación mediante una API para desarrolladores en https://api.picassoia.com/v1 y a través de conexiones MCP. Los cuatro modelos de esa superficie son PicassoIA Image, PicassoIA Image Editor Pro y dos modelos de video. Los trabajos se ejecutan de forma asíncrona: Claude envía una predicción, consulta su estado y después lee el resultado final. La plataforma permite 5 predicciones simultáneas por cuenta, compartidas entre todas las conexiones que tengas abiertas, así que un lote de peticiones desde una misma sesión se pondrá en cola en lugar de ejecutarse todo a la vez.
💡 Consejo sobre el ámbito: la página de precios indica que las conexiones MCP están disponibles en los planes Pro+, Elite e Infinite, así que confirma tu plan antes de configurarlo. Registra la conexión en el ámbito de usuario si quieres generación de imágenes en todos los repositorios, o en el ámbito local si solo la necesita un proyecto. Copia la URL de conexión desde tu cuenta de PicassoIA en lugar de adivinar una dirección.
No necesitas una terminal para pedir ayuda con un comando claude mcp add que falla. Claude Sonnet 5 funciona en PicassoIA y se da muy bien con este tipo de depuración:
/mcp o de la terminal.claude mcp list.Para razonamientos más complejos sobre un .mcp.json grande, Claude Opus 4.7 está disponible en la misma plataforma, y Claude 4.5 Haiku responde rápido a las dudas de sintaxis sencillas.
Leer sobre ámbitos es útil, pero la verdadera recompensa llega cuando Claude trabaja con imágenes mientras programas. Abre Picasso IA, elige un modelo como PicassoIA Image y genera unas cuantas imágenes con tus propios prompts. Prueba con una imagen de cabecera para tu próximo README, una maqueta de producto o una escena de estilo fotográfico para una entrada de blog. Cuando te gusten los resultados, conecta esa misma capacidad a Claude Code mediante MCP y deja que el asistente produzca imágenes dentro de tu flujo de trabajo. Experimenta con libertad, compara modelos lado a lado y guarda los prompts que funcionan.
Elige tu idioma
