Skip to content

feat: Offer monitor events through the MCP Events extension, polled - #91

Merged
gkurt merged 4 commits into
mainfrom
gokhan/mcp-events
Nov 2, 2026
Merged

gkurt merged 4 commits into
mainfrom
gokhan/mcp-events

Conversation

@gkurt

@gkurt gkurt commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Why

Clients such as Canvas start work from events on a connector's MCP server through the MCP Events extension, io.modelcontextprotocol/events (SEP-3415, not merged yet). They subscribe as the team, so no model or session has to be there. With this PR, a client can start work when an Edge Delta monitor alerts, with no agent polling get_event_search.

This PR adds poll delivery only. The hosted server is stateless, and webhooks need a durable subscription store in the backend. That plan lives with the backend in the edgedelta repo.

What

  • initialize advertises the extension, through an AfterInitialize hook.
  • mcp-go sends methods it doesn't know to "method not found" and has no hook for custom ones, so the server answers events/list and events/poll before mcp-go sees them:
    • HTTP: MCPHTTPServer.Handler() wraps the Streamable HTTP server. HTTPServer() is unchanged, but it doesn't serve events.
    • stdio: stdin goes through a filter, and every response is written as one line.
  • Other events/* methods answer -32601.
  • Two event types, both delivered by polling:
    • monitor.alert: a monitor changes state. Arguments: monitorId, monitor, type, states, service, plus extra CQL in query.
    • pattern.anomaly: the same for pattern anomaly monitors, with the log patterns behind the anomaly in the payload.
  • Each event is the event search's own. Its eventId is the event's event.id. Its payload has a title and a url to the event in the app (the link monitor notifications use), plus the monitor's state, priority, service, message and values.
  • The cursor is a time plus the IDs delivered since that time:
    • The time stays two minutes behind now, because the search indexes events a little late. The IDs stop a later search from delivering anything twice.
    • maxAgeMs moves the cursor forward, and so does a seven-day limit. truncated is true only when that skipped an event.
    • maxEvents defaults to 50 and is capped at 100, with hasMore set when more are waiting. nextPollMs is 30000.
  • Errors use the SEP's provisional codes:
    • -32023 NotFound, with data.kind: "event".
    • -32602 for bad arguments, a cursor the server didn't issue, or CQL the search refuses.
    • -32024 when the token can't search events.
    • -32020, with HTTP 400, when an Mcp-Name header names a different event. The header isn't required yet.
  • New WithAppURL option. By default the app URL follows the API URL: staging gets app-staging.
  • The README has a new Events section.

Testing

  • Table-driven tests in pkg/events cover:
    • polling sequences: a null start, each event delivered once, events indexed late, backlogs drained in batches with ties at the same millisecond, and maxAgeMs with and without a gap;
    • every error;
    • the CQL built from arguments, and the payload mapping;
    • the JSON-RPC layer.
  • I checked that the tests fail when the lag is set to zero.
  • Tests in server cover initialize, events/list, the Mcp-Name check and core methods still reaching mcp-go over HTTP, and the stdio filter.
  • Run against prod over stdio: polls returned real monitor alerts and pattern anomalies (the anomalies with their patterns), and bad CQL in query came back as -32602.
  • Run with Canvas's own client (src/server/connectors/events.ts on the MCP SDK) against this branch over HTTPS. It listed both types and polled real events. Bad arguments came back as InvalidParams, an unknown type as NotFound and subscribe as MethodNotFound, and it sent Mcp-Name on every events/* request.
  • go test ./..., go vet and go mod tidy pass. golangci-lint reports nothing new; the 5 remaining issues are already on main.

Once this is tagged (v0.2.42), the edgedelta repo bumps to it and switches admin to Handler().

gkurt added 3 commits November 2, 2026 17:52
…ion (SEP-3415), polled

initialize advertises io.modelcontextprotocol/events, and the server answers
events/list and events/poll itself, before mcp-go, which has no hook for custom
methods: Handler() wraps the Streamable HTTP server and the stdio server
filters stdin. Other events/* methods are not found until webhooks come.

Two types, both polled: monitor.alert (a monitor changing state, narrowed by
monitor, type, states, service and extra CQL) and pattern.anomaly. Each event
is the event search's own, its eventId the event's event.id, with a title and
a url to it in the app.

The cursor is a watermark plus the IDs delivered at or after it: the
watermark trails now by two minutes, since search indexing is eventually
consistent, and the IDs keep a late search from repeating anything. maxAgeMs
and a seven-day replay ceiling move it on, truncated only when that skipped
an event.

@tuncerkaplankiran tuncerkaplankiran left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work overall, the stdio filter and the HTTP wrapper look solid to me (body is restored for mcp-go, batches and GET/DELETE fall through, lines don't interleave). Tests pass with -race too. Left a few comments, the first one is the one I'd fix before merging, it can drop events without setting truncated.

Comment thread pkg/events/poll.go Resolved
Comment thread pkg/events/poll.go Resolved
Comment thread pkg/events/types.go Resolved
… single millisecond, and keep the query argument in its group

A cursor holds at most 500 delivered IDs, so a poll caps its batch to
what the cursor can take, and when Seen is full of events at one
millisecond it moves past them and sets truncated, instead of jumping
silently. The event search refuses from == to, so a one-millisecond
range is searched with the next one and trimmed. The query argument has
to keep its parentheses and quotes balanced, read as CQL's lexer does,
so it can't close the group that keeps the monitor domain filter.
@gkurt
gkurt merged commit ecf3697 into main Nov 2, 2026
4 checks passed
gkurt added a commit that referenced this pull request Nov 2, 2026
Stacked on #91, which adds polling.

## Why

Polling runs a search for every subscription every 30 seconds, whether
or not anything happened. Webhooks post each event once, as soon as the
event search has it. The SEP's webhook mode needs server-side state, and
this server holds none. So the library takes a store from the host.
Admin, in the edgedelta repo, keeps subscriptions in DynamoDB and runs
delivery.

## What

- **`events/subscribe` and `events/unsubscribe`**, offered when the host
passes `server.WithEventSubscriptions(store, sender)` and puts each
caller's principal in the context (`events.WithPrincipal`). Each type
then lists `delivery: ["poll","webhook"]`.
- Subscriptions are keyed per the SEP by `(principal, url, name,
arguments)`. The `id` is a truncated SHA-256 of that key.
- Checks: `https` and a public address (`InvalidParams`); a `whsec_`
secret of 24 to 64 bytes; push or any other mode is `Unsupported`; no
principal is `Forbidden`.
- The verification challenge runs once per `(principal, url)` and is
cached for a day. A failure is `-32027` with `data.reason`.
- Grants are an hour at most. A revoked principal can't refresh, so it
stops getting events within the hour, with no access check on every run.
`ttlMs: null` gets the same finite hour.
- A refresh keeps the subscription's cursor, returns `deliveryStatus`,
resumes a suspended subscription, and dual-signs for ten minutes when
the secret changes.
- A new subscription with a cursor starts from it, with `maxAgeMs` and
`truncated` handled as in polling.
- **`Handler.Deliver(ctx, sub)`**, which the host runs when a
subscription's `NextRun` comes:
- It polls from the stored cursor and posts each event in order. Each
event is signed per Standard Webhooks, with `X-MCP-Subscription-Id` and
the cursor after that event as the safe-to-persist watermark.
- The cursor moves only past what the endpoint takes. A failure is
retried from there, with doubling backoff up to 15 minutes. After a day
of failures, delivery waits for the client's next refresh.
- A 413 skips its event. A 410 or a lapsed grant ends the subscription.
A stretch that had to be skipped gets a `gap` envelope. A principal that
may no longer search gets a `terminated` envelope.
- **`Sender`**: one HTTP client for challenges and deliveries.
- It follows no redirects and refuses addresses that aren't globally
routable. It checks this in the dialer's `Control`, so DNS rebinding
can't get past it.
  - It keeps bodies at 256 KiB or less.
  - `WithRootCAs` is for private deployments and tests.
- Polling is refactored so that the cursor after any number of a batch's
events can be computed; delivery needs that. Polling behaves as before.
- The README has a new Webhooks section.

## Testing

- Table-driven tests:
- Subscribe: create, refresh, rotation, one challenge per principal and
URL, and each error.
- Delivery: ordering, retry after a 503, 413, 410, a lapsed grant,
revoked access, the cursor and subscription header on each event, and
dual signing inside and after the overlap.
  - Backoff, and SSRF at both check and dial time.
  - Also `events/list` over HTTP with a store.
- Run end to end with Canvas's own client against a local server built
from this branch:
- The server used an in-memory store and searched prod. A local endpoint
verified signatures the way Canvas's `handleEventsWebhook` does.
- Subscribing from a cursor an hour back: one challenge, then that
hour's 23 ALERT events, all signed and verified, with no duplicates.
- The refresh returned the same `id` and its `deliveryStatus` with no
new challenge. Unsubscribing removed it, and a second unsubscribe
answered NotFound with `kind: "subscription"`.
- `go test ./...` and `go vet` pass, and golangci-lint reports only the
5 issues already on `main`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants