Serwer MCP

Model Context Protocol (MCP) to standard, którym asystenci AI rozmawiają z zewnętrznymi systemami. Mediflo wystawia zdalny serwer MCP, więc agent może czytać i zmieniać dane Twojej organizacji przez gotowe narzędzia, zamiast składać żądania HTTP z dokumentacji.

To ten sam produkt co REST API — te same dane i te same reguły. Zmienia się sposób wywołania i to, czym się uwierzytelniasz: człowiek loguje się kontem Mediflo, serwer używa klucza API.

Jak to działa

Dwie drogi uwierzytelnienia, jeden endpoint. Człowiek loguje się kontem Mediflo: Claude Code (/mcp → Authenticate) i konektor w Claude Desktop / claude.ai same odkrywają nasz serwer autoryzacji, otwierają przeglądarkę i proszą o zgodę. Serwer, zadanie CI albo klient bez przeglądarki wysyła klucz API w nagłówku Authorization: Bearer mflo_live_…, dokładnie jak w REST API. Klucz mintujesz w aplikacji: Ustawienia → Integracje → Klucze API.

Po zalogowaniu asystent działa jako Ty. Zakresy wyliczamy z Twoich uprawnień w aplikacji, więc podłączony asystent nie zrobi niczego, czego sam nie możesz zrobić w Mediflo. Samo podłączenie wymaga uprawnienia „Łączenie asystentów AI przez MCP” (mcp.connect); podłączonych asystentów odłączysz w Ustawienia → Integracje → MCP.

Zakresy decydują, co agent w ogóle zobaczy. Narzędzia, na które połączenie nie ma zakresu, nie pojawiają się w tools/list i nie da się ich wywołać — nie są rejestrowane dla Twojej sesji. Klucz bez tasks.write po prostu nie ma narzędzia create_task. To wygodne zabezpieczenie: agentowi do diagnostyki daj klucz tylko do odczytu, a nie zadzwoni do nikogo, nawet jeśli bardzo będzie chciał.

Serwer jest bezstanowy. Nie wydaje Mcp-Session-Id, nie sprawdza go i nie wymaga rundy initialize przed tools/list czy tools/call. Klienty, które i tak robią handshake, działają normalnie.

Kolejność narzędzi to instrukcja. tools/list zwraca je w kolejności konfiguracji bota: orientacja → wartości domyślne → utworzenie bota → konfiguracja → workflow → publikacja → weryfikacja. Czytanie listy od góry do dołu prowadzi przez cały happy path.

Co można zrobić

Postawić bota od zera — głosowego albo czat na stronie. create_bot tworzy bota już skonfigurowanego zgodnie z rekomendacjami Mediflo — modele, sposób prowadzenia rozmowy, model analizy po rozmowie. Pominięte channels oznacza kanały, z których organizacja może korzystać (czat, gdy plan go obejmuje; telefon, gdy są numery i boty głosowe). Do napisania zostaje prompt. Potem update_bot_config (dla czatu także channelSettings), publish_bot_config i get_bot_readiness. Nazwę, aktywność i kanały zmienisz od razu przez update_bot — to nie jest wersja robocza. Bot tylko czatowy nie dostaje numeru telefonu: widget, domeny i kolory ustawiasz w aplikacji (Ustawienia → Czat na stronie). Szczegóły: wersja robocza i publikacja.

Zdiagnozować rozmowę i zgłosić ją do nas. Sześć narzędzi zamyka pętlę dla klienta, który pracuje bez przeglądarki:

list_bot_sessions            →  znajdź sesję, na którą skarży się użytkownik
get_bot_session              →  jak się skończyła i co bot ustalił
get_bot_session_telemetry    →  DLACZEGO tak poszło (bez treści rozmowy)
get_bot_session_transcript   →  co dokładnie padło (osobne wywołanie, celowo)
create_support_ticket        →  zgłoś do Mediflo z dołączonymi botSessionIds
attach_sessions_to_ticket    →  powtórzyło się — to samo zgłoszenie, kolejne sesje

Telemetria i transkrypcja to dwa osobne wywołania z rozmysłem: telemetria niesie powody zakończenia, błędy SIP, opóźnienia i fałszywe przerwania — i żadnej treści rozmowy. Integracja, która potrzebuje tylko diagnostyki, nigdy nie musi odebrać wypowiedzi rozmówcy.

Dołączaj sesje do zgłoszenia. To one sprawiają, że wsparcie otwiera konkretną rozmowę zamiast pytać „którą?". Przy powtarzalnym problemie dołącz kilka — wzorzec między rozmowami zwykle jest diagnozą. Limit to 20 sesji na zgłoszenie.

Zadzwonić pod wskazany numer. create_bot_session jest jedynym narzędziem na tym serwerze, które dzwoni pod czyjś numer telefonu, i robi to natychmiast. Zawsze podawaj idempotencyKey, który możesz powtórzyć: ponowione żądanie zwróci istniejącą sesję z created: false zamiast wykonać drugie połączenie. Odmowy wracają jako błędy narzędzia z kodem REST (OUTSIDE_CALL_WINDOW, IDEMPOTENCY_KEY_REUSED, BOT_NOT_PUBLISHED, …). Wynik rozmowy nie jest w odpowiedzi — odpytaj get_bot_session albo poczekaj na webhook bot_call.completed.

Odebrać webhooki bez czytania dokumentacji. get_webhook_event_catalog zwraca katalog zdarzeń z przykładowymi payloadami, opisem podpisu i zasadami dostarczania — komplet do napisania odbiornika. Ludzka wersja tego samego: Webhooki.

Czego serwer nie robi

• Nie usuwa botów. Nie ma takiego narzędzia i nie będzie: Bot kasuje się twardo, bez deletedAt, więc zewnętrzne usunięcie byłoby nieodwracalne. Usuwanie zostaje w aplikacji.
• Nie zwraca sekretów webhooków. Sekret pokazujemy raz, przy utworzeniu i przy rotacji.
• Nie wydaje uprawnień, których nie masz. Logowanie nadaje asystentowi zakresy wyliczone z Twoich uprawnień w aplikacji — nie da się przez nie podnieść własnego dostępu. Operacje celowo zostawione poza tą ścieżką (m.in. dzwonienie i rezerwacje) wymagają klucza API z jawnie nadanym zakresem.

Limity i błędy

Limity zapytań i dziennik audytowy są te same co w REST, z jednym zastrzeżeniem: każde żądanie MCP liczy się do puli zapisów. Bucket wybieramy przed odczytaniem ciała żądania, a ten endpoint przyjmuje wywołania modyfikujące — łagodniejsze liczenie potrafiłoby nie doliczyć zapisu.

Błędy przychodzą jako JSON-RPC, nie jako REST-owa koperta error:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Rate limit exceeded for this API key",
    "data": { "retryAfterSeconds": 17 }
  }
}

Znaczenie niesie status HTTP: 401 dla brakującego, błędnego, wygasłego lub odwołanego poświadczenia (odpowiedź niesie wtedy nagłówek WWW-Authenticate, po którym klient sam rozpoczyna logowanie), 429 dla limitu (z nagłówkiem Retry-After), 503 gdy nasz weryfikator kluczy jest niedostępny. Reszta jest w rozwiązywaniu problemów.

Katalog narzędzi w wersji maszynowej: /api/mcp-tools.json.