Cómo probar y depurar servidores MCP con MCP Inspector

Si encontró esto buscando "MCP Inspector no conecta" o "cómo probar mi servidor MCP", está en el lugar adecuado. Y si su servidor compila sin errores, pero no tiene idea de si realmente se comporta correctamente hasta que un cliente real falla con él, este artículo es exactamente para eso.

MCP Inspector le ofrece un ciclo completo de depuración con reconocimiento de transporte para cualquier servidor MCP que esté creando o manteniendo. Pero solo si configura correctamente el tipo de transporte, las rutas y la autenticación desde el inicio. Configure mal cualquiera de estas tres cosas y pasará una hora persiguiendo un error de conexión que no tiene nada que ver con el código de su servidor.

Qué falla antes de que siquiera se conecte

• MCP Inspector muestra herramientas, recursos y prompts por separado, para que pueda validar cada primitiva del protocolo de forma independiente.
• Un tipo de transporte incorrecto genera tiempos de espera silenciosos, no errores útiles; aquí es donde se originan la mayoría de los tickets de configuración.
• Los servidores HTTP requieren el segmento de ruta /mcp; omitirlo provoca errores de enrutamiento incluso cuando el servidor responde a pings.
• Una prueba exitosa en Inspector confirma una conexión limpia y esquemas correctos, no que su cliente de producción se comportará de manera idéntica.

Requisitos previos para ejecutar MCP Inspector

Tenga todo esto preparado antes de usar Inspector. La falta de cualquiera de estos elementos produce un modo de fallo diferente y confuso.

• Node.js y npm instalados

  Inspector se inicia mediante npx, que se incluye con npm. Sin Node.js en su equipo, el comando de CLI falla de inmediato con un error de "comando no encontrado" que parece un problema de Inspector, pero no lo es. Es un problema del entorno de ejecución.

• Un servidor MCP en ejecución antes de conectarse

  Esta es una herramienta de código abierto para desarrolladores destinada a pruebas y depuración; no inicia su servidor por usted. Si el proceso del servidor no está ya activo, Inspector intentará conectarse, agotará el tiempo de espera y le dará un error que parece una configuración incorrecta del transporte. El servidor debe estar activo antes de que Inspector entre en juego.

• Un navegador moderno para la GUI

  Inspector sirve su interfaz desde un proceso local de Node en el puerto 6274. Chrome o Firefox, en su versión actual. Los navegadores antiguos han provocado que la interfaz no se renderice. La herramienta es una GUI basada en navegador, no una aplicación de escritorio; esto sorprende a muchas personas la primera vez.

• VS Code con la extensión MCP instalada (si usa la variante de IDE)

  El Inspector incluido disponible dentro de VS Code e IDE similares requiere que la extensión esté instalada para que funcione el inicio automático. Omitir esto y esperar que la ruta de npx inicie la variante integrada en el IDE no produce nada útil.

• Credenciales de OAuth listas si su servidor requiere autenticación

  Debe tener a mano el ID de cliente, el secreto de cliente y la URL de redirección antes de conectarse a un servidor protegido por autenticación. Intentar resolver las credenciales después de que Inspector ya está abierto genera flujos parciales, confusión sobre el estado de la sesión y errores de token que parecen problemas del servidor.

Primeros pasos: cómo iniciar MCP Inspector

Hay dos formas principales de iniciar Inspector. La ruta de CLI mediante npx es la más directa y funciona en cualquier lugar donde esté instalado Node. La ruta integrada en el IDE se inicia automáticamente dentro de su entorno de desarrollo si tiene la extensión adecuada. Ambas terminan sirviendo la misma interfaz basada en navegador en localhost.

Ejecución de MCP Inspector mediante la CLI npx

Abra la terminal y ejecute:

npx @modelcontextprotocol/inspector@latest

Eso es todo para el comando. Lo que ocurre después: se inicia un proceso local de Node e Inspector sirve su interfaz de navegador, de forma predeterminada en http://localhost:6274. Su navegador debería abrirse automáticamente. Si no lo hace, vaya allí manualmente.

Lo que muchas personas pasan por alto en este momento de "primeros pasos" es que esperan una aplicación de escritorio. Inspector no lo es. Es una pestaña del navegador servida desde un servidor local. Esto significa que, si cierra la terminal, la interfaz desaparece. Mantenga el proceso en ejecución mientras utiliza la interfaz de Inspector.

Cuando pasa directamente un comando de servidor mediante CLI, Inspector también puede iniciar por usted el proceso del servidor stdio en línea; por ejemplo:

npx @modelcontextprotocol/inspector node /absolute/path/to/server.js

Es un atajo útil al usar MCP Inspector con un servidor stdio local. La línea de comandos se convierte en la conexión.

Ejecución de MCP Inspector desde un IDE o entorno incluido

Algunos entornos, incluido VS Code con la extensión MCP instalada, incluyen Inspector e inician automáticamente la interfaz del navegador cuando lo activa desde el IDE. El repositorio oficial en GitHub es la fuente autorizada para los detalles de arquitectura y el comportamiento específico de cada versión.

Estas variantes integradas en el IDE gestionan la integración con Claude Desktop de forma más directa, ya que la extensión conoce el contexto de su espacio de trabajo. Pero primero debe instalar la extensión. Intentar invocar Inspector desde VS Code sin ella no produce nada: sin error, sin interfaz, sin comentarios útiles. Instale la extensión y después actívelo.

Cómo elegir el transporte adecuado: stdio, SSE y HTTP con transmisión

Aquí es donde se originan la mayoría de los tickets de soporte. Un tipo de transporte incorrecto no genera un error claro. Genera un tiempo de espera silencioso o un fallo de handshake sin ningún mensaje que le indique qué salió mal. Se quedará mirando el indicador giratorio del estado de conexión y asumirá que el servidor está caído. Probablemente no lo esté.

MCP admite tres modos de transporte distintos y no son intercambiables. Seleccionar el incorrecto en Inspector es exactamente como intentar hablar francés con alguien que solo habla portugués: técnicamente están en la misma reunión, pero no se comunica nada.

Configuración del transporte stdio: comando, argumentos y rutas absolutas

Use el transporte stdio cuando su servidor MCP se ejecute como un proceso hijo local, iniciado directamente por Inspector o por un cliente. La configuración del servidor en Inspector requiere dos campos: el comando (el ejecutable) y los argumentos (cualquier indicador o ruta de archivo).

El error de configuración más común que veo con stdio es usar una ruta relativa en lugar de una absoluta. Las rutas relativas no logran iniciar silenciosamente el proceso del servidor. El error que recibe no dice "ruta incorrecta". Simplemente no se conecta. Use siempre la ruta absoluta completa.

Una configuración stdio válida se ve así:

Pase las variables de entorno mediante el campo Entorno, no modificando su sesión de shell. Inspector necesita verlas a nivel de proceso.

Configuración del transporte HTTP y SSE: formato de URL y la ruta /mcp

Use el transporte HTTP o SSE cuando su servidor MCP exponga un endpoint HTTP, ya sea local o remoto. La documentación de Cloudflare Agents recomienda explícitamente este enfoque para probar servidores MCP remotos y gateways antes de conectarlos a un agente.

El campo de URL configurable es sencillo. La trampa está en el segmento de ruta. Para los servidores que implementan el protocolo MCP sobre HTTP, la URL debe incluir /mcp al final:

https://your-server.example.com/mcp

Omitir /mcp provoca fallos de enrutamiento que parecen errores de conexión incluso cuando el servidor es completamente accesible. El servidor responde en su raíz. El endpoint del protocolo MCP no. Obtendrá un 404 o un tiempo de espera silencioso, según cómo gestione el servidor las rutas no reconocidas. Añada el segmento de ruta; no es opcional.

Si necesita exponer encabezados personalizados, como un encabezado Authorization para un gateway, la configuración de transporte HTTP de Inspector incluye una sección Headers. Agréguelos allí antes de conectarse.

Cómo gestionar la autenticación para servidores MCP protegidos con OAuth

Los fallos de autenticación en MCP Inspector casi siempre son problemas de secuencia de configuración, no problemas del servidor. El servidor es accesible. Las credenciales existen. Pero algo no se introdujo antes del intento de conexión, o no se introdujo en el orden correcto, y el token falta o no es válido cuando Inspector realiza su primera solicitud.

Sigo viendo este patrón: alguien depura durante 45 minutos suponiendo que el servidor MCP tiene un error, y luego descubre que el campo del token de sesión del proxy estuvo vacío todo el tiempo. Los mensajes de error de autenticación en el lado del cliente suelen ser silenciosos o engañosos, lo que significa que la señal que necesita está en Inspector, no en los registros de su servidor.

Registro del cliente MCP Inspector con su proveedor de identidad

Antes de que Inspector pueda completar un flujo de OAuth, su proveedor de identidad necesita saber que Inspector existe como cliente. Para Auth0 y proveedores similares, esto significa crear una aplicación que represente al cliente Inspector y obtener sus credenciales.

Necesitará un ID de cliente, un secreto de cliente y una URL de redirección registrada. La URL de redirección debe coincidir exactamente con lo que Inspector espera, normalmente algo como http://localhost:6274/oauth/callback. Una discrepancia aquí hace que el flujo de consentimiento falle en el paso de redirección con un error genérico que parece un problema de permisos.

Existen dos rutas de registro:

Si su proveedor de identidad admite DCR, Inspector puede gestionar por sí mismo el flujo de registro. De lo contrario, deberá realizar un registro estático. Consulte la documentación de su proveedor: Auth0 admite ambos, pero DCR requiere una marca de configuración explícita para habilitarse. Configurar esto incorrectamente significa que Inspector llega con credenciales que el proveedor no reconoce y obtiene un 401 que no tiene nada que ver con su servidor MCP.

En cuanto a permisos, no desactive scopes intentando simplificar la configuración. El servidor MCP necesita scopes específicos para exponer correctamente sus herramientas. Los permisos excesivamente limitados generan listas de herramientas parciales y errores 403 a mitad de sesión que parecen errores de Inspector.

Finalización del flujo OAuth e introducción de credenciales en Inspector

En la interfaz de Inspector, introduzca su ID de cliente, secreto de cliente y el token de sesión del proxy en la sección de configuración de autenticación antes de hacer clic en Connect. Ese orden importa. Hacer clic primero en Connect y esperar introducir las credenciales en una ventana emergente no es cómo funciona el flujo.

Una vez que haga clic en Connect con las credenciales ya configuradas, Inspector activará la pantalla de consentimiento basada en navegador. Complete el inicio de sesión y acepte los permisos. Tras esa redirección, Inspector mantiene un token de sesión activo y puede pasar a la pestaña Tools.

El token de sesión del proxy es la pieza que la mayoría de las personas pasa por alto. Es independiente de las credenciales de cliente OAuth. Es lo que permite a la capa proxy de Inspector mantener la sesión entre su navegador y el servidor MCP. Déjelo vacío y recibirá un error de "token missing" aunque el endpoint del servidor sea perfectamente accesible y las credenciales OAuth sean correctas.

Ahí es donde suele comenzar el ticket.

Cómo probar servidores MCP: descubrimiento y ejecución de herramientas

Una vez conectado, el flujo de pruebas principal consta de tres pasos: Connect, List Tools, Run Tool. Esa secuencia lo es todo. Lo que la hace útil es leer cuidadosamente lo que devuelve en cada paso.

Una conexión correcta muestra un indicador de estado verde en Inspector, con el nombre del servidor y la versión del protocolo visibles. Si ve eso, no ha terminado de probar: ha terminado de conectarse. Las pruebas empiezan ahora.

Uso de la pestaña Tools para listar e inspeccionar esquemas de herramientas

Haga clic en List Tools en la pestaña Tools. Inspector envía la solicitud MCP tools/list a su servidor y representa la respuesta: nombres de herramientas, descripciones y el esquema JSON completo de los parámetros de cada herramienta.

Aquí es donde valida varias cosas a la vez. ¿Los nombres de las herramientas son correctos? ¿Las descripciones de los parámetros son precisas? ¿Los parámetros obligatorios aparecen como obligatorios en el esquema? ¿El esquema de entrada es el que su servidor realmente espera?

Para servidores que exponen múltiples espacios de nombres de herramientas, algo habitual con servidores MCP de Ontology o cualquier servidor que encapsule varias API de backend, la lista de herramientas es cómo confirma que los límites entre espacios de nombres funcionan. Un esquema que muestra el tipo de parámetro incorrecto para una herramienta es un error del servidor, y es mejor detectarlo aquí que en un agente de producción que pasa silenciosamente el tipo incorrecto y devuelve datos inútiles.

Inspeccione directamente el esquema JSON sin procesar en Inspector antes de ejecutar nada. Toma 30 segundos y ha detectado errores reales que no habrían aparecido hasta la tercera o cuarta invocación de una herramienta.

Ejecución de una herramienta y lectura de la respuesta en tiempo real

Seleccione una herramienta de la lista. Inspector representa un formulario basado en el esquema de entrada de la herramienta: complete los parámetros obligatorios, añada los opcionales relevantes para su prueba y haga clic en Run Tool.

Inspector muestra la carga útil sin procesar de la solicitud que envió y la respuesta sin procesar que recibió. Lea ambas. La solicitud le muestra lo que Inspector realmente serializó a partir de las entradas de sus parámetros, lo cual es útil para detectar coerciones de tipo. La respuesta muestra la salida completa del servidor, incluida cualquier carga útil de error.

Como criterio práctico de éxito, ejecute la misma herramienta dos veces con entradas idénticas. Las respuestas deberían ser idénticas, o diferentes de forma determinista si la herramienta consulta datos en tiempo real. Las respuestas inconsistentes para entradas idénticas normalmente indican un problema de estado del lado del servidor o una condición de carrera en la implementación de la herramienta. Ejecútela cinco veces si la herramienta usa API externas: el comportamiento ante límites de tasa y la gestión de tiempos de espera aparecen en ejecuciones repetidas de una forma que no aparecerá en una sola prueba.

La guía de Chris Ebert sobre el AWS Documentation MCP Server en Inspector es una buena referencia de cómo se ve un flujo de invocación de herramientas limpio de principio a fin: puede ver los parámetros de la herramienta search_documentation, el esquema y cómo interpretar la respuesta antes de integrar el servidor en un agente.

📊 En la práctica:
Una prueba exitosa en Inspector confirma un estado de conexión limpio, esquemas de herramientas correctos y respuestas consistentes de las herramientas para las entradas esperadas. No confirma que su cliente MCP de producción, ya sea un IDE de IA, Claude Desktop o un framework de agentes, gestionará los casos límite de la misma manera. Inspector valida el comportamiento del protocolo de su servidor. El cliente introduce su propia capa de interpretación.

Depuración de errores del servidor MCP: registros, solicitudes y vistas a nivel de protocolo

Cuando algo falla en Inspector, el diseño de vista por pestañas es donde debe ir para averiguar dónde falló. Las pestañas no son decorativas. Cada una muestra una capa diferente de la interacción del protocolo.

Los servidores MCP exponen tres primitivas principales: recursos para contexto, herramientas para acciones y prompts para interacciones con plantillas. El debate de la comunidad de GitHub sobre la arquitectura de MCP las describe claramente. Inspector muestra las tres por separado, lo que significa que puede validar cada una de forma independiente en lugar de asumir que una lista de herramientas funcional implica que todo lo demás está bien. No es así.

Lectura del panel de salida de errores y los registros de solicitud/respuesta

El panel de salida de errores muestra mensajes del lado del servidor, salida stderr y códigos de error a nivel de protocolo. Si falla una invocación de herramienta, revise primero este panel. Un 401 significa un problema con el token de autenticación. Un error de incompatibilidad de esquema significa que su servidor devuelve una respuesta que no cumple con lo declarado por el esquema de la herramienta. Un tiempo de espera sin código de error normalmente significa que el servidor recibió la solicitud y dejó de responder durante la ejecución.

Los registros de solicitud/respuesta muestran los mensajes del protocolo MCP sin procesar, incluido el handshake de inicialización. Aquí es donde inspecciona las cargas útiles y los detalles a nivel de protocolo en su totalidad. Si el handshake muestra una incompatibilidad inesperada de capabilities, con frecuencia esa es la causa raíz de que las herramientas no aparezcan aunque la conexión se muestre en verde. Revise el registro antes de asumir que el código del servidor está mal. El problema suele estar en el paso de negociación.

Utilice las pestañas Prompts y Resources de la misma forma: haga listas, inspeccione sus esquemas e invóquelos con entradas de prueba. Un servidor que lista correctamente las herramientas, pero devuelve URI de recursos malformados, fallará en flujos específicos de agentes que combinan llamadas a herramientas con recuperación de contexto. Detecte eso ahora, no después de integrar el servidor en un flujo de IA de producción.

Itere modificando el código del servidor, reconectando y ejecutando de nuevo. Inspector no conserva sesiones entre reinicios del servidor, pero reconectarse es rápido, y este ciclo (cambiar código → reiniciar servidor → reconectar Inspector → volver a ejecutar herramienta) es el ritmo de desarrollo principal para cualquier trabajo con servidores MCP.

Solución de errores de conexión y configuraciones incorrectas comunes

Cuando falle la conexión, revise esta lista antes de asumir que el servidor tiene un error:

• El servidor no se inició antes de conectarse

  Inspector no puede iniciar su servidor en la mayoría de las configuraciones. Si el proceso no está en ejecución, la conexión agotará el tiempo de espera. Inicie el servidor, confirme que acepta conexiones y luego abra Inspector.

• Se seleccionó el tipo de transporte incorrecto

  Un servidor stdio configurado como HTTP, o viceversa, genera un handshake fallido sin un mensaje de diagnóstico útil. Observe cómo se inicia su servidor: si es un proceso hijo, es stdio. Si se vincula a un puerto, es HTTP o SSE.

• Falta el segmento de ruta /mcp en la URL

  Para los transportes HTTP/HTTP con transmisión, la URL debe terminar en /mcp para que el enrutamiento del protocolo sea correcto. Que un servidor sea accesible en su raíz no significa que el endpoint MCP sea accesible.

• No se introdujo el token de autenticación o el token de sesión del proxy antes de conectarse

  Introduzca todas las credenciales antes de hacer clic en Connect. Introducirlas después de un intento de conexión fallido deja a Inspector en un estado parcial que a veces requiere una recarga completa para limpiarse.

• Ruta relativa en la configuración stdio

  Use rutas absolutas para el comando del servidor. Las rutas relativas fallan silenciosamente durante el inicio del proceso, lo que parece un error de conexión.

🤔 Espere.
Inspector valida que su servidor se comporta correctamente durante una sesión de Inspector. Pero su cliente MCP de producción, ya sea una configuración de Claude Desktop, un IDE de IA o un agente personalizado, tiene su propia interpretación del protocolo, su propio comportamiento de reintentos y su propia lógica de tiempos de espera. Los desarrolladores descubren discrepancias regularmente solo después de cambiar de Inspector a su cliente real. Inspector es un paso necesario, no el final.

Hay algo más que conviene saber sobre el ciclo de depuración: si su servidor MCP gestiona llamadas autenticadas y observa fallos de autenticación intermitentes que no se reproducen de forma consistente en Inspector, el problema suele ser el alcance del token y no su validez. En Latenode, cuando los ingenieros integran un servidor MCP en un flujo de automatización de varios pasos, añaden un nodo JavaScript que registra el token exacto, los scopes y el cuerpo de la solicitud en cada llamada; así, cuando aparece un 401, disponen de todo el contexto en un solo lugar en vez de reconstruirlo a partir de tres registros diferentes. Ese patrón es directamente útil aquí: integre el registro en el flujo antes de asumir que el servidor está fallando.