Cómo configurar MCP en Claude Code (paso a paso, desde cero)

Claude Code, por sí solo, ya lee y escribe archivos y ejecuta comandos en tu proyecto. Pero el trabajo de verdad casi siempre vive en otras herramientas. El GitHub donde está el código. El navegador que abre tu sitio. La base de datos con los pedidos. MCP es lo que conecta Claude con todo eso.

En esta guía vas a conectar tu primer servidor en pocos minutos. Puedes copiar y pegar cada comando.

Qué es MCP, sin rodeos

MCP significa Model Context Protocol. Es un estándar que deja que Claude use herramientas externas de forma directa, como GitHub, Notion o el navegador, sin que tengas que andar copiando y pegando información de un lado a otro.

Piénsalo así. Sin MCP, Claude es un empleado brillante encerrado en una sala. Con MCP, le das las llaves de las demás salas de la empresa.

Antes de empezar

Necesitas Claude Code instalado y funcionando en la terminal. Si el comando de abajo responde con una versión, ya estás listo.

claude --version

El comando que agrega un servidor

Todo gira en torno a un solo comando. La estructura es esta:

claude mcp add [--scope local|project|user] [--transport http|stdio|sse] <nombre> <url-o-comando>

Parece mucho, pero en la práctica solo rellenas tres espacios. El nombre que le das, de dónde viene y quién puede usarlo. Vamos por partes.

Paso 1. Elige quién va a usarlo (el alcance)

El alcance decide dónde se guarda la configuración y quién ve el servidor. Son tres.

• local (el predeterminado). Vale solo para ti, solo en este proyecto. Úsalo cuando estés probando.
• project. Queda en un archivo .mcp.json en la raíz del proyecto y va a Git. Todo el que clone el repositorio recibe el mismo servidor. Úsalo para herramientas que todo el equipo necesita.
• user. Vale para ti en todos los proyectos de la máquina. Úsalo para tus herramientas personales.

Cuando dos alcances definen el mismo servidor, el orden de prioridad es local, después project, después user.

Paso 2. Agrega el servidor

Existen tres formas de conexión. No necesitas memorizarlas, solo saber qué ejemplo copiar.

Servidor alojado (HTTP)

Es un servidor que ya corre en una URL. El más común hoy.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Servidor local (stdio)

Corre en tu propia máquina, como un navegador controlable o el acceso a archivos. Todo lo que va después del -- es el comando que Claude ejecuta.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Servidor con eventos (SSE)

Menos común al principio. Sirve para servidores que envían avisos a Claude.

claude mcp add --transport sse mi-webhook https://mi-servicio.local:8000

Paso 3. Ejemplo completo, de principio a fin (GitHub)

Digamos que quieres a Claude revisando tus Pull Requests en GitHub. Con un token de acceso de GitHub a mano, el comando es este.

claude mcp add --scope user --transport http github \
  https://mcp.github.com/mcp \
  --header "Authorization: Bearer ghp_tu_token_aqui"

Listo. A partir de ahora, en cualquier proyecto, puedes pedir:

Revisa el PR en github.com/miempresa/repo/pull/42

Y Claude pasa a ver las herramientas de GitHub. Listar PRs, leer el diff, dejar comentarios.

Paso 4. El archivo .mcp.json (para todo el equipo)

Si usaste el alcance project, la configuración se convierte en un archivo .mcp.json en la raíz del proyecto. Tiene este formato.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ghp_tu_token_aqui"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Como este archivo va a Git, la primera vez que alguien del equipo abre el proyecto Claude pide una aprobación rápida. Es a propósito, para que nadie ejecute un servidor sin saberlo.

Paso 5. Confirma que funcionó

Desde la terminal, fuera de una sesión, ejecuta:

claude mcp list

Vas a ver cada servidor con un estado.

MCP Servers (local):
  ✓ github: Connected
  ✓ playwright: Connected
  ! sentry: Needs authentication
  ✗ mi-webhook: Failed to connect

Qué significa cada uno:

• ✓ Connected. Todo en orden, Claude ya puede usarlo.
• ! Needs authentication. Falta autorizar (mira abajo).
• ✗ Failed to connect. URL incorrecta, servidor caído o token inválido.

Dentro de una sesión, el comando /mcp abre un menú para ver las herramientas, autenticar y revisar el estado.

/mcp

Si el servidor pide inicio de sesión (OAuth), es aquí donde eliges Authenticate. El navegador se abre, lo apruebas, y el estado pasa a Connected.

Comandos útiles del día a día

# listar todo
claude mcp list

# ver los detalles de un servidor
claude mcp get github

# eliminar
claude mcp remove github

# importar servidores que ya están en Claude Desktop (macOS y WSL)
claude mcp add-from-claude-desktop

Los 3 tropiezos más comunes

1. “No MCP servers configured” de la nada. Agregaste el servidor con el alcance local dentro de un proyecto y abriste Claude en otro. La solución es usar el alcance user, que vale en todas partes, o agregarlo de nuevo en el proyecto correcto.

2. “Failed to connect”. Casi siempre es la URL o el token. Para un servidor HTTP, prueba la URL con curl -I <url>. Para un servidor local, ejecuta el comando del -- directo en la terminal y mira el error real. Si es lentitud la primera vez, aumenta el tiempo límite con MCP_TIMEOUT=60000 claude.

3. Editaste el .mcp.json y no cambió nada. Claude lee ese archivo solo cuando la sesión empieza. Sal con /exit y ábrelo de nuevo.

En resumen

Conectar una herramienta a Claude Code es una línea de comando. Eliges el alcance, pegas la dirección, confirmas con claude mcp list y listo. A partir de ahí Claude deja de ser un asistente aislado y pasa a actuar en las herramientas que tu empresa ya usa.

Es justo este tipo de conexión la que transforma una curiosidad en automatización que ahorra horas cada semana. Si quieres, nosotros hacemos ese diseño para tu negocio y te lo entregamos funcionando.

Preguntas frecuentes

¿Qué es MCP en Claude Code?

MCP significa Model Context Protocol. Es un estándar que permite a Claude usar herramientas externas directamente, como GitHub, Notion o el navegador, sin que copies y pegues información de un lado a otro.

¿Cómo agregar un servidor MCP en Claude Code?

Usa el comando claude mcp add, indicando un nombre y la dirección del servidor. Para un servidor alojado: claude mcp add --transport http nombre https://url-del-servidor. Verifica después con claude mcp list.

¿Cuál es la diferencia entre los alcances local, project y user?

Local vale solo para ti en este proyecto. Project queda en un archivo .mcp.json en la raíz y va al Git, valiendo para todo el equipo. User vale para ti en todos los proyectos de la máquina. Ante conflicto, la prioridad es local, luego project, luego user.

¿Por qué aparece Failed to connect al listar los servidores?

Casi siempre es la URL o el token incorrectos. En un servidor HTTP, prueba la URL con curl. En un servidor local, ejecuta el comando del -- directo en la terminal para ver el error real. Si es lentitud en la primera conexión, aumenta el tiempo límite con MCP_TIMEOUT=60000.

¿Es seguro guardar el token en el archivo .mcp.json?

No. Como ese archivo va al Git, nunca escribas una contraseña o token real en él. Deja el token en una variable de entorno y referencia la variable, en lugar de escribir el valor.