Depuración - Documentación Oficial de MCP en Español

Una guía completa para depurar integraciones de Model Context Protocol (MCP)

La depuración eficaz es esencial al desarrollar servidores MCP o integrarlos con aplicaciones. Esta guía cubre las herramientas y enfoques de depuración disponibles en el ecosistema MCP.

Esta guía es para macOS. Las guías para otras plataformas estarán disponibles pronto.

Descripción general de las herramientas de depuración

MCP proporciona varias herramientas para la depuración en diferentes niveles:

MCP Inspector

Interfaz de depuración interactiva

Pruebas directas del servidor

Consulte la guía del Inspector para obtener más detalles

Claude Desktop Developer Tools

Pruebas de integración

Recopilación de registros

Integración con Chrome DevTools

Registro del servidor

Implementaciones de registro personalizadas

Seguimiento de errores

Monitoreo del rendimiento

Depuración en Claude Desktop

Comprobación del estado del servidor

La interfaz de Claude.app proporciona información básica sobre el estado del servidor:

Haga clic en el icono

para ver:

Servidores conectados

Prompts y recursos disponibles

Haga clic en el icono

para ver:

Herramientas disponibles para el modelo

Visualización de registros

Revise los registros detallados de MCP desde Claude Desktop:

Los registros capturan:

Eventos de conexión del servidor

Problemas de configuración

Errores de tiempo de ejecución

Intercambios de mensajes

Uso de Chrome DevTools

Acceda a las herramientas para desarrolladores de Chrome dentro de Claude Desktop para investigar errores del lado del cliente:

Cree un archivo developer_settings.json con allowDevTools configurado como verdadero:

Abra DevTools: Command-Option-Shift-i

Nota: Verá dos ventanas de DevTools:

Ventana de contenido principal

Ventana de la barra de título de la aplicación

Utilice el panel Consola para inspeccionar los errores del lado del cliente.

Utilice el panel Red para inspeccionar:

Cargas útiles de mensajes

Tiempo de conexión

Problemas comunes

Directorio de trabajo

Cuando utilice servidores MCP con Claude Desktop:

El directorio de trabajo para los servidores iniciados a través de claude_desktop_config.json puede no estar definido (como / en macOS) ya que Claude Desktop podría iniciarse desde cualquier lugar

Utilice siempre rutas absolutas en su configuración y archivos .env para garantizar un funcionamiento fiable

Para probar servidores directamente a través de la línea de comandos, el directorio de trabajo será donde ejecute el comando

Por ejemplo, en claude_desktop_config.json, utilice:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}

En lugar de rutas relativas como ./data

Variables de entorno

Los servidores MCP heredan solo un subconjunto de variables de entorno automáticamente, como USER, HOME y PATH.

Para anular las variables predeterminadas o proporcionar las suyas propias, puede especificar una clave env en claude_desktop_config.json:

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

Inicialización del servidor

Problemas comunes de inicialización:

Problemas de ruta

Ruta incorrecta del ejecutable del servidor

Faltan archivos requeridos

Problemas de permisos

Intente usar una ruta absoluta para command

Errores de configuración

Sintaxis JSON no válida

Faltan campos requeridos

Desajustes de tipo

Problemas de entorno

Faltan variables de entorno

Valores de variables incorrectos

Restricciones de permisos

Problemas de conexión

Cuando los servidores no se conectan:

Revise los registros de Claude Desktop

Verifique que el proceso del servidor se esté ejecutando

Pruebe de forma independiente con Inspector

Verifique la compatibilidad del protocolo

Implementación de registro

Registro del lado del servidor

Al crear un servidor que utiliza el stdio transport local, todos los mensajes registrados en stderr (error estándar) serán capturados automáticamente por la aplicación host (por ejemplo, Claude Desktop).

Los servidores MCP locales no deben registrar mensajes en stdout (salida estándar), ya que esto interferirá con el funcionamiento del protocolo.

Para todos los transports, también puede proporcionar registro al cliente enviando una notificación de mensaje de registro:

Python

TypeScript

Eventos importantes para registrar:

Pasos de inicialización

Acceso a recursos

Ejecución de herramientas

Condiciones de error

Métricas de rendimiento

Registro del lado del cliente

En aplicaciones cliente:

Habilite el registro de depuración

Supervise el tráfico de red

Realice un seguimiento de los intercambios de mensajes

Registre los estados de error

Flujo de trabajo de depuración

Ciclo de desarrollo

Desarrollo inicial

Utilice Inspector para pruebas básicas

Implemente la funcionalidad principal

Agregue puntos de registro

Pruebas de integración

Pruebe en Claude Desktop

Supervise los registros

Verifique el manejo de errores

Prueba de cambios

Para probar los cambios de manera eficiente:

Cambios de configuración: Reinicie Claude Desktop

Cambios en el código del servidor: Utilice Command-R para recargar

Iteración rápida: Utilice Inspector durante el desarrollo

Buenas prácticas

Estrategia de registro

Registro estructurado

Utilice formatos consistentes

Incluya contexto

Agregue marcas de tiempo

Realice un seguimiento de los ID de solicitud

Manejo de errores

Registre los seguimientos de pila

Incluya el contexto del error

Realice un seguimiento de los patrones de error

Supervise la recuperación

Seguimiento del rendimiento

Registre el tiempo de operación

Supervise el uso de recursos

Realice un seguimiento de los tamaños de los mensajes

Mida la latencia

Consideraciones de seguridad

Al depurar:

Datos confidenciales

Limpie los registros

Proteja las credenciales

Enmascare la información personal

Control de acceso

Verifique los permisos

Verifique la autenticación

Supervise los patrones de acceso

Obtener ayuda

Al encontrar problemas:

Primeros pasos

Revise los registros del servidor

Pruebe con Inspector

Revise la configuración

Verifique el entorno

Canales de soporte

Problemas de GitHub

Discusiones de GitHub

Proporcionar información

Extractos de registro

Archivos de configuración

Pasos para reproducir

Detalles del entorno