Support MCP events in the Appwrite MCP server #127

Goal

Let ChatGPT (and other MCP clients) subscribe to things that happen in a user's Appwrite project and receive a signed webhook when they occur.

"When a function execution fails in project X, read the logs and open a fix."
"When a row is added to support_tickets, triage it."

Scope: hosted mcp.appwrite.io (Streamable HTTP + OAuth) only. v1 is webhook delivery only, because that is all ChatGPT supports. Local stdio is out of scope.

Specs: OpenAI: MCP Events · WG design sketch (merged 2026-09-08) · SEP-3415 Events Extension (draft, opened 2026-10-05)

Blockers

How it works

 ChatGPT                       mcp.appwrite.io (stateless, any replica)    Appwrite project
 ───────                       ────────────────────────────────────────    ────────────────
    │  server/discover  ───────▶  capabilities.events
    │  events/list      ───────▶  catalog (6 events)
    │
    │  events/subscribe ───────▶  1. validate args, https URL, whsec_ secret
    │  (bearer token,            2. authorize: read target resource ─────────▶ GET table/function/bucket
    │   url, secret)             3. verify callback ◀─── challenge POST ───┐
    │                            4. upsert webhook (id = subscription id) ───▶ POST/PUT /webhooks
    │                               authPassword = sealed envelope              │
    │  ◀── {id, refreshBefore}   (nothing stored on our side)                   │
    │                                                                           │
    │                                                            row created ───┤
    │                            ingress /appwrite/webhooks/{id} ◀──────────────┘ Basic auth = envelope
    │                            5. verify HMAC, open envelope, check expiry + filter, ACK
    │  ◀── signed POST ───────── 6. strip to IDs, Standard Webhooks sign, retry in-process
    │
    │  events/subscribe (again, before refreshBefore) → re-check access, new envelope
    │  events/unsubscribe ─────▶ DELETE /webhooks/{id}

Where the state lives

No database. Each subscription is one Appwrite webhook in the user's project, and everything needed to deliver is sealed inside it:

Any replica can serve any request or delivery, and restarts lose nothing. Verified end to end on a local Cloud stack with real OAuth tokens (spike branch spike/events-stateless): two replicas, restart, expiry, refresh, rotation, unsubscribe.

Spec cheat sheet

Methods

All results carry resultType: "complete" (2026-07-28 protocol).

Subscribe rules

Delivery

Error codes

The codes are being renumbered (SEP-3415 / WG PR #11), so keep them behind constants. Ship the ChatGPT values for now.

data.reason ∈ challenge_failed, timeout, connection_refused, tls_error, http_4xx, http_5xx.

Capability advertisement: send both

Event catalog

Every event takes a required project_id. Payloads carry IDs and metadata only (ids, status, timestamps, error code); the agent fetches details with appwrite_call_tool.

Who benefits

v1

Execution failures are a separate event, not execution.completed with a filter: successful executions are high-volume noise for an agent.

Later

Excluded

Notes

• eventId = hash(X-Appwrite-Webhook-Delivery-Id, subscription id). The delivery id is md5(eventId:webhookId) and is identical on every Appwrite retry, so dedup is stable.
• Appwrite payloads are the full response model: whole rows, and users with email, phone and prefs. The ingress must project them down to the payloadSchema fields and never forward the raw body.
• Appwrite webhooks filter only by event name; status filters are applied at our ingress.
• Executions served through function domains fire no event, so execution.failed does not cover HTTP traffic to function domains.

Current footprint

Plan

Risks

Open questions

Done when

• Encrypted and length-limited attributes return 500 instead of 400 (webhooks authPassword/authUsername/url, variables value) appwrite#14293 is shipped to Cloud.
• server/discover at 2026-07-28 returns capabilities.events (both shapes); events/list returns the v1 catalog (6 events), filtered to what the caller can access.
• events/subscribe validates arguments, secret and URL; authorizes; runs the verification handshake (cached); returns a deterministic id, refreshBefore, cursor: null and truncated: false; idempotent across refresh and rotation.
• A matching Appwrite change → exactly one Standard-Webhooks-signed POST ≤ 256 KiB. Non-matching changes → no POST.
• Retries are bounded and re-signed; no retry on 410/413; works with 2+ replicas and survives a pod restart with no shared store.
• SSRF tests pass (private, loopback, link-local, IPv6 ULA, DNS rebinding, redirects).
• events/unsubscribe stops delivery and removes the managed webhook; expired subscriptions stop and get cleaned up.
• ChatGPT checklist passes on staging, then production, behind a flag.
• docs/events.md, README, metrics and Sentry tags are in place.

2026-10-12 — monitoring dashboards

• appwrite-labs/monitoring#605: Events row on dashboards/Cloud/mcp.json for mcp_events_subscriptions_total, mcp_events_deliveries_total, mcp_events_ingress_total (covers Plan step 9 observability panels).