One agent hands out the work.
Paseo runs it.

1. Install the pluginPaseo clones it, runs npm ci and loads it. The HTTP server stays off.
2. Open the settings⌘K → MCP server, or Settings → Plugins → paseo-mcp. Add your allowed roots.
3. Create a token per clientLabel and scope: read for the list/read tools and events, full for everything. Optionally limited to agents with a label. It is shown once.
4. Turn the server on and connectCopy the ready snippet for Hermes or Claude Code (CLI or .mcp.json) from the same screen.

Copypaseo plugin install github:MaxGierlachowski/paseo-mcp

Hermes, in ~/.hermes/config.yaml:

mcp_servers:
  paseo:
    url: "http://127.0.0.1:6790/mcp"
    headers:
      Authorization: "Bearer <token>"
    timeout: 300

Claude Code:

Copyclaude mcp add --transport http paseo-agents http://127.0.0.1:6790/mcp --header "Authorization: Bearer <token>"

• A stable command. ~/.local/bin/paseo-mcp is rewritten on every load and follows plugin updates. A file the plugin did not write is never touched.
• Test connection. Starts the server exactly like a client, lists the tools and counts the agents.
• Status at a glance. Config file, allowed roots, accounts and how the server signs in; the credential stays masked.
• Copyable configs for Hermes, Claude Code (.mcp.json and CLI) and any stdio client.

mcp_servers:
  paseo:
    command: "/Users/you/.local/bin/paseo-mcp"
    env:
      PASEO_MCP_CONFIG: "/Users/you/.config/paseo-mcp/config.json"
    timeout: 300

Cursor in, cursor out

# a consistent start: state plus a cursor
paseo_list_agents
  → { agents: [...], events_cursor: "mw7z…:41" }

paseo_wait_for_events cursor="mw7z…:41"
    timeout_sec=120 only_needs_attention=true
  → { events: [...], next_cursor: "mw7z…:44", gap: false }

# always continue with next_cursor
paseo_wait_for_events cursor="mw7z…:44" …

Filters: agent_ids, labels, types, only_needs_attention, limit. A token can be limited to labels such as origin=hermes.

Guarantees

• Ordered: seq grows within an epoch; webhooks may overlap, sort by seq.
• At least once: repeats only right after a list or a gap; skip them by id.
• No silent loss: a cursor older than the buffer (1000 events, 60 min) or from before a restart gets gap: true and the current state.
• Metadata only: no message content, except an opt-in preview marked untrusted.

# POST, application/json
Paseo-Mcp-Signature: t=1794150672,v1=<hex>
Paseo-Mcp-Delivery:  mw7z…:3      # same on every retry
Paseo-Mcp-Event-Id:  mw7z…:3

{ "delivery_id": "mw7z…:3", "sent_at": "…",
  "events": [ { "type": "agent.turn_ended", … } ] }

Copy// verify over the raw body, before parsing
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const mac = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1 ?? "", "hex");
  return given.length === mac.length && timingSafeEqual(given, mac);
}

Answer 2xx fast. Errors, timeouts, 408, 429 and 5xx are retried up to 6 times (1, 2, 4, 8, 16 s). After 5 failed deliveries in a row the endpoint pauses until you resume it. A Python example is in the README.