Solución de problemas

La mayoría de las fallas de configuración caen en cuatro categorías: la clave de API no llega al servidor, el bridge de @maguyva/mcp no arranca, no se puede resolver el repositorio, o el cliente no logra conectarse en absoluto. Revisa la sección que coincida con tu síntoma.

Cada solicitud se autentica con tu clave de API, enviada como un header Authorization: Bearer o, si un cliente no puede establecerlo, como un header X-API-Key. Si se rechazan las llamadas a herramientas:

• Verifica que tu clave empiece con el prefijo mgv_.
• Revisa que hayas reemplazado el marcador mgv_xxxx de los ejemplos de configuración con tu clave real de app.maguyva.ai.
• Si tu configuración lee la clave desde MAGUYVA_API_KEY, confirma que la variable esté definida en el entorno desde el que tu cliente realmente se lanza. Los exports de shell agregados a ~/.zshrc o ~/.bashrc solo aplican después de recargar el shell — y las apps con interfaz gráfica pueden no heredarlos en absoluto. Si tienes dudas, escribe la clave directamente en la configuración: en el header Authorization de una configuración remota nativa (Bearer seguido de tu clave), o en el bloque env de una configuración con el bridge @maguyva/mcp.
• Asegúrate de que la clave no haya expirado ni haya sido revocada.

Si tu cliente utiliza el bridge @maguyva/mcp, inicia un proceso local que se conecta al servidor remoto de Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Si el servidor nunca aparece en tu cliente, o aparece y se desconecta de inmediato:

• Verifica que npx esté disponible en tu PATH — el bridge necesita una instalación funcional de Node.js. Ejecuta npx -y @maguyva/mcp --help en una terminal para confirmar que puede arrancar.
• Revisa la sintaxis de la configuración MCP de tu cliente — un archivo JSON mal formado falla en silencio en algunos clientes.
• Muchos clientes no necesitan el bridge en absoluto. Claude Code usa el plugin de Maguyva (/plugin install maguyva@maguyva), y Cursor, VS Code, Devin Desktop y Zed se conectan al servidor remoto de forma nativa con un header Bearer (Zed vía context_servers). El bridge es para clientes que no pueden enviar ese header desde su configuración, como Claude Desktop, cuyo claude_desktop_config.json solo inicia servidores locales. Los conectores personalizados de Claude Desktop pueden enviar un header de solicitud authorization, pero los headers de solicitud están en beta para un número limitado de organizaciones.

• Verifica que el repositorio esté conectado e indexado en app.maguyva.ai.
• Revisa el formato: "owner/repo" apunta a la rama predeterminada, "owner/repo:branch" apunta a una rama específica (por ejemplo, "owner/repository:develop").
• Asegúrate de que tu cuenta tenga acceso al repositorio.
• Usa repository_context(action="info", repository="...") para comprobar la resolución del repositorio; omite el parámetro de repositorio únicamente cuando el cliente MCP proporcione un valor predeterminado para la solicitud o la clave pueda acceder exactamente a un repositorio.

• Prueba la conectividad a https://maguyva.tools/mcp desde tu máquina — los proxies corporativos y los firewalls suelen ser los culpables.
• Verifica que tu token de API sea válido y no haya expirado.
• Vuelve a revisar la configuración del cliente contra Guía de instalación para tu cliente — la ubicación y forma del archivo de configuración difieren según el cliente.

Después de cualquier cambio, pregúntale a tu agente "¿Qué repositorios tengo conectados?" — eso verifica la conexión de punta a punta. Luego haz una pregunta real sobre tu repo; deberías ver respuestas con rutas de archivo y números de línea de tu repositorio conectado.