Skip to content

types

Wire types and error codes for MCP Events (SEP-3415), shared by the server and client sides.

DeliveryError module-attribute 

DeliveryError = Literal[
    "connection_refused",
    "timeout",
    "tls_error",
    "http_4xx",
    "http_5xx",
    "challenge_failed",
]

The categories a server reports for a failing callback; never raw endpoint responses.

events_error 

events_error(code: int, **data: Any) -> MCPError

Build one of the SEP-3415 errors, with data as its typed payload.

Source code in src/mcp/experimental/events/types.py 
66
67
68
def events_error(code: int, **data: Any) -> MCPError:
    """Build one of the SEP-3415 errors, with `data` as its typed payload."""
    return MCPError(code=code, message=_ERROR_MESSAGES[code], data=data or None)

EventDescriptor

Bases: _Model

One event type, as listed by events/list.

Source code in src/mcp/experimental/events/types.py 
75
76
77
78
79
80
81
82
83
class EventDescriptor(_Model):
    """One event type, as listed by `events/list`."""

    name: str
    description: str | None = None
    delivery: list[DeliveryMode]
    input_schema: dict[str, Any]
    payload_schema: dict[str, Any]
    meta: dict[str, Any] | None = Field(default=None, alias="_meta")

EventOccurrence

Bases: _Model

One event, as returned by a poll or POSTed to a webhook.

Source code in src/mcp/experimental/events/types.py 
86
87
88
89
90
91
92
93
94
95
class EventOccurrence(_Model):
    """One event, as returned by a poll or POSTed to a webhook."""

    event_id: str
    name: str
    timestamp: datetime
    data: dict[str, Any]
    cursor: str | None = None
    """Subscription position after this event; webhook deliveries only."""
    meta: dict[str, Any] | None = Field(default=None, alias="_meta")

cursor class-attribute instance-attribute 

cursor: str | None = None

Subscription position after this event; webhook deliveries only.

ListEventsParams

Bases: PaginatedRequestParams

Parameters for events/list.

Source code in src/mcp/experimental/events/types.py 
98
99
class ListEventsParams(PaginatedRequestParams):
    """Parameters for `events/list`."""

ListEventsResult

Bases: PaginatedResult

Result of events/list.

Source code in src/mcp/experimental/events/types.py 
102
103
104
105
class ListEventsResult(PaginatedResult):
    """Result of `events/list`."""

    events: list[EventDescriptor]

PollEventsParams

Bases: RequestParams

Parameters for events/poll.

Source code in src/mcp/experimental/events/types.py 
108
109
110
111
112
113
114
115
class PollEventsParams(RequestParams):
    """Parameters for `events/poll`."""

    name: str
    arguments: dict[str, Any] | None = None
    cursor: str | None = None
    max_age_ms: int | None = Field(default=None, ge=0)
    max_events: int | None = Field(default=None, ge=1)

PollEventsResult

Bases: Result

Result of events/poll.

Source code in src/mcp/experimental/events/types.py 
118
119
120
121
122
123
124
125
class PollEventsResult(Result):
    """Result of `events/poll`."""

    events: list[EventOccurrence]
    cursor: str | None = None
    truncated: bool = False
    has_more: bool = False
    next_poll_ms: int

WebhookDelivery

Bases: _Model

Where and how to deliver a webhook subscription's events.

Source code in src/mcp/experimental/events/types.py 
128
129
130
131
132
133
class WebhookDelivery(_Model):
    """Where and how to deliver a webhook subscription's events."""

    mode: str = "webhook"
    url: str
    secret: str

WebhookTarget

Bases: _Model

The callback URL that identifies a webhook subscription on events/unsubscribe.

Source code in src/mcp/experimental/events/types.py 
136
137
138
139
class WebhookTarget(_Model):
    """The callback URL that identifies a webhook subscription on `events/unsubscribe`."""

    url: str

DeliveryStatus

Bases: _Model

How delivery to a webhook subscription is going, reported on refresh.

Source code in src/mcp/experimental/events/types.py 
142
143
144
145
146
147
148
class DeliveryStatus(_Model):
    """How delivery to a webhook subscription is going, reported on refresh."""

    active: bool
    last_delivery_at: datetime | None = None
    last_error: DeliveryError | None = None
    failed_since: datetime | None = None

SubscribeEventsParams

Bases: RequestParams

Parameters for events/subscribe.

Source code in src/mcp/experimental/events/types.py 
151
152
153
154
155
156
157
158
159
160
class SubscribeEventsParams(RequestParams):
    """Parameters for `events/subscribe`."""

    name: str
    arguments: dict[str, Any] | None = None
    delivery: WebhookDelivery
    cursor: str | None = None
    max_age_ms: int | None = Field(default=None, ge=0)
    ttl_ms: int | None = Field(default=None, ge=0)
    """Suggested lifetime; omitted means the server default, an explicit `None` asks for no expiry."""

ttl_ms class-attribute instance-attribute 

ttl_ms: int | None = Field(default=None, ge=0)

Suggested lifetime; omitted means the server default, an explicit None asks for no expiry.

SubscribeEventsResult

Bases: Result

Result of events/subscribe.

Source code in src/mcp/experimental/events/types.py 
163
164
165
166
167
168
169
170
class SubscribeEventsResult(Result):
    """Result of `events/subscribe`."""

    id: str
    refresh_before: datetime | None = None
    cursor: str | None = None
    truncated: bool = False
    delivery_status: DeliveryStatus | None = None

UnsubscribeEventsParams

Bases: RequestParams

Parameters for events/unsubscribe.

Source code in src/mcp/experimental/events/types.py 
173
174
175
176
177
178
class UnsubscribeEventsParams(RequestParams):
    """Parameters for `events/unsubscribe`."""

    name: str
    arguments: dict[str, Any] | None = None
    delivery: WebhookTarget

UnsubscribeEventsResult

Bases: Result

Result of events/unsubscribe.

Source code in src/mcp/experimental/events/types.py 
181
182
class UnsubscribeEventsResult(Result):
    """Result of `events/unsubscribe`."""