Añade tu primer servidor MCP a Claude Code

Un servidor MCP le da a Claude Code acceso a una herramienta, base de datos o servicio externo, para que no tengas que pegar esos datos en el chat. Añadir uno lleva un solo comando.

Dos comandos que conviene conocer

Para un servidor remoto, usa HTTP. Este es el ejemplo de la documentación con Notion:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Para un programa que corre en tu propia máquina (stdio), pon -- entre las opciones de Claude Code y el comando del propio servidor:

claude mcp add --transport stdio myserver -- python server.py --port 8080

Todo lo que va detrás del -- le llega al servidor sin cambios. Las opciones de Claude Code (--transport, --env, --scope, --header) van antes del nombre del servidor. Existen servidores SSE pero están en desuso, así que usa HTTP cuando el servidor lo ofrezca.

Cuida lo que añadiste

• claude mcp list muestra tus servidores.
• claude mcp get notion muestra uno.
• claude mcp remove notion lo quita.
• /mcp dentro de Claude Code muestra el estado de cada servidor y gestiona el inicio de sesión.

Tres ámbitos

• Local (por defecto)Se guarda en ~/.claude.json bajo la ruta del proyecto. Solo tú, solo este proyecto.
• ProyectoSe guarda en .mcp.json en la raíz del proyecto. Pensado para subirlo a git y que lo comparta el equipo, y Claude Code pide aprobación antes de usarlo.
• UsuarioSe guarda en ~/.claude.json. Solo tú, en todos tus proyectos.

Elige con --scope. Si el mismo nombre existe en más de un sitio, el local gana al de proyecto y este al de usuario, y Claude Code usa la entrada entera del ganador sin mezclar campos.

Un .mcp.json compartido

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

En este archivo, ${VAR} se sustituye por el valor de una variable de entorno, y ${VAR:-default} usa el valor por defecto solo si la variable no está definida. Funciona en command, args, env, url y headers, así que el archivo que subes puede nombrar una variable en lugar de contener un secreto.

Iniciar sesión

Para un servidor que usa OAuth, ejecuta /mcp y termina el inicio de sesión en el navegador. Claude Code guarda el token y lo renueva. «Clear authentication» en el mismo menú lo revoca. Una ejecución no interactiva (claude -p) no puede hacer el inicio de sesión, así que entra antes desde una sesión interactiva.

Antes de fiarte de uno

• Comprueba que confías en el servidor. La documentación avisa de que los servidores que traen contenido de fuera pueden exponerte a una inyección de instrucciones, es decir, texto en una página o documento que intenta dirigir a Claude.
• En una sesión interactiva, Claude Code te pide aprobar los servidores de proyecto de .mcp.json. claude mcp reset-project-choices borra tus respuestas.
• Las ejecuciones no interactivas cargan los servidores de proyecto sin preguntar, así que mira el .mcp.json de cualquier repositorio que no hayas escrito tú.
• Un token que pasas con --env o --header se guarda como parte de la configuración de ese servidor. Prefiere una variable cuando el servidor lo permita.

Tamaño y coste

Claude Code avisa cuando un resultado de herramienta pasa de 10.000 tokens, y limita los resultados a 25.000 por defecto. Puedes subir el límite con la variable MAX_MCP_OUTPUT_TOKENS, pero los resultados grandes llenan rápido tu contexto. La búsqueda de herramientas viene activada, así que las definiciones de herramientas se cargan bajo demanda. Si quieres gastar menos tokens, mira gasta menos cuota.

Comprueba que funciona

1. Añade un servidor en el que confíes.
2. Ejecuta claude mcp list y /mcp y mira que aparezca conectado.
3. Pregunta a Claude algo que solo ese servidor pueda responder.
4. Quítalo si no lo usas. Un servidor sin uso es desorden.

Límites

• Los comandos, las opciones y los valores por defecto cambian entre versiones. Varios comportamientos de la página de documentación dependen de una versión mínima, así que mira la tuya con claude --version.
• No hemos probado todos los servidores. Que un servidor concreto sea seguro o funcione lo tienes que comprobar tú.

Esta página sigue la documentación de MCP de Anthropic tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los ejemplos.

Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).