MCP Inspector: cómo probar y depurar servidores MCP localmente

En este artículo vas a ver:

• Qué es MCP Inspector y cuándo usarlo.
• Cómo instalar y ejecutar en los tres modos: web, CLI y TUI.
• Cómo inspeccionar un servidor local o remoto.
• Cómo usar MCP Inspector en CI y en flujos automatizados.
• Los cuidados con secretos y el almacenamiento local.

O que é o MCP Inspector

MCP Inspector es la herramienta de desarrollo de referencia para probar y depurar servidores MCP. Permite listar herramientas, llamar funciones, leer recursos, inspeccionar prompts y seguir el tráfico JSON-RPC entre cliente y servidor.

La herramienta viene en un solo paquete, @modelcontextprotocol/inspector, que instala un binario llamado mcp-inspector. Tres clientes comparten el mismo núcleo: web (interfaz gráfica en el navegador), CLI (scriptable, para automatización) y TUI (interfaz de terminal). Todos usan los mismos transportes, archivos de configuración y negociación de protocolo.

El paquete también instala mcpdo, un cliente experimental que mantiene una conexión abierta entre varios comandos.

Pré-requisitos

MCP Inspector requiere Node.js 22.19.0 o más reciente. No es necesario instalar nada globalmente: todo se ejecuta vía npx.

Si vas a depurar un servidor Python, instala uv o pipx para ejecutar el servidor con uvx o python. Si vas a depurar un servidor Node, ten node y npm disponibles.

Como rodar no modo web

El modo web es el predeterminado. Abre una interfaz gráfica en el navegador y es el modo más completo.

Para inspeccionar un servidor local, pasa el comando que lo inicia como argumento:

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

Para abrir la interfaz sin destino y agregar servidores desde la propia UI:

$ npx @modelcontextprotocol/inspector

El comando imprime una URL con un token de API por ejecución y abre el navegador. El token protege las rutas /api, porque el servidor puede ejecutar procesos en tu máquina. No escribas localhost:6274 de memoria: usa la URL impresa.

Para desactivar la apertura automática del navegador, define MCP_AUTO_OPEN_ENABLED=false.

Como rodar no modo CLI

El modo CLI es scriptable y devuelve resultados en texto o JSON. Es el modo ideal para CI, pipelines de shell y agentes de código que necesitan verificar un cambio rápidamente.

Para listar las herramientas de un servidor:

$ npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

Para llamar una herramienta y extraer el resultado con jq:

$ npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \
  --method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result

Cada ejecución se conecta, hace una petición y finaliza. Para flujos que requieren una sesión abierta (tasks, subscriptions, elicitation), usa mcpdo.

Como rodar no modo TUI

El modo TUI es una interfaz de terminal interactiva, útil cuando no hay navegador disponible.

$ npx @modelcontextprotocol/inspector --tui node build/index.js

La navegación y los atajos de teclado están documentados en la página de referencia del TUI.

Inspecionando servidores locais e remotos

Para un servidor stdio, pasa el comando de inicialización como argumento posicional. Usa -- para separar los argumentos del servidor de los argumentos del Inspector:

$ npx @modelcontextprotocol/inspector node build/index.js -- --verbose --config /etc/myserver.conf

Para pasar variables de entorno y directorio de trabajo:

$ npx @modelcontextprotocol/inspector -e API_KEY=abc123 -e REGION=us-east-1 --cwd ~/projects/my-server \
  node build/index.js

Para un servidor HTTP o SSE remoto:

$ npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

El Inspector soporta los transportes http (Streamable HTTP) y sse. Si el servidor responde 401, el Inspector ejecuta el flujo OAuth descrito en la documentación de autorización e intenta de nuevo.

Lee siempre el README del servidor antes de inspeccionar. Cada servidor exige comandos y argumentos diferentes.

Usando en CI y en flujos automatizados

El modo CLI devuelve códigos de salida distintos para cada situación, lo que facilita la integración en pipelines. Usa --format json para obtener salida estructurada y --strict para convertir la verificación de portabilidad de schema en un gate.

Un flujo típico de smoke test:

1. Conecta con initialize para confirmar que el servidor responde.
2. Lista herramientas con tools/list.
3. Llama a una herramienta con tools/call y verifica el resultado.
4. Haz assertions con jq o con el código del pipeline.

El Inspector también importa configuraciones de clientes MCP existentes, lo que facilita reutilizar la misma lista de servidores en desarrollo y en CI.

Seguridad y secretos

El Inspector almacena secretos (tokens OAuth, client secrets y valores de env de servidores stdio) en el keychain del sistema operativo cuando está disponible. En máquinas sin keychain, como Linux sin libsecret, sesiones SSH, Termux y contenedores, los secretos van a ~/.mcp-inspector/secrets.json, sin cifrado, a menos que proporciones una clave.

El token de API por lanzamiento protege las rutas /api, pero no es un mecanismo de autenticación fuerte. En máquinas donde otros procesos pueden alcanzar el puerto, configura DANGEROUSLY_OMIT_AUTH con cuidado.

Para servidores stdio, el stderr del proceso aparece en la pestaña Console, que es donde la mayoría de los servidores coloca sus diagnósticos. Revisa esa pestaña primero cuando una conexión falle sin motivo aparente.

Eras de protocolo

El Inspector soporta dos eras de protocolo: legacy y modern (2026-07-28). El estándar es legacy. Para probar comportamiento moderno, define la era en Server Settings o pasa --protocol-era legacy|auto|modern en la línea de comandos.

La documentación detalla cómo cambia cada pestaña entre las eras, incluyendo headers Mcp-* estandarizados y tareas.