Cómo instalar MCP en Claude Code, Copilot, OpenCode, Codex, Gemini

¿Qué es un MCP server? ¶

MCP (Model Context Protocol) es un estándar abierto creado por Anthropic en noviembre de 2024 que define cómo los modelos de IA se conectan con herramientas externas, bases de datos y APIs. Piensa en MCP como un puerto USB-C para agentes de IA: un conector universal que permite que cualquier agente compatible se comunique con cualquier servicio que implemente el protocolo, sin integraciones a medida para cada combinación. MCP es uno de los protocolos clave del ecosistema de IA generativa, junto con A2A, ACP y otros estándares que están definiendo cómo interactúan los agentes con nuestras herramientas.

¿Quieres aprender a montar un MCP? Tutorial: Crea un MCP desde cero con todo el código

Un MCP server es un programa ligero que expone capacidades específicas (herramientas, recursos, prompts) a través de este protocolo estandarizado. Puede ejecutarse localmente en tu máquina (transporte stdio) o estar alojado en un servidor remoto al que te conectas por HTTP. Los servidores remotos son, además, los que más han cambiado: el protocolo eliminó las sesiones de su núcleo para que escalen como cualquier otra API. En diciembre de 2025, Anthropic donó MCP a la Agentic AI Foundation bajo la Linux Foundation, consolidándolo como estándar de la industria con soporte de OpenAI, Google, Microsoft y otros.

La adopción ha sido masiva: a día de hoy hay más de 97 millones de descargas mensuales de los SDKs y más de 10.000 servidores activos. El ecosistema cubre desde acceso a sistemas de archivos y bases de datos hasta integraciones con GitHub, Slack, Notion, Figma y cientos de servicios más. Y con la llegada de WebMCP, el protocolo que lleva MCP al navegador, las posibilidades se amplían al frontend. Si antes de configurar MCP quieres decidir qué herramienta usar, echa un vistazo a nuestra comparativa de las mejores herramientas de IA para programar con precios y recomendaciones para cada perfil de developer. Y si lo que buscas es darle a tu agente contexto del navegador y del servidor en una sola línea de tiempo, dev3000 actúa como un MCP gateway local que orquesta varios MCPs por debajo. Esta guía te muestra cómo configurar dos MCP servers de ejemplo en los 16 agentes de IA más populares.

Los dos MCP de ejemplo ¶

Cada herramienta tiene su propio formato. Si quieres ver una comparativa detallada de los agentes de IA para programación, tenemos un análisis completo. Aquí tienes las instrucciones exactas para añadir Context7 (remoto, sin API key) y Sequential Thinking (local, vía npx) en los 16 agentes de IA más populares.

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter

Context7 — Documentación actualizada de librerías inyectada en tu prompt. Servidor remoto en https://mcp.context7.com/mcp. No necesita API key.

Sequential Thinking — Razonamiento paso a paso para problemas complejos. Se ejecuta localmente con npx -y @modelcontextprotocol/server-sequential-thinking. Necesitas Node.js instalado.

Instalar un MCP en Claude Code ¶

Fichero de configuración: ~/.claude.json (scopes local y user) o .mcp.json en la raíz del proyecto (scope project, el que se commitea y comparte el equipo).

Vía comando ¶

# Context7 (remoto)
claude mcp add --transport http context7 https://mcp.context7.com/mcp

# Sequential Thinking (local)
claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

Añade --scope user para que esté disponible en todos tus proyectos.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

📖 Fuente: Anthropic Docs — Claude Code MCP

Si quieres sacarle más partido a Claude Code más allá de MCP, consulta nuestros 60 trucos para dominar Claude Code con configuración, flujos de trabajo y técnicas avanzadas.

Domina la herramienta a fondo

Instalar MCP es solo el principio: esta masterclass cose hooks, agentes, MCP y workflows en directo

Verás CLAUDE.md, hooks, agentes y MCP (Sequential Thinking, Context7, GitHub) cableados con criterio, más workflows EPCC / TDD / visual / worktrees que la documentación oficial no termina de explicar.

Entrar a la masterclass →

Masterclass en directo · 2h30 · Acceso con Web Reactiva Premium · 15€/mes

Instalar un MCP en Codex (OpenAI) ¶

Fichero de configuración: ~/.codex/config.toml (global) o .codex/config.toml en la raíz del proyecto. Los servidores van en una tabla [mcp_servers.<nombre>].

Vía comando ¶

# Context7 (remoto)
codex mcp add context7 -- npx -y @upstash/context7-mcp

# Sequential Thinking (local)
codex mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

Vía fichero de configuración ¶

Codex es el único que usa TOML en vez de JSON.

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

Nota: Codex también soporta url para servidores HTTP remotos directos (ej: url = "https://mcp.context7.com/mcp"), pero la vía npx funciona sin problemas.

📖 Fuente: OpenAI Docs — Codex MCP Servers

Instalar un MCP en Gemini CLI ¶

Fichero de configuración: ~/.gemini/settings.json (global) o .gemini/settings.json (proyecto).

Vía comando ¶

# Context7 (remoto)
gemini mcp add --name context7 --transport http --url https://mcp.context7.com/mcp

# Sequential Thinking (local)
gemini mcp add --name sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "httpUrl": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Ojo: Gemini usa httpUrl para servidores remotos HTTP (no url). Usa /mcp dentro de Gemini CLI para verificar el estado de los servidores.

📖 Fuente: Google — Gemini CLI MCP

Instalar un MCP en Qwen Code ¶

Fichero de configuración: ~/.qwen/settings.json (global) o .qwen/settings.json (proyecto).

Vía comando ¶

# Context7 (remoto)
qwen mcp add --transport http context7 https://mcp.context7.com/mcp

# Sequential Thinking (local)
qwen mcp add sequential-thinking npx -y @modelcontextprotocol/server-sequential-thinking

Escribe en el scope de usuario (~/.qwen/settings.json) salvo que añadas --scope project.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Nota: Qwen Code es un fork de Gemini CLI y hereda su estructura, incluido el httpUrl para endpoints de streamable HTTP (deja url para los SSE). Prueba con /mcp para verificar el estado.

📖 Fuente: Qwen Code Docs — Connect Qwen Code to tools via MCP

Instalar un MCP en OpenCode (SST) ¶

Fichero de configuración: opencode.json (proyecto) o ~/.config/opencode/opencode.json (global).

Vía comando ¶

# Context7 (remoto)
opencode mcp add context7

# Sequential Thinking (local)
opencode mcp add sequential-thinking

El comando opencode mcp add inicia un asistente interactivo que te guía para configurar el tipo (local/remote), el command o la URL. No acepta todos los parámetros inline como Claude Code o Codex.

Vía fichero de configuración ¶

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "sequential-thinking": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"],
      "enabled": true
    }
  }
}

Cuidado: OpenCode cambia toda la nomenclatura respecto al resto. La clave raíz es mcp (no mcpServers). Los tipos son remote/local (no http/stdio). Y command es un array con todos los argumentos juntos (no se separan en command + args).

📖 Fuente: OpenCode Docs — MCP

Instalar un MCP en GitHub Copilot (VS Code) ¶

Fichero de configuración: .vscode/mcp.json (proyecto) o el mcp.json de tu perfil de usuario, que en macOS vive en ~/Library/Application Support/Code/User/mcp.json. Para abrirlo sin buscarlo: MCP: Open User Configuration en la paleta de comandos.

Vía comando ¶

Copilot no tiene un CLI propio para gestionar MCP. Se configura de dos formas desde VS Code:

1. Interfaz gráfica: Abre Copilot Chat → icono de herramientas → botón + → rellenas el formulario.
2. Command Palette: Ctrl+Shift+P → MCP: Add Server → sigue el asistente.

Vía fichero de configuración ¶

{
  "servers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Ojo: La clave raíz en .vscode/mcp.json es servers (no mcpServers). Necesitas VS Code 1.99+ y el modo Agent activado en Copilot Chat.

📖 Fuente: VS Code Docs — Copilot MCP Servers

Instalar un MCP en Amp (Sourcegraph) ¶

Fichero de configuración: ~/.config/amp/settings.json en macOS y Linux, %USERPROFILE%\.config\amp\settings.json en Windows. También acepta la variante settings.jsonc.

Vía comando ¶

# Context7 (remoto)
amp mcp add context7 https://mcp.context7.com/mcp

# Sequential Thinking (local)
amp mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking

Vía fichero de configuración ¶

{
  "amp.mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Ojo: La clave raíz es amp.mcpServers (con prefijo amp.). Amp recomienda agrupar servidores MCP dentro de Skills para reducir la carga de contexto.

📖 Fuente: Amp Manual — Core Settings (MCP)

Instalar un MCP en Cline (VS Code) ¶

Fichero de configuración: ~/.cline/mcp.json si usas el CLI. Con la extensión de VS Code el fichero es cline_mcp_settings.json, dentro del almacenamiento global de la extensión:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Vía comando ¶

El CLI de Cline trae un asistente que cubre todo el ciclo:

cline mcp
# → List servers / Add server / Edit server / Enable-Disable / Delete server

Desde la extensión: panel de Cline → icono MCP Servers (🔌) → pestaña Configure → botón Configure MCP Servers, que abre el JSON.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Nota: Cline soporta transporte stdio, SSE y Streamable HTTP. Puedes añadir "alwaysAllow": ["resolve", "searchLibraries"] para aprobar automáticamente ciertas herramientas.

📖 Fuente: Cline Docs — Configuring MCP Servers

Instalar un MCP en Continue (VS Code / JetBrains) ¶

Fichero de configuración: .continue/mcpServers/ en la raíz del proyecto, con un YAML por servidor. Para tenerlo siempre activo en tu máquina, un bloque mcpServers en ~/.continue/config.yaml.

Vía comando ¶

Continue no tiene CLI dedicado para MCP. Se configura editando ficheros YAML o importando configuraciones JSON de otros agentes.

Vía fichero de configuración ¶

Crea un archivo por servidor en .continue/mcpServers/. Por ejemplo, .continue/mcpServers/context7.yaml:

name: Context7
version: 0.0.1
schema: v1
mcpServers:
  - name: context7
    url: https://mcp.context7.com/mcp

Y .continue/mcpServers/sequential-thinking.yaml:

name: Sequential Thinking
version: 0.0.1
schema: v1
mcpServers:
  - name: sequential-thinking
    command: npx
    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]

Truco: Continue puede importar directamente ficheros JSON de Claude Code, Cursor o Cline si los dejas en .continue/mcpServers/. Soporta stdio, SSE y streamable-http.

📖 Fuente: Continue Docs — MCP Deep Dive

Instalar un MCP en Cursor ¶

Fichero de configuración: ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto).

Vía comando ¶

Cursor no tiene CLI para gestionar MCP. Se configura de dos formas:

1. Interfaz gráfica: Settings → MCP Settings → Add new MCP server.
2. Command Palette: Ctrl+Shift+P → MCP: Add Server.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Nota: Cursor usa el formato estándar mcpServers. Para HTTP remoto basta con url; para stdio, command + args.

📖 Fuente: Cursor Docs — Model Context Protocol

Instalar un MCP en Goose (Block) ¶

Fichero de configuración: ~/.config/goose/config.yaml (macOS/Linux) o %APPDATA%\Block\goose\config\config.yaml (Windows).

Vía comando ¶

# Abre el asistente interactivo de configuración
goose configure
# → Selecciona "Add Extension" → "Command-line Extension"
# → Introduce el nombre y comando del servidor

No acepta parámetros inline directamente. El comando goose configure lanza un asistente paso a paso.

Vía fichero de configuración ¶

Goose usa YAML con una estructura propia basada en extensions:

extensions:
  context7:
    type: stdio
    cmd: npx
    args:
      - "-y"
      - "@upstash/context7-mcp@latest"
    enabled: true
  sequential-thinking:
    type: stdio
    cmd: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-sequential-thinking"
    enabled: true

Cuidado: Goose no usa mcpServers sino extensions. Los campos son cmd (no command) y el type puede ser stdio, sse o streamable-http. Para Context7 remoto vía HTTP, usa type: sse o type: streamable-http con la URL correspondiente.

📖 Fuente: Goose Docs — Using Extensions

Instalar un MCP en Junie (JetBrains) ¶

Fichero de configuración: ~/.junie/mcp/mcp.json (global) o .junie/mcp/mcp.json (proyecto).

Vía comando ¶

Dentro de una sesión de Junie, usa el comando /mcp para abrir el MCP Installation Assistant, que te guía para configurar servidores.

Desde el IDE: Settings → Tools → Junie → MCP Settings → Edit mcp.json.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Nota: Junie actualmente solo soporta transporte stdio. Para Context7 se usa la versión npx en vez de la URL remota HTTP.

📖 Fuente: Junie Docs — Add and configure MCP servers

Instalar un MCP en Kiro CLI (Amazon) ¶

Fichero de configuración: ~/.kiro/settings/mcp.json (global) o .kiro/settings/mcp.json (proyecto).

Vía comando ¶

# Context7 (remoto)
kiro-cli mcp add --name context7 --scope global --url https://mcp.context7.com/mcp

# Sequential Thinking (local)
kiro-cli mcp add --name sequential-thinking --scope global \
  --command npx --args "-y" "@modelcontextprotocol/server-sequential-thinking"

Cambia --scope global por --scope workspace para configuración a nivel de proyecto.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Nota: Kiro soporta carga jerárquica de configuraciones: agente > workspace > global. Los MCP definidos a nivel de agente tienen prioridad sobre el resto.

📖 Fuente: Kiro Docs — MCP Configuration

Instalar un MCP en Roo Code (VS Code) ¶

Fichero de configuración: .roo/mcp.json en la raíz del proyecto, o el global mcp_settings.json en el almacenamiento de la extensión:

• macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json

Si el mismo servidor está en los dos sitios, manda el del proyecto.

Vía comando ¶

Roo Code no tiene CLI. Se configura desde la interfaz:

1. Interfaz gráfica: Panel de Roo → icono MCP → Edit Global MCP / Edit Project MCP.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Nota: Roo Code es un fork de Cline y comparte el formato. Soporta stdio, streamable-http y SSE (legacy). Puedes usar "alwaysAllow" igual que en Cline.

📖 Fuente: Roo Code Docs — Using MCP

Instalar un MCP en Trae (ByteDance) ¶

Fichero de configuración: .trae/mcp.json en la raíz del proyecto. Si ya lo tienes montado en otro IDE, el botón Raw Config (JSON) de la interfaz te deja pegar la configuración tal cual.

Vía comando ¶

Trae no tiene CLI para gestionar MCP. Se configura desde:

1. Interfaz gráfica: Settings → AI Management → Agents → MCP → Add Manually.

Vía fichero de configuración ¶

Trae usa una estructura diferente: mcpServers es un array (no un objeto) y command es un array único:

{
  "mcpServers": [
    {
      "name": "context7",
      "url": "https://mcp.context7.com/mcp",
      "type": "sse"
    },
    {
      "name": "sequential-thinking",
      "command": ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  ]
}

Cuidado: Trae rompe el estándar de dos formas: mcpServers es un array (no un objeto con claves), y command es un array completo incluyendo argumentos (no se separa en command + args). Para servidores remotos usa url + "type": "sse".

📖 Fuente: Trae Docs — Add MCP Servers

Instalar un MCP en Windsurf (Codeium) ¶

Fichero de configuración: ~/.codeium/windsurf/mcp_config.json.

Vía comando ¶

Windsurf no tiene CLI para MCP. Se configura desde la interfaz:

1. Interfaz gráfica: Chat → icono del martillo (🔨) → Configure → View raw config.

Vía fichero de configuración ¶

{
  "mcpServers": {
    "context7": {
      "serverUrl": "https://mcp.context7.com/mcp"
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Ojo: Windsurf usa serverUrl para servidores HTTP remotos (no url). Soporta interpolación de variables de entorno con ${env:NOMBRE_VARIABLE}.

📖 Fuente: Windsurf Docs — MCP

Tabla resumen de diferencias ¶

Dieciséis agentes, dieciséis formas distintas de declarar lo mismo. Contra ese caos va precisamente el estándar Agent Plugins, que define un único mcp.json portable para los MCP que viajan dentro de un plugin.

Errores comunes al instalar un MCP (y cómo salir de ellos) ¶

Casi todos los fallos caen en la misma media docena de sitios, y ninguno tiene que ver con el protocolo. Antes de abrir un issue en GitHub, ejecuta el comando del servidor a pelo en tu terminal: si ahí ya falla, tu agente no tiene la culpa.

El fichero no se lee y el servidor no aparece ¶

Síntomas: guardas la configuración, reinicias el agente y el servidor no sale por ningún lado. Ni error, ni nada.

Causa: el fichero es JSON estricto y tiene una coma de más al final del último bloque, comillas simples o un comentario. Es lo que pasa cuando copias un trozo del medio de un ejemplo.

Solución: valida antes de reiniciar.

python3 -m json.tool ~/.cursor/mcp.json

Si está bien, te devuelve el JSON formateado. Si no, te canta la línea exacta. Ojo con la excepción: .vscode/mcp.json sí admite comentarios porque VS Code lo trata como JSONC. El resto, no.

La clave raíz no es la que crees ¶

Síntomas: el JSON es válido, el agente arranca, pero la lista de herramientas sigue vacía.

Causa: pegaste la configuración de otro agente. mcpServers es lo habitual, pero Copilot usa servers, OpenCode usa mcp, Amp usa amp.mcpServers y Goose usa extensions con cmd en vez de command.

Solución: mira la columna “Clave raíz” de la tabla de arriba y renombra. No es un problema de configuración, es de traducción entre agentes.

El servidor remoto se queda colgado ¶

Síntomas: los MCP locales funcionan, los remotos aparecen como failed o cargando para siempre.

Causa: cada agente llama distinto al campo de la URL. Gemini CLI y Qwen Code esperan httpUrl para streamable HTTP, Windsurf espera serverUrl, y los demás url (algunos con type: "http" al lado).

Solución: usa el nombre exacto que espera tu agente y comprueba que el endpoint responde antes de culpar a la configuración.

curl -i -X POST https://mcp.context7.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

npx: command not found aunque npx te funcione ¶

Síntomas: el servidor stdio no arranca desde el IDE, pero ese mismo comando va perfecto en tu terminal.

Causa: las aplicaciones de escritorio no heredan el PATH de tu shell. Si instalaste Node con nvm, npx vive en un directorio del que tu IDE no sabe nada.

Solución: ruta absoluta y a otra cosa.

which npx
# /Users/tu-usuario/.nvm/versions/node/v22.14.0/bin/npx

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "/Users/tu-usuario/.nvm/versions/node/v22.14.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

La API key no llega al servidor ¶

Síntomas: el servidor arranca, pero todas las llamadas devuelven 401 o un “missing credentials”.

Causa: exportaste la variable en tu .zshrc y das por hecho que el servidor la ve. El proceso lo lanza el agente, no tu shell.

Solución: declara las variables en el bloque env del servidor. Y si tu agente soporta interpolación, úsala para no dejar el token escrito en un fichero que acabará en el repositorio: ${VAR} en Claude Code, ${env:VAR} en Windsurf.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Permiso denegado al arrancar tu propio servidor ¶

Síntomas: EACCES o “permission denied” cuando el servidor es un script tuyo.

Causa: al fichero de entrada le falta el bit de ejecución, el shebang, o las dos cosas.

Solución: chmod +x dist/index.js y #!/usr/bin/env node en la primera línea. En macOS, si el servidor toca carpetas como Documentos o Escritorio, el sistema pedirá permiso de disco a la aplicación que lo lanza, no al servidor.

Tienes demasiados MCP activos a la vez ¶

Síntomas: el agente va más lento, elige la herramienta equivocada o se queja del tamaño del contexto.

Causa: cada servidor inyecta la descripción de todas sus herramientas en cada petición. Quince servidores son miles de tokens gastados antes de que escribas una sola palabra.

Solución: deja activos solo los que uses en ese proyecto y desactiva el resto desde la interfaz o con "enabled": false. Si quieres el detalle de cuánto cuesta cada cosa, lo desmenuzamos en cómo ahorrar tokens con tu agente de IA.

💡 Si solo te llevas una cosa de esta sección: el 90% de los fallos se resuelven validando el JSON y ejecutando el comando del servidor a mano.

Preguntas frecuentes sobre la instalación de MCP ¶

¿Dónde está el fichero de configuración de MCP en Claude Code? ¶

En ~/.claude.json para los scopes local y user, y en .mcp.json en la raíz del proyecto para el scope project. El primero es privado y el segundo se commitea, así que todo el equipo comparte los mismos servidores.

¿Cómo instalo un MCP en Cursor si no tiene CLI? ¶

Editando ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto) con la clave mcpServers. También puedes hacerlo desde Settings → MCP Settings → Add new MCP server, que escribe el mismo fichero.

¿Por qué mi MCP server aparece como “failed” y no conecta? ¶

Las tres causas más habituales son un JSON con coma final, una clave raíz que no corresponde a ese agente, y npx fuera del PATH del IDE. Ejecuta el comando del servidor en tu terminal: si funciona ahí, el problema está en el fichero de configuración.

¿Puedo usar el mismo JSON de configuración en todos los agentes? ¶

No tal cual. El bloque interno del servidor (command, args, url) sí es casi idéntico, pero la clave raíz y el nombre del campo de la URL cambian entre agentes. Traducir de uno a otro son dos ediciones: la clave de arriba y el campo de la URL.

¿Necesito instalar algo antes de añadir un MCP server? ¶

Para los servidores locales que se ejecutan con npx necesitas Node.js, y para los que usan uvx, Python con uv. Los servidores remotos por HTTP no requieren nada más que la URL, porque el proceso se ejecuta en el servidor.

¿Qué diferencia hay entre un MCP local (stdio) y uno remoto (HTTP)? ¶

El local se ejecuta como un proceso en tu máquina y se comunica por entrada y salida estándar: tiene acceso a tus ficheros y no depende de la red. El remoto vive en un servidor y te conectas por HTTP: no consume recursos tuyos, pero necesita conexión y, casi siempre, autenticación.

¿Cómo compruebo qué MCP tengo instalados y si funcionan? ¶

En los agentes de terminal, el comando /mcp dentro de la sesión lista los servidores y su estado: lo tienen Claude Code, Gemini CLI y Qwen Code. Desde fuera de la sesión, claude mcp list o cline config mcp. En los IDE gráficos, el panel de MCP marca en rojo los que no arrancan.

¿Dónde guardo las API keys de un MCP server? ¶

En el bloque env de la configuración del servidor, nunca escritas dentro de args. Si el fichero se commitea, como .mcp.json o .vscode/mcp.json, usa interpolación de variables de entorno para que el token quede fuera del repositorio.

¿Configuro los MCP a nivel global o por proyecto? ¶

Global para lo que usas siempre, como documentación o razonamiento. Por proyecto para lo que solo tiene sentido en ese repositorio: la base de datos, el gestor de incidencias, el diseño. Así evitas cargar herramientas que no vas a usar y mantienes el contexto pequeño.

¿Cuántos MCP servers puedo tener activos a la vez? ¶

No hay un límite duro, pero sí uno práctico: cada servidor añade sus herramientas al contexto de cada petición. A partir de diez servidores empiezas a notar que el modelo elige peor. Activa los que necesites en ese momento y desactiva el resto.

Dónde encontrar más MCP servers ¶

• Registro oficial de MCP — El directorio mantenido por el proyecto MCP bajo la Linux Foundation. Busca servidores por nombre, categoría o popularidad: registry.modelcontextprotocol.io

• Repositorio GitHub del protocolo — Especificación, SDKs (TypeScript, Python, Java, Go, C#) y servidores de referencia: github.com/modelcontextprotocol

• Documentación oficial de MCP — Guías de inicio, tutoriales y referencia completa del protocolo: modelcontextprotocol.io

• Smithery — Marketplace comunitario con cientos de MCP servers listos para instalar, con soporte one-click para varios agentes: smithery.ai

• Tutorial de MCP Apps — Aprende a crear herramientas MCP con interfaces visuales interactivas usando mcp-use y React: tutorial paso a paso en Web Reactiva