Rozwiązywanie problemów
Brakujące narzędzie, błąd -32001, nagłówki, limit 1 MB i inne odmowy serwera MCP — co znaczą i co z nimi zrobić.
Przeglądarka się otworzyła, ale nie mogę podłączyć asystenta
Strona zgody mówi, że nie masz uprawnienia do łączenia asystentów AI — i nie wyda żadnego tokenu. Poproś administratora o uprawnienie „Łączenie asystentów AI przez MCP” (mcp.connect). Administratorzy i supervisorzy mają je domyślnie, konsultantowi trzeba je nadać.
To uprawnienie decyduje wyłącznie o tym, czy wolno podłączyć asystenta. O tym, co asystent może potem zrobić, decydują Twoje pozostałe uprawnienia — samo mcp.connect nie daje dostępu do żadnych danych.
Jeśli zamiast tego chcesz podłączyć serwer albo zadanie CI, użyj klucza API — tamta ścieżka nie wymaga mcp.connect.
Strona zgody mówi, że adres nie jest dozwolony
Logowanie kontem Mediflo przekazuje dostęp pod adres, który podaje sama aplikacja — dlatego bez decyzji administratora dozwolone są tylko zweryfikowane adresy: claude.ai, claude.com i Twój własny komputer (Claude Code). Każdy inny adres strona zgody odrzuca, bo nazwę aplikacji może wpisać ktokolwiek — liczy się tylko adres.
Jeśli ufasz tej aplikacji, poproś administratora (uprawnienie „Zarządzanie kontrolą dostępu i ustawieniami bezpieczeństwa”) o dodanie jej adresu w Ustawienia → Integracje → MCP → Dozwolone adresy asystentów AI. Przy łączeniu zobaczysz wtedy ostrzeżenie o niezweryfikowanym adresie, które trzeba potwierdzić, zanim przycisk Zezwól się odblokuje.
Zadanie zaplanowane w claude.ai nie łączy się z Mediflo
Objaw: w zwykłej rozmowie narzędzia Mediflo działają, ale zadanie zaplanowane (np. codzienny raport) kończy się komunikatem, że nie udało się połączyć z konektorem, albo wysyła pusty raport.
Przyczyna: konektor w claude.ai jest skonfigurowany z kluczem API. W zadaniach uruchamianych w tle claude.ai tego klucza nie dołącza, więc serwer odrzuca żądanie jako nieuwierzytelnione albo zadanie poddaje się, zanim do nas dotrze.
Co zrobić:
- W claude.ai: Ustawienia → Konektory → usuń konektor Mediflo.
- Dodaj własny konektor z adresem
https://app.mediflo.ai/api/external/mcp, bez klucza API i bez tokenu. - Kliknij Połącz, zaloguj się kontem Mediflo i kliknij Zezwól.
- W ustawieniach zadań zaplanowanych upewnij się, że nowy konektor jest do nich włączony.
Stary klucz API możesz potem unieważnić w Ustawienia → Integracje → Klucze API.
Agent nie widzi narzędzia, którego oczekiwałeś
To prawie zawsze brak zakresu, nie brak narzędzia. Narzędzie, na które klucz nie ma zakresu, nie jest w ogóle rejestrowane dla Twojej sesji: nie ma go w tools/list, a tools/call zgłasza je jako nieznane.
Zacznij od get_server_info — działa z każdym ważnym poświadczeniem i zwraca zakresy połączenia oraz dokładną listę narzędzi, którą ono widzi. Porównaj ją z katalogiem narzędzi: brakujący wiersz od razu wskaże zakres, którego nie masz.
Zakresy klucza zmienisz w aplikacji: Ustawienia → Integracje → Klucze API (pełna lista: zakresy). Po zalogowaniu kontem Mediflo zakresów nie ustawia się ręcznie — wynikają z Twoich uprawnień w aplikacji i odświeżają się w ciągu godziny po ich zmianie. Zakres webhook-payloads.read nadaje się tylko jawnie — nie wchodzi w żaden wildcard, bo daje dostęp do treści dostarczonych webhooków.
Klient zapamiętał starą listę
Po zmianie zakresów odśwież połączenie w kliencie (w Claude Code: /mcp, w
Cursorze i VS Code przełącznik serwera). Lista narzędzi jest budowana przy
połączeniu, więc do czasu odświeżenia agent widzi poprzedni zestaw.
Błędy, które możesz zobaczyć
| Objaw | Co się stało | Co zrobić |
|---|---|---|
401 i -32001 „API key is missing or invalid" | Klucz nie istnieje, jest błędny albo nagłówek nie doszedł. | Sprawdź nagłówek Authorization: Bearer mflo_live_…. Klucz pokazujemy raz — jeśli go nie masz, wygeneruj nowy. |
401 i -32001 „API key has expired" / „has been revoked" | Klucz wygasł albo został odwołany. | Wygeneruj nowy w aplikacji. Nazywamy te dwa przypadki wprost, bo naprawa jest inna. |
429 i -32001 „Rate limit exceeded" | Przekroczony limit zapytań. Odpowiedź niesie Retry-After i data.retryAfterSeconds. | Odczekaj tyle, ile mówi nagłówek. Każde żądanie MCP liczy się do puli zapisów. |
503 i -32001 | Nasz weryfikator kluczy jest chwilowo niedostępny. To nasza awaria, nie Twój klucz. | Ponów za chwilę. Nie rotuj klucza. |
400 i -32600 „JSON-RPC batching is not supported" | Klient wysłał tablicę wiadomości. | Jedna wiadomość na żądanie. Batching zniknął ze specyfikacji MCP w wersji 2025-06-18. |
400 i -32700 „request body is not valid JSON" | Ciało żądania nie sparsowało się jako JSON. | Sprawdź Content-Type: application/json i escapowanie w powłoce. |
413 i -32600 „Request body exceeds the 1048576-byte limit" | Ciało większe niż 1 MB. | Wywołanie narzędzia to zwykle kilkaset bajtów. Prześlij duże treści (np. bazę wiedzy) jako źródło z adresem URL, nie w argumencie. |
400 „Unsupported protocol version" | Klient zażądał wersji protokołu, której Twoja organizacja nie negocjuje: spoza 2024-10-07 … 2025-11-25, albo 2026-07-28, jeśli nie włączyliśmy jej dla organizacji. | Klienty MCP wracają wtedy same do wspieranej wersji — odpowiedź ją wymienia (kod -32000; po włączeniu 2026-07-28 kod -32022 z listą w data.supported). Przy surowym curlu pomiń nagłówek MCP-Protocol-Version albo ustaw wspieraną wersję. |
400 i -32602 „…missing the required per-request envelope key(s)…" albo „Invalid _meta envelope…" | (Organizacje z włączoną 2026-07-28.) Nagłówek MCP-Protocol-Version wskazuje 2026-07-28, ale ciało żądania nie niesie koperty params._meta albo brakuje w niej protocolVersion lub clientCapabilities. | W 2026-07-28 każde żądanie zawiera kopertę _meta — klienty MCP dodają ją same. Przy surowym curlu pomiń nagłówek (żądanie bez koperty obsłużymy jak dotąd) albo dołącz kopertę — przykład w instalacji. |
400 i -32020 „the request headers and body disagree" | (Organizacje z włączoną 2026-07-28.) Nagłówki nie zgadzają się z ciałem: MCP-Protocol-Version wskazuje inną wersję niż koperta, brakuje Mcp-Method albo wskazuje inną metodę, brakuje Mcp-Name przy tools/call albo wskazuje inne narzędzie niż params.name. | Wysyłaj nagłówki lustrzane do ciała — klienty MCP robią to same. Przy surowym curlu sprawdź zwłaszcza Mcp-Name. |
405 z nagłówkiem Allow: POST | Klient spróbował GET. | Endpoint przyjmuje wyłącznie POST. Bez sesji nie ma osobnego strumienia SSE do otwarcia. |
404 i -32601 przy subscriptions/listen | (Organizacje z włączoną 2026-07-28.) Klient poprosił o strumień powiadomień o zmianach. | Serwer jest bezstanowy i nie wysyła powiadomień — server/discover ogłasza listChanged: false. Listę narzędzi odświeżysz zwykłym tools/list. |
Transport odrzuca POST, zanim narzędzie się uruchomi | Brakuje typu w nagłówku Accept. | Wyślij Accept: application/json, text/event-stream — oba typy są wymagane. Klienty MCP robią to same; przy surowym curlu trzeba je dopisać. |
Nie licz na kod -32001 przy rozróżnianiu przyczyn
Uwierzytelnianie, limit zapytań i awaria weryfikatora dzielą ten sam kod
JSON-RPC -32001 (blok -32000..-32099 zarezerwowany przez JSON-RPC 2.0 na
błędy implementacji). Rozróżnia je status HTTP i pole data, nie kod.
Błędy z samego narzędzia
Wszystko, co dzieje się po tym, jak żądanie dotrze do serwera MCP — nieznane narzędzie, złe argumenty, odmowa narzędzia — wraca jako zwykła odpowiedź JSON-RPC albo wynik z flagą isError, a nie jako błąd HTTP. Treść jest po angielsku i pisana pod agenta, więc zwykle wystarczy przekazać ją modelowi.
Dwa przypadki warto znać:
- Konflikt wersji roboczej. Jeśli konfiguracja zmieniła się od Twojego odczytu, zapis jest odrzucany komunikatem „przeczytaj ponownie". Ponawianie bez ponownego odczytu nigdy nie zadziała — to konflikt deterministyczny.
- Odmowa połączenia.
create_bot_sessionzwraca kod REST-owy (OUTSIDE_CALL_WINDOW,IDEMPOTENCY_KEY_REUSED,BOT_NO_OUTBOUND_NUMBER,BOT_NOT_PUBLISHED, …) plus jedną linię podpowiedzi, więc agent wie, co zmienić przed kolejną próbą.
Ogólny komunikat „Tool nazwa failed. Retry, or contact support if it persists." oznacza nasz błąd wewnętrzny — szczegóły zostają w naszych logach z rozmysłem, bo mogłyby cytować dane osobowe, w tym dane wrażliwe. Jeśli się powtarza, zgłoś to przez create_support_ticket z dołączonymi botSessionIds.
Zmiana konfiguracji nie działa
Sprawdź, czy była publikacja. update_bot_config zmienia tylko wersję roboczą — cała reguła jest w wersji roboczej i publikacji. To najczęstsze „narzędzie zwróciło sukces, a nic się nie zmieniło" na tym serwerze.
Bot nie odbiera, nie dzwoni albo nie odpowiada na czacie
get_bot_readiness mówi, czego brakuje, osobno dla czatu (readyForWebChat) i dla połączeń wychodzących (readyForOutbound). Bot tylko przychodzący i bot tylko czatowy mają readyForOutbound: false całkiem legalnie. Do wychodzących potrzeba podpiętego numeru z gotowym trunkiem SIP. Do czatu na stronie potrzeba widgetu podpiętego w aplikacji (Ustawienia → Czat na stronie) — serwer MCP tego nie zrobi. Nie dokładaj numeru telefonu botowi, który tylko pisze.
Nadal nie działa
Zbierz dowody i przekaż je nam: list_bot_sessions → get_bot_session → get_bot_session_telemetry, a potem create_support_ticket z botSessionIds. Dołączona sesja to różnica między „coś nie działa" a zgłoszeniem, które wsparcie może otworzyć od razu.