MCP Inspector con npx y CLI: cómo probar un servidor MCP

Un servidor MCP puede arrancar sin un solo error y aun así no servir de nada. El proceso está en marcha, el registro no muestra nada y el cliente al que lo conectas muestra una lista de herramientas vacía o un mensaje vago de "failed to connect". Antes de culpar al cliente, prueba el servidor por separado. MCP Inspector es la herramienta oficial del proyecto Model Context Protocol para ese trabajo: hace de cliente, realiza el handshake y te permite listar y llamar a todo lo que expone tu servidor. Este artículo muestra cómo lanzarlo con npx, cómo manejarlo desde la CLI, cómo leer sus códigos de salida y cómo corregir los errores que más tiempo hacen perder.

💡 Comprobación de versión: La mayoría de tutoriales en línea describen Inspector v1. La última versión en npm en el momento de escribir esto es 2.9.0, y la v2 cambió los puertos, las variables de entorno, los flags y los códigos de salida. Todos los comandos de abajo siguen la documentación de la v2.

Qué hace MCP Inspector

Inspector es un cliente MCP pensado para depurar. Arranca tu servidor (stdio) o se conecta a él (HTTP o SSE), ejecuta el handshake initialize y te muestra exactamente lo que devuelve. No hay ningún modelo de lenguaje en medio, así que cuando algo falla sabes que el problema está en el servidor o en la conexión, no en el comportamiento del prompt.

El handshake que comprueba

La primera llamada, initialize, demuestra que el servidor habla MCP. La respuesta trae cuatro datos que conviene leer línea por línea:

• serverInfo: el nombre y la versión que informa tu servidor.
• protocolVersion: la revisión del protocolo que ambas partes acordaron.
• capabilities: qué funciones existen, como herramientas, recursos y prompts.
• instructions: texto opcional que el servidor entrega a los clientes.

Si capabilities no tiene una entrada tools, ningún cliente mostrará una sola herramienta, por muchas que hayas registrado en el código. Esa única comprobación explica una buena parte de los casos de "mis herramientas no aparecen".

Interfaz web, CLI y TUI

Un paquete, tres interfaces. El flag del modo debe ir primero, justo después del nombre del paquete.

Usa la interfaz web mientras construyes y la CLI cuando necesites una respuesta que puedas repetir.

Lánzalo con npx

No hay nada que instalar. npx descarga el paquete, lo ejecuta y pasa todo lo que va después del nombre del paquete al servidor que quieres probar. Una primera ejecución sensata lleva una línea y un minuto.

Versión de Node y puertos

La v2 necesita Node.js 22.19.0 o posterior. Ejecuta node --version antes que nada, porque un entorno de ejecución antiguo es lo primero que hay que descartar.

Los cambios de puertos y variables afectan a quien sigue publicaciones antiguas, así que aquí tienes la comparativa breve:

Cambia el puerto de la interfaz web con CLIENT_PORT, un entero fijo entre 1 y 65535. La v2 también reserva el 6275 para el sandbox de MCP Apps y el 6278 para el servidor de origen de la aplicación, así que mantén ambos libres.

CLIENT_PORT=6280 npx @modelcontextprotocol/inspector node build/index.js

Copiar prompt

En PowerShell de Windows, define primero la variable con $env:CLIENT_PORT = "6280" y después ejecuta la misma línea npx.

Pasar argumentos y variables de entorno

Para un servidor Node ya compilado, pon el comando justo después del nombre del paquete:

npx @modelcontextprotocol/inspector node build/index.js

Copiar prompt

Las variables de entorno se pasan con -e:

npx @modelcontextprotocol/inspector -e API_TOKEN=your-token -- node build/index.js

Copiar prompt

Un servidor TypeScript sin paso de compilación funciona igual, por ejemplo npx @modelcontextprotocol/inspector tsx src/index.ts. La mayoría de proyectos envuelven la línea en un script de npm para que todo el equipo ejecute el mismo comando:

{
  "scripts": {
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  }
}

Copiar prompt

💡 El doble guion cambia de significado. En el modo web y TUI, todo lo que va después de -- llega a tu servidor. En el modo CLI, todo lo que va antes de -- es el destino y todo lo que va después es una opción de Inspector. En el modo CLI, el comando del servidor también debe ir primero: --cli --method tools/list node build/index.js descarta el destino en silencio.

El token detrás de la interfaz

La v2 crea un token de API aleatorio en cada arranque y lo exige en todas las rutas /api/*. Una página abierta sin él se rechaza. Define MCP_INSPECTOR_API_TOKEN tú mismo si quieres un valor estable, y reinicia si una pestaña se queja, porque el token antiguo murió con el proceso anterior.

El servidor web escucha por defecto en 127.0.0.1 mediante HOST. Abrirlo a otras interfaces requiere un DANGEROUSLY_BIND_ALL_INTERFACES explícito, y DANGEROUSLY_OMIT_AUTH=true desactiva por completo la comprobación del token. Inspector arranca procesos locales en tu nombre, así que trata el token como una contraseña y no dejes estas dos excepciones en equipos compartidos.

Usar un archivo de configuración

Escribir el comando se vuelve pesado cuando un servidor necesita tres argumentos y dos variables de entorno. Guárdalos en un archivo y elige el servidor por su nombre. Existen dos flags, y son excluyentes:

El catálogo por defecto está en ~/.mcp-inspector/mcp.json. Ninguno de los dos flags puede combinarse con un destino ad hoc en la misma línea de comandos.

Entradas stdio

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_TOKEN": "your-token" },
      "cwd": "/path/to/server"
    }
  }
}

Copiar prompt

Mantén command y cada elemento de args como entradas separadas. Inspector los lanza directamente en lugar de unirlos en una sola cadena, lo que conserva los límites de los argumentos cuando una ruta contiene espacios.

Entradas HTTP y SSE

{
  "mcpServers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.internal.example/mcp",
      "headers": { "X-Tenant": "acme" }
    }
  }
}

Copiar prompt

El campo type acepta stdio, http (HTTP en streaming) o sse. En la CLI eliges una entrada con --server:

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server my-server --method tools/list

Copiar prompt

--server solo selecciona un servidor en el modo CLI. El cliente web avisa e ignora la opción al cargar un archivo, y la TUI la rechaza como opción desconocida.

Probar un servidor MCP desde la CLI

El modo CLI prescinde del navegador e imprime la respuesta en stdout, lo que lo convierte en la herramienta adecuada para comprobaciones rápidas y para todo lo que quieras automatizar. Cada comando tiene la misma forma: primero el destino, después --method y luego lo que necesite ese método.

Lista primero las herramientas

Empieza siempre preguntando qué cree el servidor que ofrece:

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

Copiar prompt

Cambia el método por resources/list o prompts/list para comprobar las otras dos funciones. Un servidor remoto necesita una dirección y un transporte, y un token bearer si está protegido:

npx @modelcontextprotocol/inspector --cli \
  --transport http --server-url https://example.com/mcp \
  --header 'Authorization: Bearer <token>' \
  --method tools/list

Copiar prompt

Compara los nombres de la salida con lo que espera tu cliente. Una herramienta registrada como generateImage pero solicitada como generate_image es un caso clásico, y basta un comando para detectarlo.

Llama a una herramienta con argumentos JSON

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name generate_image \
  --tool-args-json '{"prompt":"a ceramic mug on an oak desk, soft window light","aspect_ratio":"16:9"}'

Copiar prompt

--tool-args-json recibe un objeto JSON y no aplica ninguna conversión, así que los números siguen siendo números y los booleanos siguen siendo booleanos. Para una prueba rápida, --tool-arg prompt="a red door" es más corto, pero sus valores se interpretan como JSON cuando son válidos, así que una cadena que parece un número se convierte en número. Cuando los tipos importan, usa la forma JSON.

💡 Nota para Windows: PowerShell 5.1 de Windows elimina las comillas dobles internas del JSON que se pasa a programas nativos. Escapa cada una con una barra invertida, o usa --tool-arg para valores cortos.

Lee los códigos de salida

La CLI informa del resultado en su código de salida, de modo que un script nunca tiene que extraer texto para saber qué ocurrió.

El código 5 es el más importante para las pruebas. Una herramienta que falla de forma limpia ahora hace fallar el comando, así que inspector --cli ... && next-step se detiene donde la v1 habría seguido. Las conexiones agotan su tiempo a los 15 segundos por defecto en las ejecuciones ad hoc, y --connect-timeout <ms> eleva ese límite cuando tu servidor carga una base de datos o un modelo al arrancar.

Ejecutar comprobaciones de Inspector en CI

Una prueba de humo útil verifica cuatro cosas: el servidor se conecta, la herramienta existe, una llamada válida tiene éxito y una llamada no válida falla. Cuatro comandos, sin navegador, y una versión defectuosa nunca llega a los usuarios.

Fija la versión

Fija una versión exacta en CI, nunca un rango como @2.x, porque los flags y los códigos de salida cambiaron entre versiones principales:

npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js --method initialize

Copiar prompt

Dale a cada trabajo su propio almacén de tokens para que una ejecución nunca reutilice el estado de inicio de sesión de otra:

export MCP_STORAGE_DIR="$(mktemp -d)"
export MCP_INSPECTOR_OAUTH_STATE_PATH="$MCP_STORAGE_DIR/oauth.json"

Copiar prompt

Verificar con jq

Añade --format json y la CLI imprime un único objeto JSON con un campo result, listo para jq. Conviene conocer dos trampas. Nunca mezcles stderr con stdout con 2>&1 al analizar, porque los diagnósticos acaban dentro del JSON. Y captura el estado de salida antes de encadenar con un pipe, porque una tubería informa del estado de su último comando, lo que oculta una CLI fallida tras un jq correcto.

#!/usr/bin/env bash
set -u
INSPECT="npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js"

# 1. The handshake works
$INSPECT --method initialize --format json > init.json || exit 1

# 2. The tool exists (status captured before the pipe)
tools=$($INSPECT --method tools/list --format json); code=$?
[ "$code" -eq 0 ] || { echo "tools/list failed with $code"; exit "$code"; }
echo "$tools" | jq -e '.result.tools | map(.name) | index("generate_image")' > /dev/null || exit 1

# 3. A valid call succeeds
$INSPECT --method tools/call --tool-name list_models --tool-args-json '{}' \
  --format json > call.json || exit 1

# 4. An invalid call fails
if $INSPECT --method tools/call --tool-name generate_image --tool-args-json '{}' \
  > /dev/null 2>&1; then
  echo "tool accepted empty input"; exit 1
fi

Copiar prompt

La cuarta comprobación es la que la gente se salta. Un servidor que acepta un prompt vacío y devuelve una imagen en blanco superará todas las pruebas positivas que escribas.

Corrige los errores que vas a ver

La mayoría de fallos encajan en unos pocos patrones. Identifica primero el síntoma y después lee la sección que lo explica.

Contaminación de stdout en stdio

El transporte stdio transporta sus mensajes JSON-RPC por stdout, y el protocolo indica que un servidor no debe escribir allí nada que no sea un mensaje MCP válido. Una sola console.log perdida, un banner de arranque o una dependencia que imprime una advertencia corrompe el flujo. El handshake entonces falla con errores de parseo o simplemente se queda colgado.

Para arreglarlo, envía cada línea de registro a stderr (console.error en Node, sys.stderr en Python). Para localizar al culpable, ejecuta el comando del servidor por sí solo: un servidor stdio sano no imprime nada hasta que un cliente le habla.

Transporte no detectado

La v2 ya no adivina. Solo infiere el transporte cuando la ruta de la URL termina en /mcp o /sse, y en cualquier otro caso hay que indicarlo con el flag explícito:

npx @modelcontextprotocol/inspector --cli --server-url https://example.com/api \
  --transport http --method tools/list

Copiar prompt

Cuando un mensaje de error no te dice nada, pega la salida de stderr y el esquema de tu herramienta en Claude Sonnet 5 o en GPT 5.6 Sol y pide las tres causas más probables. Ambos leen bien las trazas de error, aunque la respuesta siempre la verificas con Inspector.

Probar un servidor de generación de imágenes

Los servidores que generan medios se comportan de forma distinta en las pruebas. Las llamadas son lentas, pueden costar dinero y el trabajo suele ejecutarse en segundo plano. La API para desarrolladores de PicassoIA muestra el patrón con claridad. Es al estilo Replicate: creas una predicción con POST /v1/models/{owner}/{name}/predictions en https://api.picassoia.com/v1, te autenticas con un token bearer, consultas GET /v1/predictions/{id} y lees el resultado cuando termina.

En el momento de escribir esto, la API y la conexión MCP exponen los mismos cuatro modelos: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video y Seedance 2.5 Lite. Una cuenta permite 5 predicciones simultáneas, compartidas entre tokens y conexiones MCP, con prompts de hasta 4.000 caracteres.

💡 Prueba en serie. Un bucle de llamadas a herramientas en una sola sesión de Inspector puede ocupar las cinco plazas y dejar sin recursos a tu cliente real. Ejecuta las pruebas de imagen una llamada cada vez.

Las herramientas asíncronas necesitan una herramienta de estado

Una herramienta que inicia un trabajo debería devolver un ID en segundos, y una segunda herramienta debería informar del progreso. Prueba ambas mitades por separado:

• La llamada de inicio responde rápido con un ID en lugar de mantener la conexión abierta durante minutos.
• La llamada de estado acepta ese ID e informa de un estado de progreso y de un estado final.
• Un trabajo fallido vuelve como resultado con isError: true, no como una llamada que se queda colgada.
• Un ID incorrecto produce el código de salida 5, no una caída del proceso del servidor.
• La URL de salida responde con estado 200 y un tipo de contenido de imagen cuando la consultas.

Esa última comprobación es la más barata, y detecta el fallo que los lectores notan primero: una imagen rota en una página publicada.

Haz tu primera imagen a continuación

Ahora tienes una forma de demostrar que un servidor funciona antes de que alguien dependa de él. El mismo hábito rinde en el terreno creativo: ejecuta una prueba pequeña, lee el resultado y cambia una cosa cada vez.

Abre Picasso IA y prueba el ciclo tú mismo. Escribe un prompt de una frase en PicassoIA Image, afina el resultado con PicassoIA Image Editor Pro y luego da vida a la imagen fija con PicassoIA Video. Cambia la lente, la luz o el sujeto entre ejecuciones y compara los resultados lado a lado. Cinco comandos de este artículo merecen la pena tenerlos junto a la terminal:

• --method initialize para confirmar el handshake.
• --method tools/list para confirmar los nombres de las herramientas.
• --method tools/call --tool-args-json para confirmar el comportamiento.
• --format json más jq para verificar la respuesta.
• El código de salida, que siempre se lee antes que la salida.