Skip to content

The agent that grows with you

docs(mcp): add the events key to the config reference

emozillaa05c6475fde2
diff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.md
index 86b311a1a30..27381db2fe1 100644
--- a/website/docs/reference/mcp-config-reference.md
+++ b/website/docs/reference/mcp-config-reference.md
@@ -68,6 +68,7 @@ mcp_servers:
| `auth` | string | HTTP | Authentication method. Set to `oauth` to enable OAuth 2.1 with PKCE |
| `sampling` | mapping | both | Server-initiated LLM request policy (see MCP guide) |
| `elicitation` | mapping | both | Server-initiated user-input requests. `enabled` (default `true`) and `timeout` in seconds (default `300`). Form-mode requests route through the approval surface; URL-mode is declined (see MCP guide) |
+| `events` | bool | both | Experimental MCP events client with webhook delivery (default: `false`). Registers `list_event_types`, `subscribe_event` and `unsubscribe_event` for this server. Needs `platforms.webhook.extra.public_url` (HTTPS) and a running gateway. Hermes refreshes subscriptions only while it is connected to the server, so with `lazy: true` or `idle_timeout_seconds` a subscription can lapse until the next connection resubscribes it. See [MCP Events](../user-guide/features/mcp.md#mcp-events-experimental) |
| `trust` | string | both | Trust tier: `full` (default) or `untrusted`. On an `untrusted` server, every write-capable tool call (any tool without a `readOnlyHint: true` annotation) requires user approval through the standard approval surface before it runs. `readOnlyHint` is a server-supplied *hint* — a lying server can at most skip approval for tools it claims are read-only, never gain extra access — so mark any server you don't fully control as `untrusted`. The same hint decides whether a call is transparently retried after the transport session expires mid-call: only `readOnlyHint: true` tools are replayed, while unannotated (write-capable) tools return an `outcome_uncertain` error — on a Streamable-HTTP server that expires idle sessions this means the first unannotated call after an idle period may fail and must be verified before re-invoking. Unrecognized values are treated as `untrusted` (fail-closed) A portable package can request `untrusted` for its own server in `plugin.json` (see [Portable Agent Plugins](../developer-guide/plugins/index.md#portable-agent-plugins-v1-packages)); a `config.yaml` entry with the same name always wins |
## Environment variable references
@@ -162,6 +163,11 @@ Prompts:
- `list_prompts`
- `get_prompt`
+Events (only on servers with `events: true`):
+- `list_event_types`
+- `subscribe_event`
+- `unsubscribe_event`
+
### Disable resources
```yaml
@@ -185,6 +191,9 @@ So this is normal:
- but no prompt utilities appear
- because the server does not support prompts
+The event utilities are the exception. The MCP SDK drops a server's `events` capability while parsing
+it, so Hermes cannot check for it and registers them whenever `events: true` is set.
+
## `enabled: false`
```yaml
diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md
index df4134a53a4..fe0f9f99ed8 100644
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@ -503,6 +503,7 @@ Hermes reads MCP config from `~/.hermes/config.yaml` under `mcp_servers`.
| `max_lifetime_seconds` | number | Recycle a stdio server after this total age (`0` = never, default). Restarts transparently on next use. |
| `enabled` | bool | If `false`, Hermes skips the server entirely |
| `supports_parallel_tool_calls` | bool | If `true`, tools from this server may run concurrently |
+| `events` | bool | If `true`, register the experimental MCP events tools for this server (default `false`). See [MCP Events](#mcp-events-experimental) |
| `tools` | mapping | Per-server tool filtering and utility policy |
### Minimal stdio example
@@ -1036,7 +1037,9 @@ Each subscription is stored as a dynamic webhook route (`hermes webhook list` sh
`mcp_event_subscriptions.json`, so the route itself only changes when you resubscribe with different
instructions or a different destination. Hermes answers the server's signed verification challenge, deduplicates
events by `eventId`, and refreshes the subscription before the lifetime the server granted runs out
-while the MCP connection is up (and again whenever it reconnects). A refresh the server refuses
+while the MCP connection is up (and again whenever it reconnects). With `lazy: true` or
+`idle_timeout_seconds` the connection is not always up, so a subscription can lapse until the next
+connection resubscribes it. A refresh the server refuses
for good (access revoked, event type removed, arguments no longer valid) removes the route; other
failures are retried with back-off. Turning the route off in the webhook dashboard lets the
subscription lapse, and turning it back on resubscribes it. If the server ends a subscription,