Troubleshooting

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

API key issues#

Every request authenticates with your API key, sent as an Authorization: Bearer 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, put the key in the config's env block.
• Ensure the key hasn't expired or been revoked.

mcp-remote bridge issues#

Most documented client configs launch a local bridge process that forwards stdio MCP traffic to the remote server:

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

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 mcp-remote --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, Windsurf, and Zed connect to the remote server natively with a Bearer header (Zed via context_servers). The bridge is only for clients without native remote-header support, such as Claude Desktop's OAuth-only connectors.

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.