--- title: "MCP Events" description: "Subskrybuj zdarzenia Bird w kliencie MCP, takie jak nowy e-mail w skrzynce pocztowej lub przychodzący SMS, i odbieraj każde z nich jako podpisany webhook na mcp.bird.com." canonical: "https://bird.com/pl-pl/dokumentacja/ai/mcp-events" --- # 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](/docs/ai/mcp-server) 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](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) 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ć | Zdarzenie | Zakres odczytu | Filtry | | -------------------------------- | --------------- | --------------------------------- | | `email_mailbox.message_received` | `mailbox:read` | `mailbox_id`, `thread_id` | | `email.delivered` | `emails:read` | `broadcast_id` | | `sms.received` | `sms:read` | `to`, Twój numer w formacie E.164 | | `whatsapp.received` | `whatsapp:read` | brak | | `amb.received` | `amb:read` | brak | `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](https://www.standardwebhooks.com/): - `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 | Błąd | Co oznacza | Co zrobić | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `-32015` `CallbackEndpointError` | Callback nie przeszedł weryfikacji. `data.reason` to `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` lub `challenge_failed`. | Udostępnij callback publicznie przez HTTPS i zwróć `challenge` w ciągu 4 sekund. | | `-32013` z `data.limit: "subscriptions"` | Organizacja nie ma wolnych endpointów webhooków. | Usuń endpoint, którego już nie potrzebujesz, a następnie zasubskrybuj ponownie. | | `-32013` z `data.limit: "rate"` | Zbyt wiele weryfikacji callbacka w krótkim czasie. | Poczekaj, a następnie spróbuj ponownie wysłać to samo żądanie. | | `-32012` | Sesja logowania nie ma uprawnienia odczytu dla zdarzenia lub `webhooks:write`. `data.required` wskazuje brakujące uprawnienie. | Zaloguj się ponownie i przyznaj je. | | `-32602` | Filtr, którego zdarzenie nie obsługuje, lub callback, który nie jest HTTPS. | Użyj filtrów, które zwraca `events/list`. | ## Następne kroki - [Przekieruj wiadomości do swojego agenta AI](/docs/ai/route-messages-to-an-agent) wysyła wiadomości przychodzące do Claude Managed Agents lub Grok Bot przez konektor, bez MCP. - [Webhooks & events](/docs/guides/webhooks) obejmuje weryfikację podpisu i katalog zdarzeń. - [Serwer MCP](/docs/ai/mcp-server) zawiera listę narzędzi, z których korzysta Twój agent. ## Related resources - [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video) - [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer) - [Coding agents](/ai) (product) - [Build with AI agents](/learn/paths/agents) (course) [Get an implementation brief](/learn/workspace?topic=agents)