Conecta un servidor MCP a Claude Code

Recién instalado, Claude Code razona muy bien pero no tiene con qué tocar nada. Puede describir el SQL que correría, la API que llamaría o el archivo que leería, pero no puede ejecutar nada de eso sin un adaptador. El Model Context Protocol (MCP) es justamente eso: un proceso pequeño con el que Claude Code habla a través de una interfaz estándar para correr herramientas reales en vez de adivinar. Esta guía recorre el registro de un servidor MCP de punta a punta: cómo elegirlo, definirle el alcance, pasarle secretos de forma segura, verificar la conexión y evitar las fallas que hacen que un servidor parezca "roto" cuando en realidad lo único que pasa es que no está conectado.

01 · Qué es MCP en realidad (y cuándo conviene usarlo)

MCP es un estándar liviano para conectar un modelo con capacidades externas. Un servidor expone un conjunto de herramientas (y a veces recursos y prompts); Claude Code es el cliente que descubre esas herramientas y las llama por ti. La gracia del estándar es que no tienes que escribir una integración a medida para cada herramienta. Todo lo que hable MCP se conecta a Claude Code de la misma forma, y ese mismo servidor también funciona en otros clientes MCP.

Recurre a MCP cuando quieras que Claude actúe, no solo que sugiera. Consultar una base de datos en Supabase, crear un registro en tu gestor de tickets, pegarle a una API interna, leer más allá del directorio de trabajo: todo eso son efectos secundarios, y un efecto secundario necesita una herramienta. Si lo único que necesitas es un prompt reutilizable o una convención del proyecto, montar un servidor MCP es demasiado; un comando slash o una entrada en CLAUDE.md es mucho más liviano. La concesión, dicho sin rodeos: cada servidor que agregas es un proceso más, un conjunto de permisos más y una cosa más que puede filtrar un secreto o hacer algo irreversible. Agrégalos con criterio.

En la práctica te vas a topar con dos formas de transporte. Los servidores stdio son procesos locales que Claude Code arranca y con los que habla por entrada/salida estándar; así corre la mayoría de los paquetes de npm. Los servidores HTTP/SSE son endpoints remotos a los que apuntas por URL, útiles para servicios alojados e infraestructura compartida del equipo. Casi toda esta guía usa stdio porque es el caso más común, pero las reglas de alcance y de secretos aplican a los dos por igual.

02 · Requisitos previos y un modelo mental de 60 segundos

Antes de agregar nada, ten esto listo:

1. Claude Code instalado y con sesión iniciada. Corre claude dentro de un directorio de proyecto y confirma que arranca.
2. El runtime que el servidor necesita. La mayoría de los servidores stdio vienen como paquetes de npm que arrancas con npx, así que necesitas Node.js en tu máquina. Los servidores en Python suelen usar uvx o pipx.
3. Una credencial real para lo que vas a conectar: el connection string de una base de datos, una API key, un token de acceso. Tenla a mano, pero evita pegarla en cualquier lado donde pueda terminar subida al repo.
4. El working tree de git limpio. Vas a escribir un archivo de configuración que tal vez termines subiendo al repo; parte de un estado conocido para que el diff quede claro.

El modelo mental son cuatro piezas. El servidor es el proceso adaptador. El comando de arranque es cómo Claude Code lo inicia (en stdio) o dónde lo encuentra (en HTTP). El alcance decide dónde se guarda el registro y quién lo ve. Los secretos son las credenciales que se le pasan al servidor al arrancar, fuera de la configuración que se sube al repo. Acierta en esas cuatro y todo lo demás son detalles.

03 · Registra tu primer servidor

El comando central es claude mcp add: le das un nombre y el comando que arranca el servidor. Todo lo que va después de -- es el comando de arranque, y se pasa tal cual, sin tocar.

claude mcp add supabase -- npx -y @supabase/mcp-server-supabase --read-only

Vale la pena fijarse en un par de cosas. El flag -y le dice a npx que no pida confirmación para instalar, algo que importa porque Claude Code lo arranca sin interacción. El flag --read-only es una opción del propio servidor, no de Claude Code; cuando un servidor ofrece modo read-only, empieza por ahí. Y el nombre (supabase) es lo que vas a ver en /mcp y lo que usarás cuando quieras invocar o depurar el servidor más adelante.

Para un servidor HTTP, en vez de un comando de arranque apuntas a una URL con el flag de transporte:

claude mcp add --transport http internal-api https://mcp.example.internal/v1

Después de agregarlo, reinicia Claude Code para que tome el servidor nuevo y corre el comando slash /mcp. Deberías ver tu servidor en la lista, marcado como conectado, junto con las herramientas que expone. Si aparece ahí y conectado, ya pasaste la parte difícil.

Cómo pasar los secretos bien

Casi todo servidor útil necesita una credencial. Pásala como variable de entorno en la misma línea de claude mcp add con -e, para que el secreto viva en el entorno de tu shell al momento de arrancar y no quede incrustado en un string:

claude mcp add supabase \
  -e SUPABASE_ACCESS_TOKEN="$SUPABASE_ACCESS_TOKEN" \
  -- npx -y @supabase/mcp-server-supabase --read-only

El detalle clave: $SUPABASE_ACCESS_TOKEN se lee de tu entorno, donde ya lo exportaste (desde un .env que no subes al repo, un gestor de secretos o tu perfil de shell). El token en sí nunca aparece en el comando, ni en el historial de tu shell en texto plano, ni, y esto es lo crítico, en el archivo de configuración si ese archivo termina versionado en git. Es la misma disciplina que aplico en todo lugar donde un secreto toca una herramienta, y es justo la idea detrás de Infuse, el gestor de secretos que estoy construyendo: la credencial existe en tiempo de ejecución y en ningún sitio permanente que tú no hayas elegido.

04 · Define el alcance: proyecto, usuario o local

Dónde vive el registro de un servidor determina quién lo recibe y si viaja con tu código. Claude Code te ofrece varios alcances; los dos que más vas a usar son project y user.

• El alcance de proyecto escribe el servidor en el .mcp.json de la raíz del repo. Sube ese archivo al repo y cada compañero que clone el repo obtiene el mismo servidor con el mismo comando de arranque. Es el default correcto para todo lo que el proyecto necesita de por sí, como la base de datos que usa la app o la API interna con la que habla.
• El alcance de usuario registra el servidor solo para ti, en todos tus proyectos, y se guarda en tu config personal en vez del repo. Úsalo para herramientas tuyas que quieres tener en todos lados, como un servidor de notas o una herramienta de búsqueda personal, y que no tienen por qué imponérsele al resto del equipo.

Agrega un servidor con alcance de proyecto de forma explícita para que caiga en .mcp.json:

claude mcp add --scope project github \
  -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  -- npx -y @modelcontextprotocol/server-github

El .mcp.json que subas al repo apuntará a la variable de entorno, no al valor del token, que es exactamente por qué la disciplina de secretos de la sección 03 no es opcional. Una config subida al repo con una referencia a una variable de entorno es segura y reproducible; una config subida al repo con un token literal es un incidente.

05 · Un ejemplo completo, de principio a fin

Digamos que estás armando una feature que necesita consultar tu base de datos en Supabase, y quieres que Claude Code lea el esquema y corra consultas seguras mientras trabajas, sin darle acceso de escritura desde el día uno.

1. Exporta la credencial en tu shell, sacándola de un archivo que git ignora:

export SUPABASE_ACCESS_TOKEN="$(grep SUPABASE_ACCESS_TOKEN .env.local | cut -d= -f2)"

2. Agrega el servidor con alcance de proyecto, en read-only:

claude mcp add --scope project supabase \
  -e SUPABASE_ACCESS_TOKEN="$SUPABASE_ACCESS_TOKEN" \
  -- npx -y @supabase/mcp-server-supabase --read-only

3. Reinicia Claude Code y corre /mcp. Confirma que supabase aparezca conectado y liste herramientas como un lector de esquema y un ejecutor de consultas. Si no aparece conectado, salta a la siguiente sección.

4. Úsalo. Pídele a Claude que describa una tabla o que cuente filas. La primera vez que llame una herramienta, Claude Code puede pedirte que la apruebes; apruébala para las que confíes. Ahora las respuestas salen de tu base de datos real, no de lo que el modelo supone que será tu esquema.

5. Sube «.mcp.json» al repo. Tu compañero clona, exporta su propio SUPABASE_ACCESS_TOKEN, reinicia Claude Code y queda con el setup idéntico, sin tener que abrir un hilo en Slack preguntando "¿cómo conectaste esto?".

6. Amplía después, con criterio. Cuando de verdad necesites escrituras, quita el --read-only, vuelve a agregar el servidor y trata esa ruta como si fuera acceso directo a la base de datos, porque a partir de ahí lo es. Empieza acotado; amplía solo cuando la integración se lo haya ganado.

06 · Errores comunes y cómo depurarlos

Cuando un servidor MCP se porta mal, casi siempre es una de un puñado de cosas. Revísalas en orden.

• Una herramienta nunca se dispara, sin avisar. La causa habitual es un servidor que no conectó. Corre /mcp primero; un servidor sin conectar, o que ni siquiera aparece en la lista, lo explica al instante. El arreglo rara vez está en el prompt; está en el registro.
• La conexión falla al arrancar. En servidores stdio esto suele ser un comando de arranque mal armado: una errata en el nombre del paquete, un -y faltante en npx que lo dejó colgado esperando una confirmación, o el runtime (Node, Python) fuera del PATH en el entorno desde el que arrancó Claude Code. Prueba corriendo a mano, en tu terminal, el comando exacto que va después del --; el error que salga ahí es el de verdad.
• Errores de auth después de conectar. El servidor arrancó, pero la credencial está mala, vencida o en realidad no está en el entorno. Imprime la variable con echo en el mismo shell desde el que lanzaste claude para confirmar que está cargada, y revisa el README del servidor por el nombre exacto de la variable que lee; no están estandarizados de un servidor a otro.
• La aprobación de primer uso parece una falla. Por defecto, las herramientas de un servidor recién agregado pueden pedirte aprobación la primera vez que se ejecutan. Eso es un control, no un bug. Si una herramienta parece inerte, fíjate si está esperando una aprobación antes de dar por sentado que está rota.
• Un secreto subido al repo. Si en algún momento encuentras un token literal en .mcp.json, dalo por filtrado: rota la credencial en el proveedor y vuelve a agregar el servidor con una variable de entorno para que el valor nunca vuelva a escribirse en el archivo.

Conectar un servidor MCP es, en el fondo, cuatro decisiones bien tomadas: qué servidor, cómo arranca, en qué alcance vive y cómo le llega su secreto sin subirse jamás al repo. Acierta en esas cuatro y Claude Code deja de adivinar sobre tus sistemas y empieza a trabajar con ellos directamente. Arranca en read-only, verifica con /mcp, sube la config al repo (nunca el secreto) y amplía el acceso solo cuando confíes en lo que hay del otro lado.