Rozwiązywanie problemów

Większość problemów z konfiguracją mieści się w czterech kategoriach: klucz API nie dociera do serwera, mostek @maguyva/mcp się nie uruchamia, repozytorium nie może zostać rozpoznane albo klient w ogóle nie może się połączyć. Przejdź do sekcji odpowiadającej Twojemu objawowi.

Każde żądanie uwierzytelnia się Twoim kluczem API, wysyłanym jako nagłówek Authorization: Bearer lub — gdy klient nie potrafi go ustawić — jako nagłówek X-API-Key. Jeśli wywołania narzędzi są odrzucane:

• Sprawdź, czy Twój klucz zaczyna się od prefiksu mgv_.
• Sprawdź, czy zastąpiłeś placeholder mgv_xxxx z przykładów konfiguracji swoim prawdziwym kluczem z app.maguyva.ai.
• Jeśli Twoja konfiguracja odczytuje klucz z MAGUYVA_API_KEY, upewnij się, że zmienna jest ustawiona w środowisku, z którego faktycznie uruchamia się Twój klient. Eksporty powłoki dodane do ~/.zshrc lub ~/.bashrc działają dopiero po ponownym załadowaniu powłoki — a aplikacje GUI mogą ich w ogóle nie dziedziczyć. W razie wątpliwości wpisz klucz bezpośrednio do konfiguracji: w nagłówku Authorization natywnej konfiguracji zdalnej (Bearer, a po nim Twój klucz) lub w bloku env konfiguracji z mostkiem @maguyva/mcp.
• Upewnij się, że klucz nie wygasł ani nie został unieważniony.

Jeśli klient używa mostu @maguyva/mcp, uruchamia lokalny proces łączący się ze zdalnym serwerem Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Jeśli serwer w ogóle nie pojawia się w Twoim kliencie albo pojawia się i natychmiast się rozłącza:

• Sprawdź, czy npx jest dostępny w Twoim PATH — mostek wymaga działającej instalacji Node.js. Uruchom npx -y @maguyva/mcp --help w terminalu, aby potwierdzić, że się uruchamia.
• Sprawdź składnię konfiguracji MCP swojego klienta — nieprawidłowo sformatowany plik JSON w niektórych klientach zawodzi bez żadnego komunikatu.
• Wiele klientów w ogóle nie potrzebuje mostka. Claude Code korzysta z pluginu Maguyva (/plugin install maguyva@maguyva), a Cursor, VS Code, Devin Desktop i Zed łączą się ze zdalnym serwerem natywnie za pomocą nagłówka Bearer (Zed przez context_servers). Mostek jest dla klientów, które nie mogą wysłać tego nagłówka ze swojej konfiguracji, jak Claude Desktop, którego claude_desktop_config.json uruchamia tylko serwery lokalne. Niestandardowe konektory Claude Desktop mogą wysyłać nagłówek żądania authorization, ale nagłówki żądań są w wersji beta dla ograniczonej liczby organizacji.

• Zweryfikuj, czy repozytorium jest podłączone i zaindeksowane w app.maguyva.ai.
• Sprawdź format: "owner/repo" celuje w domyślną gałąź, "owner/repo:branch" celuje w konkretną gałąź (np. "owner/repository:develop").
• Upewnij się, że Twoje konto ma dostęp do repozytorium.
• Użyj repository_context(action="info", repository="..."), aby sprawdzić rozpoznawanie repozytorium; pomijaj parametr repository tylko wtedy, gdy Twój klient MCP dostarcza domyślne ustawienie dla żądania lub gdy klucz ma dostęp dokładnie do jednego repozytorium.

• Przetestuj łączność z https://maguyva.tools/mcp ze swojej maszyny — firmowe proxy i firewalle to zwykle winowajcy.
• Sprawdź, czy Twój token API jest ważny i nie wygasł.
• Sprawdź jeszcze raz konfigurację swojego klienta według instrukcji w sekcji „Przewodnik instalacji” — lokalizacja i struktura pliku konfiguracyjnego różnią się w zależności od klienta.

Po każdej zmianie zapytaj swojego agenta "Jakie repozytoria mam połączone?" — to weryfikuje połączenie od początku do końca. Następnie zadaj prawdziwe pytanie o swoje repozytorium; powinieneś zobaczyć odpowiedzi ze ścieżkami plików i numerami linii z Twojego połączonego repozytorium.