Řešení problémů

Většina selhání při nastavení spadá do čtyř kategorií: API klíč se nedostává na server, most @maguyva/mcp se nespouští, repozitář se nedaří rozpoznat, nebo se klient vůbec nemůže připojit. Projděte si sekci, která odpovídá vašemu příznaku.

Každý požadavek se autentizuje pomocí vašeho API klíče, odesílaného jako hlavička Authorization: Bearer nebo — pokud ji klient neumí nastavit — jako hlavička X-API-Key. Pokud jsou volání nástrojů odmítána:

• Ověřte, že váš klíč začíná prefixem mgv_.
• Zkontrolujte, že jste zástupný text mgv_xxxx z ukázek konfigurace nahradili svým skutečným klíčem z app.maguyva.ai.
• Pokud vaše konfigurace čte klíč z MAGUYVA_API_KEY, ověřte, že je proměnná nastavená v prostředí, ze kterého se klient skutečně spouští. Exporty shellu přidané do ~/.zshrc nebo ~/.bashrc se projeví až po znovunačtení shellu — a GUI aplikace je nemusí zdědit vůbec. V případě pochybností zapište klíč přímo do konfigurace: do hlavičky Authorization v nativní vzdálené konfiguraci (Bearer a za ním váš klíč), nebo do bloku env v konfiguraci s mostem @maguyva/mcp.
• Ujistěte se, že klíči nevypršela platnost a nebyl zneplatněn.

Pokud váš klient používá můstek @maguyva/mcp, spustí místní proces, který se připojí ke vzdálenému serveru Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Pokud se server ve vašem klientovi nikdy neobjeví, nebo se objeví a hned se odpojí:

• Ověřte, že je npx dostupný ve vaší PATH — most potřebuje funkční instalaci Node.js. Spuštěním npx -y @maguyva/mcp --help v terminálu ověřte, že se dá spustit.
• Zkontrolujte syntaxi MCP konfigurace svého klienta — poškozený JSON soubor u některých klientů selže potichu.
• Mnoho klientů most vůbec nepotřebuje. Claude Code používá plugin Maguyva (/plugin install maguyva@maguyva) a Cursor, VS Code, Devin Desktop a Zed se ke vzdálenému serveru připojují nativně pomocí hlavičky Bearer (Zed přes context_servers). Most je určen pro klienty, kteří tuto hlavičku nedokážou poslat ze své konfigurace, například Claude Desktop, jehož claude_desktop_config.json spouští jen lokální servery. Vlastní konektory Claude Desktop umějí poslat hlavičku požadavku authorization, ale hlavičky požadavků jsou v betě jen pro omezený počet organizací.

• Ověřte, zda je úložiště připojeno a indexováno v app.maguyva.ai.
• Zkontrolujte formát: "owner/repo" cílí na výchozí větev, "owner/repo:branch" cílí na konkrétní větev (např. "owner/repository:develop").
• Ujistěte se, že váš účet má přístup k úložišti.
• Pomocí repository_context(action="info", repository="...") zjistěte, jak se repozitář vyhodnotí; parametr repository vynechte pouze tehdy, když klient MCP poskytuje výchozí hodnotu pro daný požadavek nebo když má klíč přístup právě k jednomu repozitáři.

• Otestujte konektivitu k https://maguyva.tools/mcp ze svého počítače — obvyklými viníky bývají firemní proxy a firewally.
• Zkontrolujte, že je váš API token platný a nevypršel.
• Znovu zkontrolujte konfiguraci klienta oproti Instalační příručka pro vašeho klienta — umístění a tvar konfiguračního souboru se u jednotlivých klientů liší.

Po jakékoli změně se svého agenta zeptejte na "Jaké repozitáře mám připojené?" — tím ověříte připojení od začátku do konce. Pak položte skutečnou otázku o svém repozitáři; měli byste vidět odpovědi s cestami k souborům a čísly řádků z vašeho připojeného repozitáře.