# Solución de problemas

Canonical source: https://maguyva.ai/es/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Soluciona las fallas comunes de configuración de Maguyva: problemas con la clave de API, problemas del bridge @maguyva/mcp, búsquedas de repositorios y errores de conexión.

### Problemas con la clave de API

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

### Problemas del bridge @maguyva/mcp

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

### 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 la 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.