Troubleshooting

Most setup failures fall into four buckets: the API key is not reaching the server, the @maguyva/mcp bridge is not starting, the repository cannot be resolved, or the client cannot connect at all. Work through the section that matches your symptom.

Every request authenticates with your API key, sent as an Authorization: Bearer header or, where a client cannot set one, an X-API-Key header. If tool calls are rejected:

• 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 a @maguyva/mcp bridge config.
• Ensure the key hasn't expired or been revoked.

If your client uses the @maguyva/mcp bridge, it launches a local process that connects to Maguyva's remote server:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

If the server never appears in your client, or appears and immediately disconnects:

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

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

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

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.