Solución de problemas

Problemas comunes al conectar o llamar a herramientas, y qué los causa.

«Authentication required» al conectar

El servidor exige un token de acceso Bearer en cada solicitud — un simple GET a la URL del servidor (por ejemplo, abrirla en un navegador) siempre devuelve esto; no es un error de tu configuración.

{
  "error": "Authentication required. POST with Authorization: Bearer <token>."
}

Solicitudes que antes funcionaban fallan de repente

Los tokens de acceso expiran tras 1 hora. Un cliente funcional se renueva automáticamente con su token de actualización — si el tuyo no lo hace, vuelve a conectarlo.

Un cliente que antes funcionaba dejó de funcionar por completo

Alguien de tu agencia puede haber revocado la conexión de ese cliente desde Configuración → Desarrollador → Conexiones MCP. Vuelve a conectarlo para obtener una nueva autorización.

«Tool not found» o falta una herramienta con un nombre similar

Los nombres de las herramientas son exactos y distinguen mayúsculas de minúsculas — revisa esta referencia para el nombre preciso. Si usas un cliente en modo «compacto» o «código», solo se listan directamente las herramientas de descubrimiento (search_os_tools, call_os_tool, …); úsalas para encontrar y llamar al resto por nombre.

Se rechaza una llamada a una herramienta por falta de acceso

La conexión solo tiene mcp:read (solo lectura) — vuelve a conectar y aprueba el acceso de escritura si la herramienta que llamas lo necesita.

Límites de solicitudes

Actualmente no hay un límite de solicitudes específico para las llamadas a herramientas MCP — a diferencia del límite de la API REST, basado en el plan y por agencia.