Skip to content

docs: mark MCP Events as live on mcp.appwrite.io #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChiragAgg5k merged 1 commit into from
Oct 14, 2026
Merged

docs: mark MCP Events as live on mcp.appwrite.io #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ docker compose up --build

> MCP Events push delivery (`--events-push`) routes events between replicas
> through a Redis-protocol server (Dragonfly in the cluster) at
> `MCP_EVENTS_REDIS_URL`. Compose runs Dragonfly and points the server at it; see [flags.md](flags.md#--events-push--push-delivery-in-progress).
> `MCP_EVENTS_REDIS_URL`. Compose runs Dragonfly and points the server at it; see [flags.md](flags.md#--events-push--push-delivery).

**`uv` directly — HTTP:**

Expand Down
25 changes: 11 additions & 14 deletions docs/events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
# Events

> **Not a supported feature yet.** Events sit behind the `--events` testing
> flag ([#127](https://github.com/appwrite/mcp/issues/127)), which is off in
> production. They cannot work on Appwrite Cloud until
> [appwrite/appwrite#14293](https://github.com/appwrite/appwrite/issues/14293)
> lets a webhook's `authPassword` hold the sealed subscription.
> **Live on [mcp.appwrite.io](https://mcp.appwrite.io/)**, with webhook and
> push delivery. Self-hosted HTTP deployments turn them on with the `--events`

@hansi-codes hansi-codes Bot Oct 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Reconcile the self-hosted claim with the hosted-only statement

This now says self-hosted HTTP deployments can enable Events, but a few lines below the page says Events are served only by the hosted server at mcp.appwrite.io. Readers can't tell whether self-hosted HTTP is supported; please reconcile the two statements.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: docs/events.md
Line: 4

Comment:
**Reconcile the self-hosted claim with the hosted-only statement**

This now says self-hosted HTTP deployments can enable Events, but a few lines below the page says Events are served only by the hosted server at mcp.appwrite.io. Readers can't tell whether self-hosted HTTP is supported; please reconcile the two statements.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

🟡 Minor · documentation · Reply if this doesn't apply.

> and `--events-push` flags. The `stdio` transport has no Events.

[MCP Events](https://developers.openai.com/plugins/build/mcp-events) let an MCP
client subscribe to things that happen in an Appwrite project and hear about
Expand All @@ -22,10 +20,10 @@ delivery modes:
Each subscription is backed by one Appwrite webhook in the subscriber's
project, so the MCP server keeps no subscription store.

## Testing flag
## Flag

For testers only: [flags.md](flags.md#--events--mcp-events-in-progress) shows
how to turn the flag on locally and check it with `curl`.
[flags.md](flags.md#--events--mcp-events) shows how to turn the flag on locally
and check it with `curl`.

With the flag on, the server advertises the capability in both shapes that
clients read today:
Expand Down Expand Up @@ -271,7 +269,7 @@ result is sent then. When the server ends the stream (termination, shutdown, tok
expiry) it sends the empty result `{"_meta": {}}` as the final frame.

Push sits behind the `--events-push` flag
([flags.md](flags.md#--events-push--push-delivery-in-progress)) and needs a
([flags.md](flags.md#--events-push--push-delivery)) and needs a
Redis-protocol server (`MCP_EVENTS_REDIS_URL`): Dragonfly in the cluster, or
Redis; the bus uses only `PUBLISH`, `SUBSCRIBE` and `PING`. `events/list` advertises
`"delivery": ["webhook", "push"]` only when both are there; otherwise it
Expand Down Expand Up @@ -429,7 +427,7 @@ adapter around the package.
the JWE key directly. The webhook signing secret is derived from it with
HKDF-SHA256 under its own label, so the two never share a key.
- **Size.** The envelope must fit Appwrite's `authPassword`, which
appwrite/appwrite#14293 has to raise to at least 2048 characters. Sealing
appwrite/appwrite#14293 raised to 2048 characters. Sealing
refuses anything longer (`ENVELOPE_BUDGET`). Measured with 36-character ids,
key id `k1` and server `https://mcp.appwrite.io`:

Expand Down Expand Up @@ -590,7 +588,6 @@ run), otherwise `redis-server` (`brew install redis` or
`apt-get install redis-server`). Two server instances share it, so a stream
opened on one receives what Appwrite delivers to the other.

A live end-to-end run against Cloud staging (real OAuth tokens, real Appwrite
webhooks) is planned once
[appwrite/appwrite#14293](https://github.com/appwrite/appwrite/issues/14293)
ships; until then the server's surroundings are played locally.
Live runs against Cloud staging and production (real OAuth tokens, real
Appwrite webhooks) are done by hand; CI plays the server's surroundings
locally.
17 changes: 7 additions & 10 deletions docs/flags.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,17 +83,14 @@ Then run `/mcp` in Claude Code and authenticate — the browser should open the
override console's sign-in page, and after consent the client completes the
token exchange against the real authorization server.

### `--events` — MCP Events (in progress)
### `--events` — MCP Events

Turns on [MCP Events](events.md): `server/discover` (and legacy `initialize`)
advertise the events capability, the server answers `events/list`,
`events/subscribe` and `events/unsubscribe`, and the Appwrite webhook ingress
is mounted at `/appwrite/webhooks/{id}`. It is a testing flag, off by default
and in production, while the feature is built
([#127](https://github.com/appwrite/mcp/issues/127)): subscriptions cannot work
on Appwrite Cloud until
[appwrite/appwrite#14293](https://github.com/appwrite/appwrite/issues/14293)
ships. Any of `1`, `true`, `yes` or `on` enables it. With the flag on,
is mounted at `/appwrite/webhooks/{id}`
([#127](https://github.com/appwrite/mcp/issues/127)). Off by default; on at
`mcp.appwrite.io`. Any of `1`, `true`, `yes` or `on` enables it. With the flag on,
`MCP_EVENTS_SEALING_KEYS` is required and the server refuses to start without
it.

Expand Down Expand Up @@ -136,16 +133,16 @@ With the flag off, neither capability appears, `events/list`,
`events/subscribe` and `events/unsubscribe` return `-32601` (method not found)
and the ingress route returns `404`.

### `--events-push` — push delivery (in progress)
### `--events-push` — push delivery

Adds [push delivery](events.md#push-delivery) to MCP Events: `events/list`
advertises `"delivery": ["webhook", "push"]` and the server serves
`events/stream`, a long-lived request that streams the subscription's events
back ([#137](https://github.com/appwrite/mcp/issues/137)). It needs `--events`
and a Redis-protocol server (Dragonfly in the cluster, or Redis) at
`MCP_EVENTS_REDIS_URL`, which carries events from the replica Appwrite delivers
to the one holding the stream. With the flag on but no URL, the server logs it and serves webhook delivery only. Off by default, so
webhook delivery can stay live while push rolls out.
to the one holding the stream. With the flag on but no URL, the server logs it and serves webhook delivery only. Off by default; on at
`mcp.appwrite.io`.

**Enable it:**

Expand Down
Loading