Solución de problemas

La mayoría de las fallas de configuración caen en cuatro categorías: la API key no llega al servidor, el bridge de mcp-remote 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.

Problemas con la API key#

Cada solicitud se autentica con tu API key, enviada como un header Authorization: Bearer. Si se rechazan las llamadas a herramientas:

• Verifica que tu key empiece con el prefijo mgv_.
• Revisa que hayas reemplazado el placeholder mgv_xxxx de los ejemplos de configuración con tu key real de app.maguyva.ai.
• Si tu configuración lee la key 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, pon la key en el bloque env de la configuración.
• Asegúrate de que la key no haya expirado ni haya sido revocada.

Problemas del bridge mcp-remote#

La mayoría de las configuraciones de cliente documentadas lanzan un proceso bridge local que reenvía el tráfico MCP por stdio al servidor remoto:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

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 mcp-remote --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, Windsurf y Zed se conectan al servidor remoto de forma nativa con un header Bearer (Zed vía context_servers). El bridge solo es para clientes sin soporte nativo de remote-header, como los conectores solo-OAuth de Claude Desktop.

Repositorio no encontrado#

• 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.

Problemas de conexión MCP#

• 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.

Verifica la solución#

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.