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 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.

TL;DR

Úsalo en dos capas. La interfaz web es útil para descubrir una tool, ver argumentos y reproducir un fallo; el modo CLI es el que debes automatizar para probar tools/list, llamadas representativas, recursos y prompts en CI. Un host de agente no es una suite de tests: si ese es tu primer cliente, llegarás tarde a los errores de contrato.

Mi postura: un servidor MCP no está listo porque el Inspector consigue conectar una vez. Está listo cuando su catálogo, sus schemas, sus fallos esperados y sus límites de autorización se comprueban en un entorno sin secretos reales. La conexión feliz es el smoke test, no la definición de calidad.

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.

El Inspector comprueba la conversación real de protocolo; CI decide si ese resultado cumple el contrato y devuelve el cambio al servidor si no lo cumple.

El contrato mínimo antes de abrir un host

Escribe primero una tabla de contrato pequeña y revisable. Para cada tool declara nombre, descripción, inputSchema, campos de salida, efectos, scope requerido, timeout, máximo de elementos y errores recuperables. Si una tool necesita leer tickets del tenant, el tenant_id debe venir del token o del backend, no de un argumento que el modelo pueda cambiar.

Haz lo mismo para resources y prompts. Un recurso debe tener URI, MIME type y límites de tamaño que puedas verificar; un prompt debe declarar los argumentos obligatorios y no filtrar secretos en ejemplos. El Inspector te deja consultar esas superficies, pero la aserción importante vive en tu repositorio: compara la respuesta normalizada con el contrato que el equipo aprueba.

No hagas snapshot de párrafos enteros ni de IDs aleatorios. Normaliza orden, timestamps, trazas y URLs efímeras; afirma solo los campos que un cliente necesita para decidir. Un snapshot enorme enseña ruido y hace que una regresión importante se pierda entre cambios legítimos.

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 gratis

Para 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.

package.json

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "mcp:tools": "npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list"
  }
}

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.

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.

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.

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.

De Inspector a una puerta de calidad en CI

Divide la pipeline en cuatro jobs cortos: compilar y hacer unit tests; arrancar el servidor con fixtures; ejecutar Inspector CLI para catálogo, tools, resources y prompts; y correr pruebas negativas de autorización y límites. Conserva como artefacto el resultado normalizado y la versión de protocolo, no credenciales ni contexto de usuarios.

Bloquea un merge cuando desaparece una tool pública, cambia un schema sin versión, una llamada segura devuelve datos de otro tenant o el proceso emite basura por stdout. No bloquees por variaciones cosméticas de descripciones mientras el contrato semántico siga siendo válido; de lo contrario, el equipo aprenderá a ignorar rojo.

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.

Checklist antes de conectar un agente

Compilar el servidor y ejecutar Inspector CLI contra el artefacto, no contra un archivo fuente sin build.

Afirmar tools, recursos y prompts esperados, con schemas y límites que el consumidor realmente use.

Probar una llamada feliz con fixtures y errores de validación, timeout y upstream controlados.

Probar dos identidades de test y comprobar aislamiento entre tenants, scopes y operaciones mutantes.

Ejecutar la matriz mínima de transporte y versión de protocolo que anuncias como compatible.

Mantener Inspector, servidor y SDK versionados; releer la migración al actualizar de era MCP.

Ejecutar proxy y fixtures sin secretos de producción, puertos públicos ni privilegios innecesarios.

Guardar resultados normalizados y trazas redactadas como artefactos de CI.

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.