Řešení problémů

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

Problémy s API klíčem#

Každý požadavek se autentizuje pomocí vašeho API klíče, odesílaného jako hlavička Authorization: Bearer. Pokud jsou volání nástrojů odmítána:

• Ověřte, že váš klíč začíná prefixem mgv_.
• Zkontrolujte, že jste zástupný symbol 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í dejte klíč přímo do bloku env v konfiguraci.
• Ujistěte se, že klíči nevypršela platnost a nebyl zneplatněn.

Problémy s mostem mcp-remote#

Většina zdokumentovaných konfigurací klientů spouští lokální proces mostu, který přeposílá stdio MCP provoz na vzdálený server:

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

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 mcp-remote --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, Windsurf a Zed se ke vzdálenému serveru připojují nativně pomocí hlavičky Bearer (Zed přes context_servers). Most je určen jen pro klienty bez nativní podpory vzdálených hlaviček, jako jsou konektory Claude Desktop fungující jen přes OAuth.

Repozitář nenalezen#

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

Problémy s připojením MCP#

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

Ověřte opravu#

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.