Cuando 26 herramientas MCP fallan igual: la lección de diagnóstico que todo desarrollador necesita leer
Imagina que configuras 26 herramientas en tu servidor MCP de GitHub. Las ves perfectamente listadas en tu cliente. Llamas a cualquiera de ellas y falla en menos de un segundo. Las 26. Con el mismo mensaje: "Tool execution failed." Sin código de error. Sin detalle. Nada accionable.
Eso es exactamente lo que documentó Sho Naka en Dev.to esta semana. Y lo más valioso de su artículo no es el error en sí — es la disección honesta de cómo un proceso de diagnóstico puede descartar la hipótesis correcta demasiado pronto, y cómo evitar repetir ese mismo patrón.
En este artículo analizamos los tres errores de razonamiento que prolongaron el problema durante horas, y qué nos enseña esto sobre la forma en que los equipos técnicos deben abordar el debugging de integraciones modernas con IA.
El síntoma que confundió a todos: visible pero inutilizable
El escenario era el siguiente: Claude Desktop reconocía correctamente las 26 herramientas del servidor GitHub MCP. La llamada tools/list funcionaba sin problema. Pero cualquier tools/call devolvía el mismo error genérico en menos de un segundo.
Lo que hizo confuso el diagnóstico fue precisamente eso: si las herramientas no hubieran aparecido en la lista, la investigación habría sido corta. El hecho de que estuvieran visibles pero inutilizables abrió una cantidad innecesaria de caminos de investigación.
La primera hipótesis del asistente de IA fue directa: «quizás el token está dañado». Era la respuesta correcta. Pero tres experimentos mal diseñados la descartaron antes de tiempo, y el desarrollador pasó horas buscando en la dirección equivocada.
Los tres errores de diagnóstico que todo equipo técnico comete
Error 1: Confundir "sin permisos suficientes" con "token inválido". Para descartar la hipótesis del token, se probó con un repositorio completamente público — uno que no requiere ningún tipo de autenticación. El razonamiento parecía sólido: si el problema fuera de permisos, un repo público debería funcionar igual. No funcionó. Y eso se interpretó como prueba de que el token no era el problema.
El error lógico es sutil pero importante. Hay dos hipótesis distintas dentro de "es un problema del token": que el token tenga scopes insuficientes, o que el token sea directamente inválido. Un repositorio público puede ser leído por cualquiera sin credenciales — pero eso no significa que GitHub ignore un header de autorización malformado. Un token inválido devuelve 401 incluso en recursos públicos, porque GitHub igual procesa el header y lo rechaza. El experimento eliminó la primera hipótesis, no la segunda. Se archivaron ambas juntas.
Error 2: Re-autorizar la credencial equivocada, tres veces. La solución intentada fue re-autorizar la GitHub App desde el cliente. Tres veces. Sin ningún cambio en el síntoma. Pero el servidor MCP estaba leyendo un Personal Access Token hardcodeado directamente en el archivo claude_desktop_config.json. Son dos credenciales completamente distintas. Ninguna re-autorización de la App toca el PAT almacenado en el JSON de configuración local. Tres intentos idénticos en el objetivo equivocado.
Error 3: No revisar los logs hasta el final. Windows almacena los logs de MCP en %APPDATA%\Claude\logs\. macOS los guarda en ~/Library/Logs/Claude/. Cuando finalmente se abrió ese archivo, el diagnóstico apareció en segundos:
El servidor respondía con código -32603 — el error genérico "Internal error" de JSON-RPC 2.0. No era un timeout. No era que la llamada se perdiera. El servidor recibía la solicitud, la procesaba, y devolvía un error de autenticación. Al ejecutar el mismo servidor directamente sobre stdio con la misma variable de entorno, la respuesta fue inmediata: "Authentication Failed: Bad credentials". El token en el archivo de configuración había expirado o estaba corrupto.
¿Cómo aplica esto en equipos de desarrollo en Perú y LATAM?
Las integraciones con herramientas MCP, APIs externas y servicios de IA están creciendo rápidamente en los equipos técnicos de la región. Y con esa adopción vienen exactamente estos escenarios: errores genéricos, múltiples capas de autenticación, y procesos de debugging que pueden consumir horas si no se tiene un método claro.
Lo que este caso enseña es aplicable a cualquier integración técnica, no solo a MCP. Cuando una llamada a una API falla con un error genérico, el primer paso siempre debe ser revisar los logs en la capa más cercana al servidor — no en la interfaz de usuario. La UI muestra lo que puede mostrar; el log muestra lo que realmente pasó.
Además, en arquitecturas donde coexisten múltiples tipos de credenciales — OAuth apps, Personal Access Tokens, API keys, service accounts — es crítico identificar exactamente cuál credencial está usando cada componente antes de intentar cualquier corrección. Re-autorizar el componente equivocado no solo no resuelve el problema: te da una falsa sensación de que ya intentaste esa solución.
¿Cómo aplica esto en tu empresa?
Si tu equipo está integrando herramientas de IA, servidores MCP, o cualquier tipo de API externa en sus flujos de trabajo, estas son las acciones concretas que reducen el tiempo de diagnóstico:
- Define un checklist de debugging antes de que ocurra el primer error. ¿Dónde están los logs de cada componente? ¿Qué credencial usa cada servicio? ¿Cómo se prueba cada capa de forma aislada?
- Separa claramente las hipótesis antes de diseñar el experimento. "Es un problema de autenticación" no es una hipótesis — es una categoría. "El token tiene scopes insuficientes" y "el token es inválido" son dos hipótesis distintas que requieren experimentos distintos.
- Revisa los logs antes de intentar cualquier corrección. En la mayoría de los casos, el error real está documentado en algún archivo de log que nadie abrió. Un minuto leyendo logs vale más que una hora repitiendo el mismo fix.
- Documenta qué credencial usa cada componente de tu stack. En proyectos con múltiples integraciones, este mapa evita exactamente el error de re-autorizar el componente equivocado.
En los proyectos de desarrollo e integración que llevamos adelante en Consultoría-Ti, este tipo de metodología de diagnóstico es parte del proceso estándar. No porque seamos infalibles, sino porque aprendimos — a veces de la manera difícil — que un experimento mal diseñado puede ser más costoso que no hacer ningún experimento.
Conclusión
El caso de los 26 herramientas MCP que fallaban igual es, en el fondo, una historia sobre razonamiento bajo incertidumbre. La hipótesis correcta estaba sobre la mesa desde el primer minuto. Un experimento que parecía refutarla no lo hacía — solo eliminaba una variante de la hipótesis, no la hipótesis completa.
En un ecosistema donde las integraciones con IA se están volviendo parte del stack técnico cotidiano, la capacidad de debuggear con método y claridad lógica es tan importante como saber configurar las herramientas. Los errores genéricos no van a desaparecer — pero el tiempo que tardamos en resolverlos sí puede reducirse significativamente.
Si tu equipo está trabajando con integraciones MCP, automatizaciones con IA, o simplemente quiere mejorar la robustez de sus flujos técnicos, en Consultoría-Ti podemos ayudarte a diseñar arquitecturas más claras y procesos de debugging más efectivos. Conversemos sobre tu proyecto.
Fuentes y Referencias
Sho Naka — "All 26 of My MCP Tools Failed the Same Way" (Dev.to)
✨ Contenido generado con ContentFlow — Consultoría-Ti