MCP Events

MCP Events pozwala klientowi MCP śledzić, co dzieje się w Bird bez odpytywania. Klient subskrybuje zdarzenie, na przykład nadejście e-maila do skrzynki pocztowej, a hostowany serwer Bird MCP wysyła każde pasujące zdarzenie na URL callbacku należący do klienta. Klient budzi agenta ze zdarzeniem, a agent reaguje na nie za pomocą narzędzi Bird.

MCP Events implementuje rozszerzenie wyzwalaczy i zdarzeń MCP z dostarczaniem przez webhooki. Protokół obsługuje klient MCP: podłączasz go do mcp.bird.com i prosisz o śledzenie wybranego zdarzenia. ChatGPT obsługuje to już teraz.

Zanim zaczniesz

• Połącz klienta z hostowanym serwerem pod adresem https://mcp.bird.com/ lub jego endpointem /dynamic. Endpoint /public i lokalny serwer bird mcp nie obsługują MCP Events.
• Zaloguj się na konto z uprawnieniami do zarządzania webhookami. Każda subskrypcja wymaga zakresu webhooks:write oraz zakresu odczytu danego zdarzenia, o które klient prosi podczas logowania.
• Użyj klienta obsługującego rozszerzenie i jego tryb dostarczania przez webhooki.

Zdarzenia, które możesz subskrybować

events/list zwraca zdarzenia, które Twoje logowanie może subskrybować, wraz z filtrami i schematem payloadu każdego z nich. Filtr zawęża subskrypcję do jednego zasobu: mailbox_id ustawiony na mbx_… dostarcza tylko pocztę przychodzącą do tej skrzynki. Zdarzenie bez filtrów dostarcza każde wystąpienie w obszarze roboczym.

Po utworzeniu skrzynki pocztowej przez serwer MCP odpowiedź sugeruje subskrypcję jej poczty, z wypełnionym zdarzeniem i mailbox_id.

Jak działa subskrypcja

1. Subskrybuj. Klient wywołuje events/subscribe ze zdarzeniem, jego filtrami, adresem URL callbacka i własnym sekretem podpisującym (whsec_…).
2. Zweryfikuj. Przed utworzeniem czegokolwiek wysyłamy podpisane {"type":"verification","challenge":"…"} na callback. Callback musi odpowiedzieć 2xx, którego treść JSON powtarza challenge, w ciągu 4 sekund.
3. Odbieraj. Każde pasujące zdarzenie dociera jako POST na callback, podpisane sekretem klienta.
4. Odnawiaj. Subskrypcja trwa do czasu refreshBefore, maksymalnie 24 godziny i minimum 5 minut od sugerowanego przez klienta ttlMs. Ponowne wywołanie events/subscribe z tym samym zdarzeniem, filtrami i callbackiem odnawia ją w miejscu. Nowy sekret podpisujący zastępuje poprzedni po zweryfikowaniu callbacka, a poprzedni podpisuje jeszcze przez 5 minut.
5. Zakończ. Klient wywołuje events/unsubscribe lub przestaje odnawiać, a subskrypcja wygasa.

Ponowna subskrypcja z tego samego logowania z tym samym zdarzeniem, filtrami i callbackiem jest idempotentna: odnawia istniejącą subskrypcję zamiast tworzyć nową.

Dostarczanie

Każde dostarczenie to żądanie zgodne ze Standard Webhooks:

• webhook-id zawiera ID zdarzenia, dzięki czemu klient może odrzucić powtórkę.
• webhook-timestamp i webhook-signature podpisują ciało żądania sekretem klienta.
• X-MCP-Subscription-Id wskazuje subskrypcję, dzięki czemu klient może wybrać swój sekret przed odczytaniem ciała żądania.

Ciało żądania to {"eventId", "name", "timestamp", "data", "cursor": null}, gdzie data jest ładunkiem zdarzenia opisanym przez events/list. Nie przechowujemy historii do ponownego odtworzenia, więc cursor zawsze ma wartość null.

Ciało żądania ma co najwyżej 256 KiB. Zdarzenie amb.received, które przekroczyłoby ten rozmiar, ma tekst wiadomości obcięty na granicy znaku i zawiera body_truncated: true; klient pobiera całą wiadomość za pomocą amb_get. Każde inne zdarzenie, które przekroczyłoby limit, nie jest wysyłane.

Nieudane dostarczenie jest ponawiane osiem razy w ciągu około ośmiu godzin, więc zdarzenie, na które reaguje Twój agent, nie jest nieaktualne, gdy dotrze. Jeśli callback odpowie 410 Gone lub 413 Content Too Large, odrzucamy to jedno zdarzenie i zachowujemy subskrypcję. Nieudane dostarczenia nigdy nie wstrzymują subskrypcji: kończy się ona, gdy wygaśnie jej dzierżawa.

Kiedy subskrypcja się kończy

Subskrypcja kończy się, gdy klient zrezygnuje z subskrypcji, gdy wygaśnie, lub gdy ktoś usunie ją w Bird, z listy Webhooks w dashboardzie lub przez API. Usunięcie natychmiast zatrzymuje dostarczanie, ale klient nie jest o tym informowany: dopóki przechowuje subskrypcję, tworzy ją ponownie przy następnym odnowieniu, ponownie weryfikując swój callback. Aby trwale zatrzymać subskrypcję, usuń ją również z klienta.

Jeśli logowanie powiązane z subskrypcją zostanie unieważnione lub utraci zakres odczytu zdarzenia, przestajemy dostarczać do niego zdarzenia, a subskrypcja wygasa w ramach swojej dzierżawy.

Wyświetl swoje subskrypcje

Każda subskrypcja jest endpointem webhooka w Twoim obszarze roboczym. Lista Webhooks w dashboardzie pokazuje każdą z nich wraz z logo klienta, zdarzeniem i filtrami, a także pozwala ją usunąć. Subskrypcje wliczają się do limitu endpointów webhooków w Twojej organizacji.

Rozwiązywanie problemów

Następne kroki

• Przekieruj wiadomości do swojego agenta AI wysyła wiadomości przychodzące do Claude Managed Agents lub Grok Bot przez konektor, bez MCP.
• Webhooks & events obejmuje weryfikację podpisu i katalog zdarzeń.
• Serwer MCP zawiera listę narzędzi, z których korzysta Twój agent.