# Troubleshooting

Canonical source: https://maguyva.ai/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).

Fix the common Maguyva setup failures: API key problems, @maguyva/mcp bridge issues, repository lookups, and connection errors.

### API key issues

- Verify your key starts with the mgv_ prefix.
- Check you replaced the mgv_xxxx placeholder from the config examples with your real key from app.maguyva.ai.
- If your config reads the key from MAGUYVA_API_KEY, confirm the variable is set in the environment your client actually launches from. Shell exports added to ~/.zshrc or ~/.bashrc only apply after reloading the shell, and GUI apps may not inherit them at all. When in doubt, write the key into the config itself: in the Authorization header of a native remote config (Bearer followed by your key), or in the env block of an @maguyva/mcp bridge config.
- Ensure the key hasn't expired or been revoked.

### @maguyva/mcp bridge issues

- Verify npx is available in your PATH -- the bridge needs a working Node.js install. Run npx -y @maguyva/mcp --help in a terminal to confirm it can start.
- Check your client's MCP configuration syntax -- a malformed JSON file fails silently in some clients.
- Many clients do not need the bridge at all. Claude Code uses the Maguyva plugin (/plugin install maguyva@maguyva), and Cursor, VS Code, Devin Desktop, and Zed connect to the remote server natively with a Bearer header (Zed via context_servers). The bridge is for clients that cannot send that header from their config, such as Claude Desktop, whose claude_desktop_config.json starts local servers only. Claude Desktop custom connectors can send an authorization request header, but request headers are in beta for a limited set of organizations.

### Repository not found

- Verify the repository is connected and indexed in app.maguyva.ai.
- Check the format: "owner/repo" targets the default branch, "owner/repo:branch" targets a specific branch (e.g. "owner/repository:develop").
- Ensure your account has access to the repository.
- Use repository_context(action="info", repository="...") to inspect repository resolution; omit the repository parameter only when your MCP client supplies a request default or the key can access exactly one repository.

### MCP connection issues

- Test connectivity to https://maguyva.tools/mcp from your machine -- corporate proxies and firewalls are the usual culprits.
- Check that your API token is valid and not expired.
- Re-check the client config against the Installation Guide for your client -- the config file location and shape differ per client.

### Verify the fix

After any change, ask your agent "What repositories do I have connected?" -- that verifies the connection end to end. Then ask a real question about your repo; you should see answers with file paths and line numbers from your connected repository.