Rozwiązywanie problemów

Większość problemów z konfiguracją mieści się w czterech kategoriach: klucz API nie dociera do serwera, mostek mcp-remote 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.

Problemy z kluczem API#

Każde żądanie uwierzytelnia się Twoim kluczem API, wysyłanym jako nagłówek Authorization: Bearer. 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 umieść klucz w bloku env konfiguracji.
• Upewnij się, że klucz nie wygasł ani nie został unieważniony.

Problemy z mostkiem mcp-remote#

Większość udokumentowanych konfiguracji klientów uruchamia lokalny proces mostka, który przekazuje ruch MCP przez stdio do zdalnego serwera:

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

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 mcp-remote --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, Windsurf i Zed łączą się ze zdalnym serwerem natywnie za pomocą nagłówka Bearer (Zed przez context_servers). Mostek jest potrzebny tylko klientom bez natywnego wsparcia dla nagłówków zdalnych, jak łączniki OAuth-only w Claude Desktop.

Nie znaleziono repozytorium#

• 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ć rozwiązanie 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.

Problemy z połączeniem MCP#

• 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ę klienta względem Przewodnik instalacji dla Twojego klienta — lokalizacja i kształt pliku konfiguracyjnego różnią się w zależności od klienta.

Zweryfikuj poprawkę#

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.