Skip to content

The agent that grows with you

Merge pull request #140121 from Potrock/feat/mcp-events-webhook

Jeffrey Quesnelle4e58c721c8cf
diff --cc website/docs/reference/mcp-config-reference.md
index 0d4aab6f0ed,27381db2fe1..44d25bc19ba
--- a/website/docs/reference/mcp-config-reference.md
+++ b/website/docs/reference/mcp-config-reference.md
@@@ -68,10 -68,8 +68,11 @@@ 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 |
+| `tool_costs` | mapping | both | What each tool spends, keyed by the MCP tool name: a non-negative number, a `[min, max]` range, or `{credits: <number or range>, note: "per animation"}`. The approval prompt names the cost and the chat's running total. Undeclared and zero-cost tools are unaffected. See [Tool costs and spend limits](../user-guide/features/mcp.md#tool-costs-and-spend-limits) |
+| `spend_limit` | number | both | Per-chat budget for this server's costed tools (`0`/absent = no limit). A costed call that would take the chat past it asks first, even on a `trust: full` server, and is refused where nobody can answer (cron, `chat -q`) |
+| `cost_unit` | string | both | Label shown with costs and totals (default: `credits`) |
## Environment variable references
diff --cc website/docs/user-guide/features/mcp.md
index 06f4eb8f655,fe0f9f99ed8..27e77ef349d
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@@ -1023,14 -998,84 +1024,70 @@@ mcp_servers
The 5-minute default timeout mirrors the gateway approval default so users on async surfaces have time to respond before the server gives up. Per-server metrics (requests, accepted, declined, errors) are tracked on the handler.
+ ## MCP Events (experimental)
+
+ Some MCP servers can notify an agent when something happens upstream (a new email, an incident, a
+ new item in a feed) through the `events/*` methods of the
+ [MCP events design sketch](https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md).
+ The proposal is still a working-group draft. Hermes implements its **webhook** delivery mode: the
+ server POSTs each event to the gateway's [webhook listener](../messaging/webhooks.md), and every
+ event starts an agent run like any other webhook route.
+
+ Turn it on per server, and tell Hermes the public HTTPS address of the webhook listener (servers
+ reject plain-HTTP callbacks, so put a TLS-terminating reverse proxy or tunnel in front of port 8644):
+
+ ```yaml
+ mcp_servers:
+ ambush:
+ url: "https://example.com/mcp"
+ events: true # registers the event utility tools for this server
+
+ platforms:
+ webhook:
+ enabled: true
+ extra:
+ public_url: "https://hermes.example.com"
+ ```
+
+ The server then gets three more utility tools:
+
+ - `list_event_types`: the event types the server offers, and your current subscriptions to them
+ - `subscribe_event`: subscribe with the event's arguments, what to do when it arrives
+ (`instructions`, up to 2000 characters) and where each run's result goes (`deliver`,
+ `deliver_chat_id`). You are asked to approve every subscription, since it starts unattended agent
+ runs; the approval shows the instructions and the destination in full.
+ - `unsubscribe_event`: cancel a subscription
+
+ Each subscription is stored as a dynamic webhook route (`hermes webhook list` shows it) with its own
+ `whsec_` signing secret; the grant and the replay cursor are kept beside it in
+ `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). 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,
+ Hermes removes the route and tells the `deliver` target. Events only arrive while
+ `hermes gateway run` is running. The event payload reaches the run whole, up to 32,000 characters
+ of JSON, with a note when it is cut. Event payloads are external data: event runs use the same
+ constrained webhook toolset as other webhook routes.
+ The listener's per-route rate limit (`platforms.webhook.extra.rate_limit`, 30 a minute by default)
+ applies to event deliveries too; raise it for a busy event type, since a server may not retry a
+ rejected delivery.
+
+ Not supported yet: the `poll` and `push` delivery modes, and subscriptions made from a secondary
+ profile under `gateway.multiplex_profiles`.
+
## Running Hermes as an MCP server
-In addition to connecting **to** MCP servers, Hermes can also **be** an MCP server. This lets other MCP-capable agents (Claude Code, Cursor, Codex, or any MCP client) use Hermes's messaging capabilities — list conversations, read message history, and send messages across all your connected platforms.
-
-### When to use this
-
-- You want Claude Code, Cursor, or another coding agent to send and read Telegram/Discord/Slack messages through Hermes
-- You want a single MCP server that bridges to all of Hermes's connected messaging platforms at once
-- You already have a running Hermes gateway with connected platforms
-
-### Quick start
+Hermes can also **be** an MCP server, so Claude Code, Claude Desktop, Cursor, Codex or any MCP client can list and read your messaging conversations, wait for new messages and send messages across every platform Hermes is connected to, and optionally call Hermes' own web, browser, vision, image generation, skills and TTS tools. This ships as the official **mcp-serve** plugin:
```bash
-hermes mcp serve
+hermes plugins install mcp-serve
```
-This starts a stdio MCP server. The MCP client (not you) manages the process lifecycle.
-
-### MCP client configuration
-
-Add Hermes to your MCP client config. For example, in Claude Code's `~/.claude/claude_desktop_config.json`:
-
```json
{
"mcpServers": {