MCP Inspector - Depura servidores del Protocolo de contexto de modelo
MCP Inspector es la herramienta visual oficial de prueba y depuración para servidores del Protocolo de contexto de modelo. Cuando estás construyendo un servidor MCP, necesitas ver qué expone realmente y cómo responde — Inspector se conecta a tu servidor, enumera sus herramientas, recursos e indicaciones, te permite invocar cada uno con argumentos arbitrarios, y muestra los mensajes JSON-RPC sin procesar fluyendo en ambas direcciones. Es la forma más rápida de verificar que un servidor funciona antes de conectarlo a Claude, Cursor u otro cliente.
Ejecutándolo
| Método | Comando |
|---|
| npx (sin instalar) | npx @modelcontextprotocol/inspector |
| Con tu servidor | npx @modelcontextprotocol/inspector node build/index.js |
| Servidor Python | npx @modelcontextprotocol/inspector uv run server.py |
| Servidor remoto/SSE | lanza, luego ingresa la URL en la UI |
| UI | se abre en el navegador (por defecto http://localhost:6274) |
Tipos de conexión
| Transporte | Usar |
|---|
| STDIO | Servidor local ejecutado como subproceso (más común) |
| SSE | Servidor remoto sobre Server-Sent Events |
| HTTP transmitible | Transporte remoto moderno |
# Inspecciona un servidor stdio local, pasando args y env
npx @modelcontextprotocol/inspector \
-e API_KEY=abc123 \
node build/index.js --verbose
La interfaz
| Pestaña | Muestra |
|---|
| Herramientas | Cada herramienta, su esquema JSON y un formulario para llamarla |
| Recursos | Recursos expuestos y sus contenidos |
| Indicaciones | Plantillas de indicaciones y sus argumentos |
| Notificaciones | Mensajes iniciados por servidor/registros |
| Historial | Cada par de solicitud/respuesta |
Prueba de herramientas
| Paso | Acción |
|---|
| 1 | Abre la pestaña Herramientas; confirma que tu herramienta está listada |
| 2 | Verifica que el esquema de entrada se renderiza correctamente (tipos, campos requeridos) |
| 3 | Llena el formulario generado e invoca |
| 4 | Inspecciona el contenido retornado y cualquier bandera isError |
| 5 | Lee el JSON-RPC sin procesar en Historial para depurar problemas de forma |
Este bucle atrapa los errores MCP más comunes: un esquema malformado, una herramienta que retorna la forma equivocada de contenido, o un error no manejado.
Qué verificar antes de entregar
| Verificación | Por qué |
|---|
| Los nombres de herramienta son únicos/descriptivos | Los clientes los exponen al modelo |
| Las descripciones explican cuándo usar la herramienta | Impulsa selección correcta del modelo |
| El esquema de entrada es preciso | Evita llamadas malformadas |
Los errores retornan isError con un mensaje | El modelo puede recuperarse |
| Las salidas grandes están paginadas/truncadas | Evita explotar la ventana de contexto |
| Los recursos tienen URIs estables | Los clientes los cachean/referencian |
Consejos de depuración
| Síntoma | Mira |
|---|
| El servidor no se conecta | Comando/args; stderr en la terminal de lanzamiento |
| Herramienta faltante | Código de registro; reinicia el servidor |
| El esquema se renderiza de manera extraña | Tipos de JSON Schema en la definición de herramienta |
| El cliente se comporta diferentemente | Compara JSON-RPC sin procesar en Historial |
| Error dependiente de env | Re-lanza Inspector con -e KEY=value |
Flujos de trabajo comunes
# Bucle de desarrollo y prueba para un servidor MCP de TypeScript
npm run build && npx @modelcontextprotocol/inspector node build/index.js
# Prueba un servidor Python con uv
npx @modelcontextprotocol/inspector uv run my_server.py
# Verifica un servidor SSE remoto antes de agregarlo a un cliente
npx @modelcontextprotocol/inspector # elige SSE, pega la URL
MCP Inspector vs alternativas
| Enfoque | Compromiso |
|---|
| MCP Inspector | Propósito específico, visual, muestra protocolo sin procesar |
| Conectar a cliente real | Realista pero bucle de retroalimentación lento |
| JSON-RPC escrito a mano | Control total, tedioso |
| Pruebas unitarias | Rápido y repetible; empareja con Inspector para exploración |
Usa Inspector mientras construyes, luego agrega pruebas automatizadas; ve servidores MCP para patrones de implementación de servidor.
Recursos
