Registrar un MCP server en Claude Code con claude mcp add

Q: ¿Necesito compilar TypeScript para registrar el server?

No. Para desarrollo local, npx tsx /ruta/src/index.ts funciona igual. Compilar a JS es más fiable para uso continuado porque no dependes de que tsx esté disponible, pero para iterar no hace falta.

Q: ¿Cuál es la diferencia entre los scopes local, user y project?

local es el valor por defecto y limita el server al proyecto actual, solo para ti. user lo hace disponible en todos tus proyectos. project lo escribe en un .mcp.json en la raíz del repositorio, así que viaja por control de versiones y lo tiene todo el equipo. Si el server no aparece donde esperabas, casi siempre es un scope mal elegido.

Q: ¿Cuál es la diferencia entre stdio y HTTP como transporte?

stdio es el modo local: Claude Code lanza tu server como proceso hijo y se comunican por stdin/stdout. Es lo más simple y suficiente para tools personales o de equipo. El transporte HTTP es para servers remotos que expones como servicio — por ejemplo, un MCP server de empresa desplegado en un servidor. Se registra con --transport http .

Ya tienes tu MCP server escrito y compilado. Arranca sin errores, los tools están declarados, y ahora quieres usarlo desde Claude Code.

Ese último paso parece trivial y es donde se atasca casi todo el mundo. No porque el comando sea difícil, sino porque claude mcp add tiene tres scopes distintos que deciden en qué proyectos aparece tu server y con quién se comparte. Elegir mal el scope se manifiesta como un server que "no funciona" cuando en realidad está perfectamente registrado — en otro sitio.

Esta guía es el registro y nada más: el comando, los scopes, cómo pasar variables de entorno y qué mirar cuando no conecta.

El comando

La sintaxis para un server local por stdio es esta:

claude mcp add [opciones] <nombre> -- <comando> [args...]

Aplicado a un server compilado en tu máquina:

claude mcp add --transport stdio github-issues -- node /ruta/absoluta/build/index.js

El -- no es decorativo. Separa las opciones de Claude Code de lo que se le pasa a tu server. Todo lo que va después se ejecuta tal cual, sin que Claude Code intente interpretarlo:

# Sin --, Claude Code intentaría parsear --port como opción suya
claude mcp add --transport stdio myserver -- python server.py --port 8080

Usa siempre ruta absoluta. El comando se resuelve desde el directorio donde arranque Claude Code, no desde donde ejecutaste claude mcp add.

Si prefieres no compilar mientras desarrollas, npx tsx funciona igual:

claude mcp add --transport stdio github-issues -- npx tsx /ruta/src/index.ts

Scopes: dónde queda registrado tu server

Aquí es donde se pierde la gente. El flag -s / --scope decide dónde se guarda la configuración, y eso determina en qué proyectos ves el server.

Scope	Disponible en	Compartido con el equipo	Se guarda en
`local` (por defecto)	Solo el proyecto actual	No	`~/.claude.json`
`project`	Solo el proyecto actual	Sí, por control de versiones	`.mcp.json` en la raíz
`user`	Todos tus proyectos	No	`~/.claude.json`

# local (por defecto): solo este proyecto, solo tú
claude mcp add --transport stdio github-issues -- node /ruta/build/index.js

# user: disponible en todos tus proyectos
claude mcp add --scope user --transport stdio github-issues -- node /ruta/build/index.js

# project: se escribe en .mcp.json y viaja con el repositorio
claude mcp add --scope project --transport stdio github-issues -- node /ruta/build/index.js

El caso típico de confusión: registras el server en scope local estando en un proyecto, abres Claude Code en otro directorio, y el server no aparece. No se ha roto nada — local significa literalmente este proyecto. Si lo quieres en todas partes, es --scope user.

Y si trabajas en equipo, --scope project es el que te interesa: escribe un .mcp.json en la raíz que puedes commitear, y tus compañeros lo tienen al clonar.

Variables de entorno

Para un server que necesita credenciales, pásalas con --env (o -e) en el registro:

claude mcp add --env GITHUB_TOKEN=ghp_xxx --transport stdio github-issues \
  -- node /ruta/absoluta/build/index.js

La variable se define en el entorno del server, no en el de Claude Code. Dentro de tu código la lees con process.env.GITHUB_TOKEN como siempre.

Ojo con esto si usas --scope project: ese .mcp.json acaba en el repositorio. No metas ahí tokens en claro.

Comprobar que ha quedado registrado

claude mcp list

Deberías ver github-issues en el listado.

Un detalle que confunde: el estado Pending approval solo aparece en servers de scope project que vienen de un .mcp.json. Es la aprobación que Claude Code te pide antes de ejecutar algo que ha llegado por el repositorio, no por tus manos. Un server que añadiste tú con claude mcp add en scope local o user no pasa por esa aprobación.

Para inspeccionar la configuración concreta de uno:

claude mcp get github-issues

Cómo probarlo desde una sesión de Claude Code

Abre Claude Code en el directorio donde registraste el server y escribe algo que active tu tool:

Lista los issues abiertos del repo microsoft/vscode

Claude detecta que tiene acceso al tool list_issues, lo llama con { owner: "microsoft", repo: "vscode", state: "open" }, y devuelve la lista formateada directamente en el chat.

Sin salir del editor. Sin copiar y pegar. Sin fricción.

Cuándo no llega a conectar

Por orden de frecuencia, esto es lo que suele pasar:

Ruta relativa en el comando. Se resuelve desde donde arranca Claude Code, no desde donde registraste. Usa ruta absoluta.
Scope equivocado. El server está registrado, pero en otro proyecto. Comprueba con claude mcp list desde el directorio en el que estás trabajando.
Un console.log en el server. En transporte stdio, stdout es el canal JSON-RPC exclusivo del protocolo. Un solo console.log corrompe el flujo y produce un error de parseo que no dice nada útil. Todo el logging va a console.error.
El server tarda en arrancar. Ajusta el timeout con MCP_TIMEOUT, en milisegundos: MCP_TIMEOUT=10000 claude.

Antes de dar por rota la integración, aísla el server con MCP Inspector, la herramienta oficial:

npx @modelcontextprotocol/inspector node /ruta/build/index.js

Abre una interfaz web donde ves los tools registrados y puedes invocarlos a mano. Si ahí funciona y en Claude Code no, el problema es el registro, no el server.

Ir más allá: cuándo crear tu propio MCP server

Esta es la pregunta real. El ecosistema de MCP servers públicos ya tiene integraciones para GitHub, Slack, Notion, bases de datos, filesystems y decenas más. No construyas lo que ya existe.

Crea el tuyo cuando:

Tienes una API interna que nadie más va a integrar.
Necesitas transformar o filtrar datos antes de que lleguen al modelo — la lógica de negocio importa.
Quieres controlar exactamente qué puede hacer Claude y qué no en tu entorno.
Estás construyendo un producto y necesitas que Claude interactúe con él de forma programática.

Si todavía no tienes claro qué es MCP ni qué expone realmente un server, aquí lo explico desde cero.

Y si quieres profundizar en este modelo de trabajo — construir con IA de forma estructurada, con specs, con MCP servers propios, con agentes que hacen trabajo real — en el curso Construye con IA: De la Idea al Producto con Claude Code trabajamos exactamente este flujo. Desde la idea hasta tener algo en producción.

Preguntas frecuentes

¿Necesito compilar TypeScript para registrar el server?

No. Para desarrollo local, npx tsx /ruta/src/index.ts funciona igual. Compilar a JS es más fiable para uso continuado porque no dependes de que tsx esté disponible, pero para iterar no hace falta.

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

local es el valor por defecto y limita el server al proyecto actual, solo para ti. user lo hace disponible en todos tus proyectos. project lo escribe en un .mcp.json en la raíz del repositorio, así que viaja por control de versiones y lo tiene todo el equipo. Si el server no aparece donde esperabas, casi siempre es un scope mal elegido.

¿Cuál es la diferencia entre stdio y HTTP como transporte?

stdio es el modo local: Claude Code lanza tu server como proceso hijo y se comunican por stdin/stdout. Es lo más simple y suficiente para tools personales o de equipo. El transporte HTTP es para servers remotos que expones como servicio — por ejemplo, un MCP server de empresa desplegado en un servidor. Se registra con --transport http <nombre> <url>.

¿Mis tools pueden leer archivos del sistema o ejecutar comandos?

Sí. Un MCP server tiene acceso completo al sistema donde se ejecuta: puede leer archivos con fs, lanzar procesos con child_process y hacer peticiones de red. Eso es también la responsabilidad — el server corre con los permisos del usuario que lo lanza, así que diseña los tools con cuidado y no expongas capacidades destructivas sin confirmación.

¿Funciona con Claude Desktop o solo con Claude Code?

Funciona con cualquier cliente MCP compatible. Claude Desktop usa claude_desktop_config.json en lugar de claude mcp add, pero el server es exactamente el mismo. También es compatible con Cursor, Continue y cualquier cliente que implemente el protocolo. Ese es el punto de MCP: escribes el server una vez y lo consumes desde donde quieras.

Conclusión

Registrar un MCP server es un comando, pero el scope es lo que decide si lo vas a encontrar donde esperas. local para lo tuyo en un proyecto, user para lo tuyo en todos, project para lo del equipo.

Y cuando algo no conecte, aísla antes de investigar: MCP Inspector te dice en treinta segundos si el problema está en el server o en cómo lo registraste.

Si estás construyendo flujos de trabajo con agentes de IA y quieres ir más allá de los MCP servers públicos, en Dominicode Labs publicamos proyectos completos, code reviews y recursos exclusivos para developers que construyen con IA en serio.

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.