Usa MCP Inspector para depurar y probar tools sin necesitar Claude Desktop.
MCP Inspector es la herramienta oficial de debug para servers MCP. Es una interfaz web que se conecta a tu server y te permite ver todas las tools, resources y prompts registrados, ejecutar tools manualmente con parámetros personalizados e inspeccionar respuestas, todo sin necesidad de Claude Desktop.
O MCP Inspector actúa como un cliente MCP visual. Inicia tu server, establece la conexión mediante STDIO y presenta una interfaz web interactiva donde puedes: ver la lista completa de tools (con descripciones y parámetros), resources (con URI y tipos) y prompts (con argumentos). Puedes ejecutar cualquier tool completando los parámetros en la interfaz y ver la respuesta formateada en tiempo real. Es esencial durante el desarrollo.
El Inspector es mantenido por el equipo oficial de MCP en el repositorio modelcontextprotocol/inspector en GitHub. Admite todas las versiones del protocolo MCP y se actualiza junto con la especificación. Los desarrolladores que usan Inspector durante el desarrollo reportan reducción del 50% en el tiempo de depuración en comparación con probar directamente desde Claude Desktop, porque el ciclo de retroalimentación es instantáneo.
Usa el Inspector como tu primer paso de prueba — incluso antes de configurar Claude Desktop. Si tu tool funciona en Inspector, funcionará en Claude. Si no funciona en Inspector, el problema está en tu server, no en la configuración del client. Inspector es tu herramienta para aislar problemas.
La instalación de MCP Inspector es sorprendentemente sencilla: basta con un solo comando npx que descarga y ejecuta todo automáticamente. No hace falta instalarlo globalmente ni configurar nada. La interfaz se abre en el navegador y está lista para usarse.
El comando para ejecutar Inspector es:
O npx descarga el paquete temporalmente y lo ejecuta sin instalación global. El Inspector se abre automáticamente en el navegador en http://localhost:5173 (puerto predeterminado). La primera ejecución puede tardar unos segundos en descargar las dependencias.
Asegúrate de tener Node.js instalado (versión 18 o superior). Verifica con node --version.
Ejecuta npx @modelcontextprotocol/inspector uv run server.py — esto inicia el Inspector Y tu server al mismo tiempo.
El navegador se abre automáticamente. Si no se abre, accede manualmente http://localhost:5173.
Node.js es obligatorio para ejecutar el Inspector. Si no tienes Node.js instalado, visita nodejs.org e instala la versión LTS. En Linux, puedes usar sudo apt install nodejs npm o instalar mediante nvm para administrar varias versiones.
El Inspector necesita saber cómo iniciar tu server MCP. Especificas el comando para ejecutar el server y el Inspector se encarga de iniciar el proceso, establecer la conexión STDIO y mantener la comunicación activa durante toda la sesión de debug.
El comando completo para conectarte a tu server:
El Inspector inicia el proceso uv run server.py como subproceso y se conecta mediante STDIO — el mismo mecanismo que usa Claude Desktop. Esto significa que, si funciona en Inspector, funcionará en Claude. Cualquier output que tu server envíe a stdout se interpreta como mensajes MCP; los logs deben ir a stderr.
Si usas python directamente en lugar de uv, el comando sería npx @modelcontextprotocol/inspector python server.py. El Inspector acepta cualquier comando que inicie un proceso MCP vía STDIO. Asegúrate de que el entorno virtual correcto esté activado si usas python directamente.
La interfaz de Inspector muestra todas las tools registradas en tu server, con sus descripciones y parámetros. Puedes completar los campos de parámetros, ejecutar la tool y ver la respuesta de inmediato: un ciclo de retroalimentación rápido que acelera enormemente el desarrollo.
En la pestaña "Tools" del Inspector, verás la lista completa de tools del server. Cada tool muestra su nombre, descripción (de la docstring) y los parámetros esperados (de los type hints). Al hacer clic en una tool, aparecen campos de formulario para cada parámetro. Completa los valores y haz clic en "Run Tool" y la respuesta aparece formateada abajo, incluido el contenido devuelto, el tipo MIME y los posibles errores. Esto permite probar cada tool por separado, con distintas combinaciones de parámetros.
En la pestaña "Tools", encuentra en la lista la tool que quieres probar. Verifica que el nombre y la descripción sean correctos.
Completa los campos de parámetros con valores de prueba. Empieza con valores válidos y luego prueba los edge cases.
Haz clic en "Run Tool" y observa la respuesta. Verifica el formato, el contenido y el manejo de errores.
Ajusta el código del server y guarda el archivo. Vuelve a conectar el Inspector para probar los cambios.
Crea una lista de escenarios de prueba para cada tool: valores válidos normales, valores vacíos, valores en el límite del rango, caracteres especiales, cadenas muy largas. Ejecuta cada escenario desde el Inspector y verifica que la respuesta sea adecuada en todos los casos. Esto es especialmente importante para las tools que hacen solicitudes HTTP o acceden a archivos.
El Inspector muestra las respuestas de las tools en un formato estructurado, incluido el JSON sin procesar de la comunicación MCP. Así puedes verificar no solo el contenido de la respuesta, sino también que el formato y los tipos sean correctos; esta información es esencial para garantizar que el modelo interprete correctamente la respuesta.
Al ejecutar una tool en Inspector, la respuesta se muestra en dos vistas: la vista formateada (texto legible, imágenes renderizadas) y el JSON sin procesar (el mensaje MCP exacto que se enviaría al client). El JSON sin procesar muestra el array de content con cada bloque teniendo type e text. Comparar el JSON sin procesar con el resultado esperado es la forma más confiable de validar que tu tool funciona correctamente.
Una respuesta MCP bien formateada sigue esta estructura: {"content": [{"type": "text", "text": "..."}]}. El campo isError indica si la tool encontró un error. Cuando devuelve True, el modelo sabe que debe informar del error al usuario en lugar de usar la respuesta como dato válido. El Inspector lo muestra visualmente con distintos colores.
Cuando algo no funciona como esperas, Inspector es tu mejor aliado para diagnosticar el problema. Desde servers que no se conectan hasta tools que devuelven errores inesperados, hay un proceso sistemático de depuración que resuelve la mayoría de los problemas en pocos minutos.
Los problemas más comunes y sus soluciones: El server no se conecta — comprueba que el comando sea correcto y que las dependencias estén instaladas. La tool no aparece en la lista — comprueba que el decorator @mcp.tool() esté presente y que la función no tenga errores de sintaxis. La tool devuelve un error — revisa los logs del server en el terminal donde se está ejecutando Inspector; el stderr del server aparece allí. Respuesta vacía — comprueba que la función devuelva algo (que no sea None).
¿El Inspector muestra "Connected" en la parte superior? Si no, el comando del server es incorrecto o el server tiene un error de importación.
¿La pestaña "Tools" muestra tus tools? Si no, revisa los decorators, los imports y que el server no falle al iniciarse.
¿Los parámetros son correctos en la interfaz? Si faltan, verifica los type hints en la firma de la función.
Si la tool se ejecuta, pero devuelve un error, revisa los logs en el terminal. El stderr del server contiene el stack trace completo.
Después de editar el código, debes volver a conectar el Inspector para que los cambios surtan efecto.
El error más común y más difícil de diagnosticar: print() en el código del server. Como MCP usa stdout para la comunicación, cualquier print() en tu código corrompe el protocolo y provoca una desconexión inmediata. Sustituye todos los prints por logging.info() o logging.debug() que van a stderr.
npx @modelcontextprotocol/inspector — requiere Node.js.
¡Este es el último módulo de la Ruta 3! Siguiente Ruta: Ruta 4 — Proyectos del mundo real