MCP Inspector: cómo probar y depurar servidores MCP antes de conectar un agente
MCP Inspector no sustituye tus tests: convierte el protocolo real en una superficie comprobable. Úsalo para detectar tools que no se anuncian, schemas que mienten, transportes incompatibles y permisos que tu suite unitaria no ve.
MCP Inspector no sustituye tus tests: convierte el protocolo real en una superficie comprobable. Úsalo para detectar tools que no se anuncian, schemas que mienten, transportes incompatibles y permisos que tu suite unitaria no ve.
`MCP Inspector` es la herramienta oficial para inspeccionar, probar y depurar un servidor Model Context Protocol (MCP). La keyword principal es `MCP Inspector`; la intención es técnica y práctica: un developer quiere comprobar un servidor real antes de entregárselo a Claude Code, Cursor, VS Code o a un agente propio.
Checklist
Qué prueba MCP Inspector y qué no
El Inspector actúa como cliente MCP y ofrece tres superficies: web, CLI y TUI. Puede abrir un proceso local por `stdio` o conectar con un endpoint remoto, negociar la versión que corresponda y ejecutar operaciones como listar tools, recursos y prompts o llamar una tool. Eso prueba el protocolo y el empaquetado que verá un host, no solo una función TypeScript aislada.
No prueba por sí solo tu autorización de negocio, el aislamiento entre tenants, la calidad de la decisión del modelo ni el comportamiento del proveedor que hay detrás. Tampoco convierte una tool mutante en segura. Es la capa de contrato: confirma que el servidor expone exactamente lo que prometes y que falla de forma útil cuando recibe entradas inválidas.
La diferencia importa desde MCP 2026-07-28. En el flujo moderno se abandona el handshake `initialize` y aparece `server/discover`; las peticiones llevan metadata por llamada y Streamable HTTP es stateless a nivel de protocolo. Si mantienes tests que asumen sesiones antiguas, pueden pasar contra un fixture legado y fallar con un cliente moderno.
Smoke test reproducible por CLI
¿Te está sirviendo? Hay una dosis cada semana
Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratisPara un servidor `stdio`, la forma más rápida de probar el wire protocol es ejecutar el Inspector como cliente, no arrancar una ventana y hacer clic. El comando siguiente lista las tools de un build ya compilado; fija Node y dependencias en el lockfile para que CI y tu portátil ejecuten el mismo artefacto.
<div style="margin:28px 0;border:1px solid #dbe3ef;border-radius:12px;overflow:hidden;background:#0f172a;"> <div style="padding:10px 14px;background:#111827;color:#cbd5e1;font:13px Consolas,monospace;">package.json</div> <pre style="margin:0;padding:18px;overflow:auto;color:#e5e7eb;font:13px/1.55 Consolas,monospace;"><code>{ "scripts": { "build": "tsc -p tsconfig.json", "mcp:tools": "npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list" } }</code></pre> </div>
Ese comando prueba que el proceso arranca, que no ensucia `stdout` con logs y que responde al catálogo MCP. En CI redirígelo a un JSON de artefacto, analiza el exit code y comprueba que aparecen solo las tools permitidas. Los logs de diagnóstico van a `stderr`; escribir texto de debug en `stdout` rompe `stdio` aunque el servidor parezca sano localmente.
Prueba una llamada real y sus errores
`tools/list` no detecta una tool registrada con argumentos mal definidos o una credencial usada demasiado pronto. Selecciona por tool un caso exitoso con fixture y al menos dos fallos: argumentos inválidos y una decisión de autorización denegada. Para una tool de búsqueda, no necesitas un LLM: usa un índice falso que devuelva resultados conocidos y verifica el `structuredContent` validado.
Puntos a revisar
Lo que conviene comprobar
La CLI del Inspector permite invocar una tool con `--method tools/call`, `--tool-name` y `--tool-arg`. Mantén las entradas en un fichero o script del repo para que no haya JSON escapado y frágil en YAML. El test debe esperar una respuesta de error explícita o un código de negocio documentado; no debe aceptar que el proceso termine con cualquier texto que contenga 'denied'.
Un patrón útil es probar la misma llamada con dos identidades de prueba. La primera puede leer un documento de su tenant; la segunda recibe `permission_denied` sin que la respuesta revele si el documento existe. Esa aserción protege tanto confidencialidad como calidad de la experiencia del agente: un modelo que recibe un 403 claro no debería reintentar diez veces.
Checklist
Compatibilidad: prueba el servidor que publicas, no el que recuerdas
El Inspector v2 convive con servidores de la era antigua y de la moderna. La configuración, flags y el modo de apuntar a un servidor cambiaron respecto a v1, así que no copies un blog post sin fijar la versión y leer la ayuda del paquete instalado. El repositorio oficial incluye una guía de migración: úsala como parte de la actualización de dependencias.
Para remoto, prueba la URL y el transporte exactos que verá el host. Un endpoint que funciona contra `stdio` no demuestra CORS, cabeceras, proxy inverso, `Content-Type`, autenticación ni los requisitos del transporte HTTP. En MCP moderno las cabeceras de método y nombre permiten a gateways y rate limiters validar y enrutar sin inspeccionar el body; una prueba HTTP debe fallar cuando cabecera y request discrepan.
Mantén una matriz pequeña: transportes soportados × versión de protocolo × identidad de prueba × operación. No hace falta probar todos los hosts del mercado en cada commit. Sí hace falta una prueba de compatibilidad por rama de protocolo que prometes soportar y una prueba de regresión cuando subes SDK o Inspector.
Checklist
El Inspector también es una frontera de seguridad
La interfaz web del Inspector se apoya en un proxy local capaz de lanzar procesos y conectar con servidores MCP. No lo expongas a una red no confiable ni desactives su autenticación para evitar una molestia de desarrollo. El propio proyecto advierte que ese atajo puede permitir que una web maliciosa use tu máquina como puente hacia procesos locales.
En CI, ejecuta el Inspector contra un contenedor o proceso efímero con un usuario sin privilegios, directorio temporal y fixtures no sensibles. No pases tokens de producción por `-e`, no imprimas cabeceras de Authorization y no dejes un puerto expuesto entre jobs. Para un servidor remoto, usa una identidad de test con scopes mínimos y revócala igual que cualquier otro secreto de integración.
La prueba negativa más valiosa no es un payload exótico: es confirmar que la tool no puede ampliar sus propios permisos. Simula un argumento que pide otra cuenta, una URL privada o una operación de escritura y verifica que tu backend impone la política antes de que la tool llegue al proveedor.
El test de protocolo debe convivir con observabilidad. Asigna un `traceparent` de prueba, registra nombre de tool, latencia, resultado y motivo de denegación de forma redactada. Cuando una integración falla en un host real podrás unir el trace con la misma operación de CI en vez de pedir al modelo que reconstruya el incidente desde una conversación.
Preguntas frecuentes
¿Qué es MCP Inspector?
Es la herramienta oficial del ecosistema MCP para inspeccionar, probar y depurar servidores mediante una interfaz web, una CLI y una TUI. Actúa como cliente MCP para comprobar la conversación de protocolo real.
¿MCP Inspector sustituye Jest, pytest o pruebas de integración?
No. Complementa esas pruebas: valida que el build que expones habla MCP correctamente. Las reglas de negocio, aislamiento de datos, rendimiento y proveedores externos necesitan tests propios.
¿Puedo usar MCP Inspector en CI?
Sí, el modo CLI está pensado para automatización. Ejecútalo contra un proceso o contenedor efímero, analiza el resultado y conserva artefactos redactados; no conviertas la UI web en un paso interactivo de CI.
¿Debo desactivar la autenticación del proxy del Inspector?
No. El proxy puede iniciar procesos locales y conectarse a servidores; mantenlo limitado a localhost y usa su autenticación. Desactivarla es un riesgo, no una optimización.
¿Por qué falla un test MCP tras actualizar a 2026-07-28?
La era moderna elimina el handshake initialize y la sesión de transporte. Revisa qué versión promete tu servidor, deja que el cliente negocie o fija una matriz explícita y actualiza fixtures heredados.
¿Qué debo verificar en una tool mutante?
Además del schema, verifica scopes, identidad derivada en backend, idempotencia, confirmación humana cuando aplique, auditoría y que una identidad de otro tenant no pueda inferir datos ni ejecutar la acción.
Cómo añadir MCP Inspector a CI para un servidor MCP
- Definir el contrato. Documenta tools, resources y prompts públicos con schemas, efectos, scopes, límites y errores esperados.
- Compilar el artefacto. Ejecuta el build del servidor y prueba el binario o archivo resultante, no una ruta de desarrollo distinta.
- Arrancar con fixtures. Inicia el servidor en stdio o un contenedor efímero con datos controlados y sin secretos de producción.
- Listar superficies. Ejecuta Inspector CLI para consultar tools, resources y prompts y compara una salida normalizada con el contrato aprobado.
- Llamar una tool segura. Ejecuta una llamada representativa con argumentos válidos y valida structuredContent, límites y resultado de negocio.
- Añadir casos negativos. Prueba schema inválido, timeout, proveedor caído y dos identidades de test para confirmar autorización y aislamiento.
- Probar compatibilidad. Repite sobre cada transporte y versión MCP que declares soportar, especialmente tras actualizar SDK o Inspector.
- Cerrar el entorno. Recoge trazas y resultados redactados, detén el proceso efímero y falla el job si cambia el contrato o se filtran datos.
Fuentes y referencias
También te puede interesar
MCP en producción: seguridad y permisosMCP outputSchema y structuredContentOAuth 2.1 para servidores MCP remotosPlaywright MCP para testing de UIMCP Registry: publicar y descubrir servidoresRecibe una lectura semanal de herramientas IA para devs
Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratis
