Tutorial de MCP para Claude Code: agrega servidores correctamente
Conecta Context7, Playwright o cualquier servidor MCP a Claude Code — transportes, alcances, el archivo .mcp.json, llaves de API y el panel /mcp, en un solo recorrido ilustrado.
La versión corta
- Un comando instala cualquier servidor: claude mcp add name -- npx -y @scope/package para servidores locales, o claude mcp add --transport http name url para los remotos.
- Hay tres transportes: stdio ejecuta un comando en tu máquina, SSE es la forma remota antigua y streamable HTTP es la opción remota moderna.
- Tres alcances deciden quién recibe el servidor: local (solo tú), project (compartido vía .mcp.json) y user (todos tus proyectos).
- Ejecuta /mcp dentro de una sesión para ver el estado y las herramientas; la primera llamada a una herramienta pide permiso, y puedes permitir una vez o siempre.
Claude Code Tutorial #7 - MCP Servers
Canal: The Net Ninja14:16
Claude Code MCP: How to Add MCP Servers (Complete Guide)
Canal: Leon van Zyl17:58
Model Context Protocol (MCP) — official Claude Code docs
Documentación: code.claude.com/docs
Las capturas vienen del capítulo de The Net Ninja — una grabación de pantalla completa y limpia. El desglose de comandos, alcances y arreglos de Windows sigue el walkthrough más completo de Leon van Zyl más la documentación oficial.
Los fotogramas pertenecen a sus respectivos creadores y se acreditan aquí con enlaces directos a los momentos exactos; el texto es nuestro.
De cero a dos servidores MCP funcionando
Parte 1 · Lo que los servidores MCP desbloquean
- 1
Lo que MCP le da a Claude Code
Claude Code trae herramientas integradas para archivos y terminal, pero todo lo que queda fuera de tu base de código está fuera de su alcance. MCP — el Model Context Protocol — es la vía estándar de Anthropic para enchufar herramientas extra: un servidor expone capacidades y Claude Code las llama como cualquier herramienta integrada.
La diapositiva del curso que define MCP en una línea.Ver en 0:52 - 2
Elige servidores según el trabajo
Cada servidor trae sus propias herramientas. El servidor de Supabase puede listar tablas, desplegar edge functions y ejecutar SQL; Playwright maneja un navegador real; Context7 sirve documentación actualizada de frameworks. Empieza por el que elimine tu tarea repetitiva más molesta.
El ejemplo de Supabase: tres herramientas, un servicio externo.Ver en 1:24 - 3
Busca el comando de instalación en el README del servidor
Los autores de servidores publican un comando listo para Claude Code en su README — Context7 y Playwright lo hacen. Directorios como PulseMCP facilitan explorar qué existe antes de comprometerte con algo.
El README de Playwright MCP documenta funciones y requisitos.Ver en 2:02 - 4
Entiende los tres tipos de transporte
La documentación oficial divide las instalaciones en locales y remotas. Un servidor stdio ejecuta un comando en tu máquina — es el predeterminado. Los servidores SSE y HTTP son endpoints remotos a los que te conectas; SSE es el formato antiguo y streamable HTTP su reemplazo. La sintaxis de claude mcp add cambia un poco en cada caso.
La página de la documentación que compara stdio local con SSE y HTTP remotos.Ver en 3:02
Parte 2 · Agrega tu primer servidor
- 5
Agrega Context7 con alcance project
Desde la terminal: claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp. El nombre lo eliges tú, todo lo que va después del doble guion es el comando a ejecutar, y --scope project escribe el servidor en la configuración compartida del proyecto en lugar de la personal.
El comando exacto para agregar el servidor de documentación Context7.Ver en 5:22 - 6
Lee el .mcp.json que creó
Los servidores con alcance project aterrizan en un archivo .mcp.json en la raíz del repo, bajo la clave mcpServers. Cada entrada registra el tipo — stdio aquí — más el comando y sus argumentos: la misma estructura que usan Cursor o Claude Desktop.
Dentro de .mcp.json: type, command y args del servidor stdio.Ver en 6:42 - 7
Usuarios de Windows: ojo con el prefijo cmd /c
En Windows nativo sin WSL, los comandos stdio necesitan cmd /c antes de npx para que la shell se cierre limpio después de que el servidor termina. La documentación lo señala en un recuadro de advertencia, y el walkthrough muestra el ajuste exacto.
El recuadro de advertencia oficial para servidores stdio en Windows.Ver en 3:24 - 8
Confirma que el archivo llegó a tu repo
Tras un agregado con alcance project, .mcp.json aparece en el explorador como un archivo nuevo sin seguimiento, listo para hacer commit y que tus compañeros reciban los mismos servidores. Los servidores con alcance local nunca tocan este archivo.
Un .mcp.json nuevo en la raíz del proyecto, sin seguimiento y listo para commit.Ver en 8:32 - 9
¿Prefieres remoto? Usa el transporte HTTP
Cuando un build stdio falla, el endpoint remoto es la salida rápida: claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. Sin proceso local y sin npm — Claude Code habla directo con la URL.
La variante HTTP del comando de agregar contra el endpoint de Context7.Ver en 8:36 - 10
Verifica la conexión en /mcp
Inicia Claude Code y ejecuta /mcp. Cada servidor muestra su estado y su lista de herramientas. Un fallo normalmente se arregla con la reconexión integrada; si no, la sección de solución de problemas de abajo cubre las causas comunes.
El panel /mcp mostrando context7 conectado con sus dos herramientas.Ver en 9:22
Parte 3 · Usa los servidores en trabajo real
- 11
Llama al servidor desde un prompt real
Pide algo que las herramientas integradas no pueden hacer y nombra al servidor: «revisa la documentación más reciente de Tailwind contra mi archivo CSS global — usa context7». Adjuntar el archivo con una mención @ ancla la respuesta a tu código.
El prompt que pide documentación actual de Tailwind vía context7.Ver en 9:38 - 12
Aprueba la llamada a la herramienta
La primera vez que corre una herramienta de un servidor, Claude Code pide permiso. Aprueba una vez, o elige la opción de permitir siempre para los servidores de confianza y las llamadas siguientes pasan sin preguntar.
La tarjeta de permiso para la herramienta resolve-library-id de Context7.Ver en 10:00 - 13
Lee la respuesta con fundamento
La herramienta devuelve la documentación relevante — aquí la guía de variables de tema de Tailwind v4 — con el costo en tokens a la vista, y Claude Code lo aplica a tu archivo. Ese es todo el punto: respuestas de documentación vigente en lugar de conjeturas de los datos de entrenamiento.
La respuesta de get-library-docs confirmando la configuración del tema.Ver en 10:15 - 14
Fija el hábito en CLAUDE.md
Escribe el símbolo de hash para agregar una memoria de proyecto, por ejemplo: «usa Context7 para documentación actualizada al implementar librerías o frameworks nuevos». La línea queda en CLAUDE.md y cada sesión posterior la hereda.
Una memoria de una línea en CLAUDE.md que hace de Context7 el predeterminado.Ver en 10:42 - 15
Agrega un segundo servidor: Playwright
Repite el patrón para automatización de navegador: claude mcp add playwright --scope project -- cmd /c npx @playwright/mcp@latest — y quita la parte de cmd /c en macOS o Linux. Un repo, varios servidores, un solo archivo de configuración.
Agregando el servidor Playwright MCP con alcance project.Ver en 11:22 - 16
Míralo manejar el navegador
Pídele a Claude Code que abra una página y la resuma — Playwright navega, hace clic y lee, y luego reporta. Con la documentación de Context7 y el navegador de Playwright, la mayoría de los pendientes externos quedan a un prompt de distancia.
El Playwright MCP navegando a un sitio para resumirlo.Ver en 12:42
Variables de entorno, headers y llaves de API
Los servidores remotos y las API con autenticación necesitan credenciales. Claude Code las recibe como variables de entorno en servidores stdio y como headers en los remotos — sin editar archivos de configuración a mano.
- 1Servidores stdio: claude mcp add myserver -e API_KEY=your-key -e ZONE=your-zone -- npx -y @some/mcp-server — repite el flag -e por cada variable, colocándolo justo después del nombre del servidor.
- 2Servidores HTTP remotos: claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer your-key" — el header se envía con cada llamada a herramienta.
- 3Repaso de alcances: local deja el servidor para ti en este proyecto, project lo comparte vía .mcp.json, y user lo instala en todos tus proyectos. Se define con -s o --scope al agregarlo.
- 4Quitar un servidor: claude mcp remove name — en alcance project, haz commit del cambio en .mcp.json para que el servidor también desaparezca para tus compañeros.
Los valores pasados con -e se guardan en texto plano dentro del archivo de configuración. Prefiere llaves con permisos acotados donde la API lo permita, y nunca hagas commit de credenciales reales en un .mcp.json de alcance project.
Cuando /mcp muestra failed
Casi todos los fallos de MCP en Claude Code se remontan a unas pocas causas. Repasa esta lista antes de borrar y volver a agregar nada.
- 1Unknown option -y en Windows: algunas terminales se traban con el flag de npm. Corre el comando de agregar desde PowerShell o el Símbolo del sistema, o quita -y, agrega el servidor, y luego regresa -y al arreglo args del .mcp.json a mano.
- 2stdio falla en Windows nativo: antepón cmd /c al comando — por ejemplo cmd /c npx -y @some/package@latest. Sin WSL es obligatorio, y la etiqueta @latest evita builds viejos en caché.
- 3Estado en failed: abre /mcp y reconecta — los fallos pasajeros normalmente se arreglan al segundo intento. Si no, el panel muestra la ubicación del log del servidor para ver el error real.
- 4El servidor no aparece en otro proyecto: así funciona el alcance. Los servidores con alcance project viven en el .mcp.json de ese repo; cambia al alcance user para una instalación en toda la máquina.
- 5El servidor conecta pero nunca se usa: nómbralo en el prompt — «usa context7 para revisar la documentación» — o agrega una memoria en CLAUDE.md, porque sin indicación los modelos agarran sus herramientas integradas de siempre.
Cuando nada funciona: claude mcp remove name, reinicia la terminal y agrega el servidor de nuevo con el transporte que sabes que funciona — la variante HTTP remota es la más predecible.