Añade un servidor MCP a Claude Code en la terminal o en VS Code. Sigue los comandos exactos para servidores HTTP remotos y stdio locales, los tres ámbitos, el inicio de sesión con OAuth, un ejemplo de imagen y video de PicassoIA y las soluciones para cualquier servidor que no se conecte.
Claude Code puede leer tus archivos y ejecutar comandos de shell de serie, pero no puede ver tu gestor de incidencias, tu base de datos ni tu generador de imágenes hasta que los conectes. Esa conexión es un servidor MCP. MCP, abreviatura de Model Context Protocol, es el estándar abierto que permite a Claude Code llamar a servicios externos como si estuvieran integrados. Añadir uno requiere un solo comando, y después el mismo servidor aparece en la terminal y en la extensión de VS Code.
Este artículo muestra los comandos exactos, los tres ámbitos que determinan quién tiene acceso a un servidor, los detalles de OAuth y de tokens con los que más se tropieza y un ejemplo real con la conexión de imagen y video de PicassoIA. Los comandos y las opciones que aparecen abajo se comprobaron con la documentación actual de Claude Code el 6 de octubre de 2026, así que coinciden con lo que verás en tu propia terminal.
💡 La versión corta: para un servidor alojado ejecuta
claude mcp add --transport http <name> <url>. Para uno local ejecutaclaude mcp add --transport stdio <name> -- <command>. Después escribe/mcpdentro de Claude Code y confirma que el servidor aparece como Connected.
Necesitas Claude Code. Para la ruta de VS Code también necesitas VS Code 1.94.0 o posterior con la extensión de Claude Code. Comprueba la versión de la CLI con claude --version, porque algunas funciones dependen de ella:
/mcp reconnect all requiere v2.1.284 o posteriorUna instalación antigua es lo primero que hay que descartar cuando un paso de abajo no hace nada. También necesitas los datos del servidor, y dependen de dónde se ejecute. Un servidor remoto te da una URL y, además, un token o un inicio de sesión en el navegador. Un servidor local te da un comando que lo lanza, normalmente mediante npx, así que Node.js tiene que estar instalado.
La opción --transport indica a Claude Code cómo comunicarse con el servidor. Hay tres opciones.
| Transporte | Dónde se ejecuta el servidor | Úsalo cuando | Estado |
|---|---|---|---|
http | URL remota | Un servicio alojado te da una URL | La opción actual para servidores alojados |
sse | URL remota | El proveedor solo publica un endpoint /sse | Obsoleto |
stdio | Tu equipo | El servidor es un programa que Claude Code lanza | Estándar para herramientas locales |
Una regla rápida: una URL que termina en /mcp es HTTP, una URL que termina en /sse es el transporte SSE anterior (comprueba si el proveedor ya ofrece una URL HTTP), y un comando npx es stdio.
La CLI es la vía más rápida, y todo lo que haces aquí es también lo que lee la extensión de VS Code. Abre una terminal en la carpeta de tu proyecto o en cualquier carpeta si vas a usar el ámbito de usuario que se describe más adelante.
El patrón es claude mcp add --transport http <name> <url>. Este es un servidor alojado real:
claude mcp add --transport http notion https://mcp.notion.com/mcp
La palabra notion es el nombre que eliges. Aparece en los nombres de las herramientas como mcp__notion__<tool>, así que conviene que sea corto y en minúsculas. Cuando el servidor pida un token, pásalo como encabezado:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
💡 Ojo:
claude mcp addguarda la configuración sin comprobar tus credenciales. Se acepta un token de marcador de posición, y el fallo solo aparece más tarde, cuando el servidor intenta conectarse.
Un servidor stdio es un programa en tu propio equipo que Claude Code inicia y con el que se comunica a través de la entrada y salida estándar. El patrón es claude mcp add [options] <name> -- <command> [args...]:
claude mcp add --transport stdio files -- npx -y @modelcontextprotocol/server-filesystem ~/projects
El doble guion es obligatorio. Todo lo que va después se pasa al servidor sin tocar, y cada opción de Claude Code (--env, --scope, --transport) tiene que ir antes del nombre. Para pasar una variable de entorno al proceso del servidor, usa --env:
claude mcp add --transport stdio --env MY_SERVICE_TOKEN=paste-here myservice -- npx -y your-server-package
Sustituye your-server-package por el paquete que documente el proveedor. En Windows nativo (no WSL), npx suele necesitar un envoltorio para que el shell pueda lanzarlo:
claude mcp add --transport stdio files -- cmd /c npx -y @modelcontextprotocol/server-filesystem C:\Users\you\projects
Tres comandos cubren la gestión del día a día:
claude mcp list
claude mcp get files
claude mcp remove files
list muestra todos los servidores configurados, get muestra los detalles de un servidor y remove lo elimina. Si ya tienes la definición de un servidor en JSON, claude mcp add-json <name> '<json>' te ahorra traducirla a opciones. Dentro de una sesión de Claude Code, /mcp muestra el estado en tiempo real y gestiona el inicio de sesión.
La extensión de Claude Code y la CLI comparten una misma configuración de MCP, así que hay dos rutas y ninguna te ata a una.
/mcp en el cuadro de chat./mcp otra vez y comprueba que el servidor aparece como Connected.El paso 5 es importante. Los cambios se aplican a las conversaciones que inicies después, así que un chat que ya estaba abierto no verá el nuevo servidor.
Abre la terminal integrada con Ctrl+` (o Cmd+` en Mac) y ejecuta el mismo comando claude mcp add que usarías en cualquier otro sitio. El diálogo y el comando de terminal guardan en la misma configuración. Este es el servidor remoto de GitHub con un token de acceso personal:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
Un servidor con credenciales incorrectas aparece como Failed en /mcp, mientras que uno que funciona aparece como Connected.
💡 Dos archivos de configuración, dos productos: VS Code tiene su propio soporte de MCP con un archivo en
.vscode/mcp.json. Ese archivo pertenece al chat integrado de VS Code y usa un formato distinto. Claude Code mantiene su propia configuración, así que un servidor declarado solo en.vscode/mcp.jsonno aparecerá en la lista/mcpde Claude Code.
Es posible que también oigas hablar de un servidor llamado ide. La extensión lo ejecuta automáticamente para abrir diferencias y leer tu selección, y no aparece en /mcp porque no hay nada que configurar.
El ámbito decide quién ve el servidor y dónde se guarda. Elígelo con --scope (forma corta -s).
| Ámbito | Se carga en | Compartido con el equipo | Se guarda en |
|---|---|---|---|
| local (predeterminado) | Solo el proyecto actual | No | ~/.claude.json |
| project | Solo el proyecto actual | Sí, a través del repositorio | .mcp.json en la raíz del proyecto |
| user | Todos los proyectos de tu equipo | No | ~/.claude.json |
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
Mi regla práctica: usa local para pruebas y para cualquier servidor con un token personal, project para las herramientas que necesita todo el equipo y user para el puñado de servidores que quieras tener en todos los repositorios.
Un servidor de ámbito de proyecto vive en un archivo .mcp.json en la raíz del repositorio, que tú confirmas en el control de versiones. Admite la expansión de variables de entorno, así que el archivo nunca tiene que contener un secreto:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
}
${VAR} se expande a la variable de entorno, y ${VAR:-default} usa un valor predeterminado cuando la variable no está definida. Cada miembro del equipo define API_TOKEN en su propio equipo.
Los miembros del equipo ven un aviso de aprobación antes de que Claude Code use un servidor de .mcp.json en una sesión interactiva. Para restablecer esas decisiones, ejecuta claude mcp reset-project-choices. Las ejecuciones no interactivas, como claude -p, cargan los servidores del proyecto sin pedir confirmación, algo que conviene recordar en los trabajos de CI.
Un servidor puede autenticarse de tres maneras, y la adecuada depende de lo que admita el proveedor.
| Método | Ideal para | Cómo |
|---|---|---|
| Token en encabezado | Servidores que emiten un token personal | --header "Authorization: Bearer ..." |
| Variable de entorno | Servidores stdio locales | --env NAME=value |
| OAuth | Servidores alojados con inicio de sesión en el navegador | /mcp, o claude mcp login <name> |
Para OAuth, abre /mcp, selecciona el servidor y sigue el inicio de sesión en el navegador. Desde la línea de comandos, claude mcp login <name> hace lo mismo, y claude mcp login <name> --no-browser muestra lo que necesitas en un equipo con SSH o sin pantalla. Para borrar las credenciales guardadas, ejecuta claude mcp logout <name>. Algunos servidores necesitan credenciales registradas previamente, que pasas con --client-id, --client-secret y --callback-port al añadir el servidor.
Dos hábitos evitan la mayoría de las filtraciones. Primero, nunca confirmes un token literal. Pon ${VAR} en .mcp.json y guarda el valor real en el entorno de tu shell. Segundo, mantén los servidores que llevan un token personal en el ámbito local o de usuario, donde el archivo queda fuera del repositorio.
Un servidor concreto hace que todo esto sea menos abstracto. PicassoIA ofrece una conexión MCP que permite a un cliente de IA crear imágenes y videos desde un chat. Expone cuatro modelos: PicassoIA Image para texto a imagen, PicassoIA Image Editor Pro para ediciones, PicassoIA Video para clips a partir de texto o de una imagen, y Seedance 2.5 Lite para video con audio.
Las herramientas se basan en trabajos asíncronos. Una llamada de generación devuelve un ID de predicción en cuanto una GPU acepta el trabajo, y el cliente consulta después get_generation hasta que el estado sea succeeded o failed. Otras herramientas son edit_image, list_generations, cancel_generation, list_models y get_account. Una cuenta puede ejecutar 5 predicciones a la vez, y ese límite se comparte entre todas sus conexiones MCP. El acceso a MCP depende de tu plan, así que confírmalo en la página de precios de PicassoIA antes de depender de él.
claude mcp add --transport http picassoia YOUR_PICASSOIA_MCP_URL
/mcp y selecciona picassoia. Si te pide iniciar sesión, sigue el flujo en el navegador. Si tu página de conexiones te dio un token en lugar de eso, añade --header "Authorization: Bearer YOUR_TOKEN" al comando.No muestro una URL aquí a propósito. PicassoIA te muestra la tuya después de iniciar sesión, así que usa la exacta de tu cuenta y no una copia de un artículo.
Como has llamado al servidor picassoia, sus herramientas aparecen como mcp__picassoia__<tool>. Prueba algo que use dos de ellas:
Usa PicassoIA para generar una fotografía en 16:9 de un escritorio de madera al amanecer con un equipo portátil y una taza de café, y luego anímala en un video corto.
Claude Code pide permiso antes de llamar a una herramienta nueva, así que espera un aviso la primera vez. Si además quieres comparar cómo leen la misma instrucción distintos modelos de lenguaje, PicassoIA incluye entre sus modelos de lenguaje a Claude Sonnet 5 y Claude Fable 5.
La mayoría de los fallos se deben a una lista corta de causas. Empieza con /mcp para leer el estado y luego usa claude mcp get <name> para ver exactamente lo que se guardó.
| Síntoma | Causa probable | Solución |
|---|---|---|
| El servidor muestra Failed | URL incorrecta o token no válido | Compruébalo con claude mcp get <name> y después elimínalo y vuelve a añadirlo con los valores correctos |
| Servidor ausente en VS Code | La conversación empezó antes de añadirlo | Inicia una nueva conversación |
| El servidor stdio se cierra al momento en Windows | npx necesita un envoltorio de shell | Usa -- cmd /c npx ... |
| Servidor conectado pero sin herramientas | El inicio de sesión con OAuth no se terminó | /mcp y luego autentica, o claude mcp login <name> |
| El servidor del proyecto nunca se carga | Se rechazó la aprobación | Ejecuta claude mcp reset-project-choices y aprueba de nuevo |
| Funciona para ti, no para un compañero | Se guardó en el ámbito local | Vuelve a añadirlo con --scope project |
| El servidor se cayó a mitad de sesión | Conexión perdida | Ejecuta /mcp reconnect all (v2.1.284 o posterior) |
Tres ajustes controlan los servidores lentos. MCP_TIMEOUT define el tiempo de espera de arranque del servidor en milisegundos, lo que ayuda cuando la descarga inicial de npx es lenta:
export MCP_TIMEOUT=10000
En PowerShell de Windows lo mismo es $env:MCP_TIMEOUT = "10000". MAX_MCP_OUTPUT_TOKENS sube el límite de la salida de las herramientas. El valor predeterminado es de 25.000 tokens, y Claude Code te avisa a partir de 10.000. Por último, un timeout por servidor en .mcp.json (también en milisegundos) da más margen a las herramientas lentas, lo que resulta útil con los generadores de imagen y video:
{
"mcpServers": {
"slow-tool": {
"type": "http",
"url": "https://example.com/mcp",
"timeout": 600000
}
}
}
Ya tienes el ciclo completo: elegir un transporte, añadir el servidor, elegir un ámbito, iniciar sesión de forma segura y arreglarlo cuando falle. La forma más rápida de notar el beneficio es conectar un servidor que produzca algo que puedas ver.
Inicia sesión en PicassoIA, conéctalo a Claude Code y pide una fotografía. Genérala con PicassoIA Image, refínala con PicassoIA Image Editor Pro y luego dale vida con PicassoIA Video o Seedance 2.5 Lite. Explora todos los modelos en picassoia.com/en/all-models y empieza con un prompt propio.
Elige tu idioma
