Claude Code MCP Registros: Encontrar el primer límite fallido

Si buscas Claude Code MCP logs , empieza con el estado resuelto del servidor y luego captura un archivo de depuración con alcance de incidente. No empieces siguiendo el directorio de registro Claude Desktop: la documentación de MCP actual etiqueta esas rutas de sistema de archivos específicamente para Escritorio, mientras que Claude Code documentos /mcp , claude mcp list , claude debug mcp y debug file . El resultado útil no es "encontrar un tronco". Consiste en identificar el primer límite fallido: configuración, aprobación de proyectos, inicio de procesos, descubrimiento de herramientas, ejecución de herramientas o el resultado externo que se suponía que debía producir. Un tronco puede explicar una frontera. No puede probar los seis. Esta guía utiliza la documentación actual de Claude Code y la 2.1.220 de lanzamiento del NPM, revisada el 30 de julio de 2026. Pinea tu versión instalada en cada incidente porque MCP comportamiento y diagnóstico siguen cambiando. Inspeccionar el estado resuelto antes de leer la salida en bruto Ejecuta estas comprobaciones desde el mismo directorio de trabajo y la misma cuenta de usuario que mostró el problema: Dentro de la sesión Claude Code afectada, ejecuta: El Guía oficial de configuración y depuración Dice /mcp muestra servidores configurados, estado de conexión y aprobación del proyecto. El MCP referencia Añade dos detalles operativos que importan: Un servidor de .mcp.json con alcance de proyecto puede permanecer pendiente hasta que el espacio de trabajo sea confiable y el servidor sea aprobado; Un servidor conectado aún puede exponer cero herramientas, y /mcp informes que cuentan. Estos hechos eliminan tres clases de búsqueda a ciegas de registros: Pruebas resueltas Primera decisión Por qué los registros no son los primeros Ausencia del servidor CONFIG MISSING Aún no hay un proceso de servidor cargado para diagnosticar. Revisa las fuentes de alcance y configuración. Pendiente de aprobación APPROVAL WAIT Esto es un límite legítimo de autoridad, no un choque. Revísalo y apróbalo de forma interactiva. No se conectó Captura MCP depuración de pruebas El comando, la ruta, el entorno, la autenticación o el transporte pueden haber fallado. Conectado, cero herramientas Reconecta y luego captura MCP evidencia de depuración El inicio tuvo éxito lo suficiente para conectarse, pero el descubrimiento no produjo un registro utilizable. Conectado, herramientas presentes Reproduce una llamada acotada La salud de la conexión no dice nada sobre la herramienta seleccionada ni sobre su efecto externo. Las rutas relativas merecen especial sospecha para los servidores locales de stdio. Claude Code documentos que command y args rutas se resuelven desde el directorio donde se lanzó Claude Code, no desde la ubicación de .mcp.json . Por tanto, un servidor puede funcionar en un repositorio y fallar desde otro con texto de configuración idéntico. Captura un archivo de depuración de Claude Code MCP con alcance La actualidad Claude Code Referencia CLI Documenta dos banderas relevantes: debug activa el modo de depuración y acepta filtros de categoría como mcp ; debug file <path escribe la salida de depuración en un camino explícito y activa implícitamente el modo de depuración. Crea un directorio privado de incidentes, inicia una sesión limpia solo con la categoría de depuración MCP y reproduce un síntoma acotado: Dentro de esa sesión, inspecciona /mcp . Si un servidor está conectado sin ninguna herramienta, usa su acción de Reconectar una vez. Si hay herramientas presentes, invoca solo la herramienta de solo lectura más pequeña que reproduzca el problema. No intentes una llamada con capacidad de escritura solo para hacer el registro más interesante. Trata el archivo de depuración como algo sensible. Puede contener rutas absolutas, nombres de servidores, detalles del entorno, metadatos de peticiones o estándar del servidor. Registra las pruebas derivadas en el recibo del incidente y luego conserva o elimina el archivo en bruto según tu política de seguridad. No copies tokens de acceso, cuerpos de prompts, argumentos de herramientas, resultados o texto STDERR en un sistema de monitorización solo porque el archivo los contenga. Un público Claude Code solicitud de funcionalidad para archivos de registro por MCP servidor informa que los usuarios quieren archivos persistentes de estilo escritorio para Claude Code. Ese problema es una prueba útil de límites, no una garantía de producto. El procedimiento de incidente soportado debe depender del archivo de depuración explícito documentado, no de una ruta predeterminada por servidor asumida. Comparar la ruta de las pruebas con el transporte El MCP Guía de depuración para la revisión del protocolo 2026 07 28 traza una frontera crucial para el transporte. Para un servidor local stdio , stdout transporta mensajes de protocolo. El diagnóstico del servidor pertenece a stderr; Escribir texto diagnóstico en STDOUT puede corromper el flujo del protocolo. La guía de resolución de problemas de Claude Code recomienda específicamente claude debug mcp cuando un servidor conectado no expone ninguna herramienta porque esto hace que el servidor stderr esté disponible en la evidencia de depuración. Para Streamable HTTP , el cliente no puede capturar el stderr del proceso del servidor remoto. Un archivo de depuración Claude Code aún puede mostrar comportamiento de conexión y peticiones en el lado cliente, pero la falla interna del servidor necesita registros o OpenTelemetry más inspección a nivel HTTP. Un segmento de depuración de cliente vacío no es prueba de que el servicio remoto no hizo nada. Esta distinción evita una conclusione errónea común: Registra el transporte en el recibo. Sin él, "no stderr" es ambiguo. Construye un recibo de incidentes minimizado por contenido El registro en bruto es prueba para la investigación. El recibo es el historial médico duradero. Puede seguir siendo útil sin almacenar contenido: Mantén explícita la precedencia del clasificador: Repetí esa regla contra ocho estuches sintéticos. Separaba correctamente la configuración faltante, la espera de aprobación, el fallo de arranque capturado, la conexión a cero herramientas, el error de herramienta, la respuesta exitosa de la herramienta sin resultado, el resultado verificado y una conexión fallida con evidencia de depuración insuficiente. Los ocho estados previstos fueron aprobados. Los dos últimos casos son el límite importante. Un resultado JSON RPC de éxito o no error es la evidencia de actividad. Si la tarea prometía un problema creado, un registro modificado, un archivo entregado o un destino actualizado, verifica ese destino por separado. Sin ese recibo, el estado correcto es OUTCOME UNVERIFIED , no es saludable. Elige la siguiente acción segura más pequeña Cada estado debería conducir a una respuesta acotada: CONFIG MISSING : inspecciona el alcance de la configuración y el archivo exacto Claude Code cargado. No alteres el código del servidor. APPROVAL WAIT : Envía la aprobación al humano responsable. No describas la espera como un accidente. STARTUP FAILED : Reparar la primera causa de arranque de hormigón en la evidencia de depuración con alcance y luego reconectar una vez. DISCOVERY EMPTY : comparar la evidencia de inicialización y de la lista de herramientas; Prueba el servidor de forma independiente con MCP Inspector si es necesario. TOOL CALL FAILED : Preserva la identidad de la petición, identifica si es seguro intentar y evita reproducir una escritura incierta. OUTCOME UNVERIFIED : consulta el destino por identificador estable. No vuelvas a ejecutar la herramienta hasta saber si el efecto ya ha ocurrido. UNCERTAIN : recoge la evidencia de límites que falta o escala. Desconocido es un estado operativo, no una invitación a adivinar. HEALTHY : requieren tanto una cadena de MCP utilizable como un recibo de resultado nuevo y determinista. Los registros hacen que un fallo sea explicable. El estado resuelto lo hace localizable. Un recibo de destino hace verificable la recuperación. Si mantienes esos trabajos separados, un incidente Claude Code MCP se convierte en un ejercicio de pruebas cortas en lugar de una secuencia de intentos cada vez más arriesgados. Sidewisp está diseñado en torno a esta distinción que prioriza la salud entre conexión, progreso útil, herramientas y resultados. Sidewisp se encuentra actualmente en versión preliminar privada. Los adaptadores de monitorización de producción y el ejecutor de recuperación generalmente no se envían por completo.