---
title: Venom for agents (one MCP server for notes, tasks and flags)
description: Connect Claude Code, Cursor, ChatGPT or any MCP client to Venom Notes, Tasks, Flags, Forms, Incidents and Experiments through one endpoint, edit notes and issue descriptions with anchored edits, search both apps at once, and run many steps in one round trip.
section: cloud
order: 245
audience: [user, operator, agent]
sources: [services/nodejs-cloud/app/workspace/mcp,  services/nodejs-cloud/lib/mcp/names.ts, services/nodejs-cloud/lib/webhooks/workspace.ts, services/nodejs-cloud/lib/mcp/limits.ts, services/nodejs-cloud/components/tasks/settings/AgentAccess.tsx, services/nodejs-cloud/migrations/0144_agent_scope_webhook_cursors.sql, services/nodejs-cloud/app/api/workspace/agents/route.ts, services/nodejs-cloud/components/workspace/ConnectAgent.tsx, services/nodejs-cloud/lib/workspace/connect.ts, services/nodejs-cloud/migrations/0138_mcp_idempotency.sql, services/nodejs-cloud/migrations/0141_change_feed.sql, services/nodejs-cloud/lib/globe/changes.ts, services/nodejs-cloud/lib/mcp, services/nodejs-cloud/lib/globe/mcp, services/nodejs-cloud/lib/tasks/mcp, services/nodejs-cloud/lib/flags/mcp, services/nodejs-cloud/lib/oauth/pure.ts, services/nodejs-cloud/lib/mcp/listing.ts, services/nodejs-cloud/lib/mcp/listing-store.ts, services/nodejs-cloud/migrations/0375_mcp_connection_listing.sql, services/nodejs-cloud/app/(console)/(shell)/connect/page.tsx, docs/adr/0052-agent-native-access.md]
features: [cloud.workspace, cloud.console-connect]
---

Venom's notes (Venom Notes), issues (Venom Tasks) and feature flags (Venom Flags) share one MCP server, and so do the experiments of Venom Experiments. An agent
connects once and gets every app's tools, a search across them, anchored edits and a batch tool that runs many steps in one round trip.

- **Endpoint:** `https://cloud.usevenom.dev/workspace/mcp`. It uses Streamable HTTP: JSON-RPC over POST, and a
  notification stream on GET for resources you subscribe to.
  A self-hosted Venom Cloud serves the same path on its own origin.
- **Credentials:** a Venom API key as a bearer token, or OAuth for apps that sign in through a browser. The endpoint
  never reads a cookie.
- **The per-app servers stay:** [`/globe/mcp`](/docs/integrations/globe-mcp), [`/tasks/mcp`](/docs/cloud/tasks-mcp)
  and [`/flags/mcp`](/docs/developers/flags) answer as before (the Notes one gains `globe_note_edit` too). Use `/workspace/mcp` for new connections.

## Connect

**Connect once, then switch products on.** Add one server, `https://cloud.usevenom.dev/workspace/mcp`, and sign in. That
connection reaches every product your access allows. To keep the agent's context small it lists only the cross-product
`workspace_*` tools at first; you then pick, per connection, which products it also lists.

The quickest way is the **Connect an agent** page (`/connect`): in the sidebar's first section, in the account menu, and
linked from Home and from Notes', Tasks', Flags' and Experiments' settings.

1. **Pick your agent.** Choose Claude Code, Claude, ChatGPT, Cursor, VS Code, Codex or venom and copy one line, or click
   **Add to Cursor** or **Add to VS Code**. Clients that can sign in through your browser do so. For Claude Code, Cursor
   and VS Code you can tick **Use a personal API key** instead; **Create a personal key** opens Settings → API keys.
2. **Your connections.** Every app you connected, when it was last used, and **Disconnect**, which stops its tokens at
   once. A connection to `/workspace/mcp` also shows a switch per product, with the number of tools each adds, and the
   connection's total.
3. **Advanced.** A connector limited to one product (`/workspace/mcp/<product>`, [below](#per-product)), for people who
   want exactly that.

By hand, Claude Code:

```bash
claude mcp add --transport http venom https://cloud.usevenom.dev/workspace/mcp
```

then `/mcp` to sign in. With a personal key (Settings → API keys, "This key is mine") add
`--header "Authorization: Bearer vck_…"`. ChatGPT, Claude and other apps that connect by URL take
`https://cloud.usevenom.dev/workspace/mcp` and run the same sign-in. Cursor, VS Code and other clients that read a JSON
config:

```json
{ "mcpServers": { "venom": { "url": "https://cloud.usevenom.dev/workspace/mcp" } } }
```

### Switching products on {#listing}

Each product you switch on for a connection adds its `core` set of tools ([tool sets](#finding-tools); Admin, which has
no `core`, adds `members`) to what `/workspace/mcp` lists for that connection. Tasks adds about 25 tools, Notes about 20.
The rest of a product's tools are not listed but still run, and `workspace_tool_search` finds them.

**A switch is not access.** It changes only what the agent sees in its tool list. The agent can call any tool its
connection's scopes allow whether the product is switched on or not, and a switch never adds a scope. To limit what an
agent may do, untick scopes when you connect it, or use a [scoped service agent](#agent-access).

- **Default:** nothing switched on, for every connection, old and new. A connection's tool list (and its prompt cache)
  changes only when you change its switches.
- **The cost:** the page shows the tools each product adds and the connection's total, with a rough token count. Above
  80 tools it warns: at roughly 280 tokens per tool definition that is about 22,000 tokens, a tenth of a 200k window spent
  before the first turn, and agents pick the right tool less reliably from long lists. The workspace tools plus Notes'
  and Tasks' core sets (61 tools) stay under it.
- **When it applies:** `initialize` on `/workspace/mcp` over an OAuth connection declares `tools.listChanged`. When you
  change the switches, the connection's notification stream (`GET /workspace/mcp` with its `Mcp-Session-Id`) sends
  `notifications/tools/list_changed`, and a client that follows it lists the tools again. A client that does not open
  the stream sees the new list when it reconnects (in Claude Code, `/mcp` → reconnect).
- **Per OAuth connection.** A Venom API key has no stored switches: put the products on its URL instead,
  `/workspace/mcp?products=tasks,globe&set=core`. That URL then serves only those products.
- **An explicit URL wins.** `?products=`, `?set=` and `/workspace/mcp/<product>` list exactly what they did; the switches
  apply only to plain `/workspace/mcp`.
- **Agents can read and change it too.** `workspace_listing_get` reads a connection's switches and counts (this one by
  default, or another of your own by id from `workspace_agent_list`). `workspace_listing_set` changes them, for the
  connection the agent is calling through only (`products` replaces the list; `add` and `remove` edit it). Since a switch
  costs context and never grants access, an agent may switch products on for itself. Neither tool is in the default
  listing (that would change every connected client's tool list); `workspace_tool_search` finds them. REST:
  `GET /api/v1/listing` and `PUT /api/v1/listing` with a token issued for `/workspace/mcp`. Each change is audited as
  `workspace.listing_set`.

### One server per product {#per-product}

There are over a thousand tools in all (the [MCP servers](/docs/developers/mcp) page has the current count), and listing
them costs context in every session. Besides the one connection [above](#listing), each product has its own endpoint, `/workspace/mcp/<product>`, that lists and runs only
that product's tools, and you connect it as its own server (Claude Code shows `venom-tasks`, `venom-globe` and so on).
Credentials, rate limits, sessions, the change feed and OAuth are shared, so one sign-in covers all of them.

| Product | Endpoint | Server name | Tools | Scopes |
|---|---|---|---|---|
| Notes | `/workspace/mcp/globe` | `venom-globe` | 92 | `globe:read` `globe:write` |
| Tasks | `/workspace/mcp/tasks` | `venom-tasks` | 221 | `tasks:read` `tasks:write` |
| Flags | `/workspace/mcp/flags` | `venom-flags` | 42 | `flags:read` `flags:write` |
| Forms | `/workspace/mcp/forms` | `venom-forms` | 19 | `forms:read` `forms:write` |
| Incidents | `/workspace/mcp/incidents` | `venom-incidents` | 56 | `incidents:read` `incidents:write` `incidents:admin` |
| Experiments | `/workspace/mcp/exp` | `venom-experiments` | 25 | `experiments:read` `experiments:write` |
| People | `/workspace/mcp/people` | `venom-people` | 135 | `people:read` `people:write` |
| Funnel | `/workspace/mcp/funnel` | `venom-funnel` | 38 | `funnel:read` `funnel:write` |
| Support | `/workspace/mcp/support` | `venom-support` | 26 | `support:read` `support:write` |
| Chat | `/workspace/mcp/chat` | `venom-chat` | 32 | `chat:read` `chat:write` |
| Status page | `/workspace/mcp/status` | `venom-status` | 16 | `status:read` `status:write` |
| Comms | `/workspace/mcp/comms` | `venom-comms` | 27 | `comms:read` `comms:write` |
| Calendar | `/workspace/mcp/calendar` | `venom-calendar` | 41 | `calendar:read` `calendar:write` |
| Admin | `/workspace/mcp/admin` | `venom-admin` | 269 | `admin:read` `admin:write` |
| Org | `/workspace/mcp/org` | `venom-org` | 10 | `org:read` `org:write` |
| Computers | `/workspace/mcp/computers` | `venom-computers` | 36 | `computers:read` `computers:write` |
| Agents | `/workspace/mcp/agents` | `venom-agents` | 48 | `agents:read` `agents:write` |
| Studio | `/workspace/mcp/studio` | `venom-studio` | 30 | `studio:read` `studio:write` |

(The tool counts are checked against the code by a test; `experiments` also works for `exp` in a path or `?products=`.
Funnel has its own scopes; a connection made with `people:read` and `people:write` before that still opens Funnel's tools.)

To connect Notes and Tasks in Claude Code:

```bash
claude mcp add --transport http venom-globe https://cloud.usevenom.dev/workspace/mcp/globe
claude mcp add --transport http venom-tasks https://cloud.usevenom.dev/workspace/mcp/tasks
```

then run `/mcp` to sign in to each. The Claude Code plugin does this for you: `/venom:connect` asks which products you
want and runs one command each, reading your cloud URL from `venom cloud login` or `VENOM_CLOUD_URL`.

**The combined endpoint lists only the cross-product tools.** `/workspace/mcp` lists `workspace_item_search`,
`workspace_batch_run`, `workspace_change_list`, `workspace_agent_list`, the [reference tools](/docs/cloud/references.md), the [finding tools](#finding-tools) and `workspace_product_list`: the last names each
product, what it does, its tool count, scopes and the exact connect command. A product's tool still runs on the combined
endpoint when you call it by name, alone or in `workspace_batch_run`, so existing scripts keep working; it just is not
listed. Switch products on for the connection ([above](#listing)) to list their core sets too, or use
`/workspace/mcp?products=all` (or `?products=tasks,globe`) to list every tool of those products.

`workspace_batch_run` is on every per-product endpoint, held to that product's tools. `workspace_item_search` and
`workspace_change_list` are on `/workspace/mcp/workspace` and the combined endpoint. A tool of another product is "unknown" on a per-product endpoint.

Claude Code:

```bash
claude mcp add --transport http venom-tasks https://cloud.usevenom.dev/workspace/mcp/tasks --header "Authorization: Bearer vck_…"
claude mcp add --transport http venom-flags https://cloud.usevenom.dev/workspace/mcp/flags --header "Authorization: Bearer vck_…"
```

Cursor (`.cursor/mcp.json`), VS Code and any client that reads a JSON config:

```json
{ "mcpServers": {
  "venom-tasks": { "url": "https://cloud.usevenom.dev/workspace/mcp/tasks", "headers": { "Authorization": "Bearer vck_…" } },
  "venom-globe": { "url": "https://cloud.usevenom.dev/workspace/mcp/globe", "headers": { "Authorization": "Bearer vck_…" } }
} }
```

Other clients take the URL and sign in through the browser. To keep one server but narrow it, add a filter to the combined
URL: `https://cloud.usevenom.dev/workspace/mcp?products=tasks,flags` (an unknown product is a 400 naming the real ones).

### Finding tools {#finding-tools}

Over a thousand tools are too many to hand an agent at once, and Tasks alone has about two hundred. Two tools let an agent
find and call the one it needs without listing the rest, and tool sets let a client connect only the part of a product it
works with.

**`workspace_tool_search`** takes the task in plain words and answers the tools that do it, best first, one line each: name,
title, product, set, whether it reads or writes, the OAuth scope it needs, and the first sentence of its description. No
schemas, so an answer is a few hundred tokens.

```json
{ "query": "move issue to cycle" }
```

```text
Tools for "move issue to cycle", best first:
- tasks_issue_update — Update an issue (tasks, core, write; tasks:write): Change an issue's fields: state, assignee (a person), delegate (an agent), priority, labels, estimate, project, cycle, title or description.
- tasks_cycle_update — Change a cycle (tasks, planning, write; tasks:write): Rename or move a cycle's dates.
```

It takes `products` (only those products' tools), `writes` (`true` for tools that change something, `false` for reads)
and `limit` (default 10, at most 25). It finds only tools the endpoint serves (on `/workspace/mcp/tasks`, Tasks' tools)
and that your credential may call: a product closed to it, a scope your app was not granted, or a write when it may only
read, and the tool is left out. Matching is on the words of the tool's name, title, description and argument names, with
plural and verb endings folded and a few everyday synonyms ("sprint" is a cycle, "remind me" a reminder, "linked to
ENG-12" the item's links); it runs in the server's memory in well under a millisecond.

**`workspace_tool_get`** takes up to 10 names and answers each tool's full definition exactly as `tools/list` would give
it (description, `inputSchema` with any `idempotency_key`, annotations), with its product, set and scope. A name the
endpoint does not serve, or your credential may not call, answers `found: false` with why and the closest names. Then call
the tool by name: every endpoint runs its products' tools whether it lists them or not.

Both are read only, need no scope beyond a connection, and answer as tool results: they never change the session's tool
list, so a client's prompt cache holds.

**Tool sets.** Each product's tools are in named sets, every tool in exactly one. Add `?set=` to a product endpoint
(`/workspace/mcp/tasks?set=core`, or `?products=tasks&set=core` on the combined one) and it lists only those sets plus
`workspace_tool_search`, `workspace_tool_get` and `workspace_batch_run`. Every other tool of the product still runs when
called by name, so the agent reaches the rest through search. `set` takes a comma list (`?set=core,planning`); `set=all`
is the whole product. An unknown set is a 400 naming the product's sets. Without `set` an endpoint lists exactly what it
listed before sets existed: existing connections see no change.

```bash
claude mcp add --transport http venom-tasks "https://cloud.usevenom.dev/workspace/mcp/tasks?set=core"
```

| Product | Sets |
|---|---|
| Tasks | `core`, `collaboration`, `planning`, `triage`, `config`, `data` |
| Notes | `core`, `databases`, `admin` |
| Admin | `members`, `keys-and-providers`, `routing`, `governance`, `ops` |
| People | `core`, `relationships`, `events`, `curation` |

Every other product has one set, `core`, holding all its tools. Tasks' `core` (about 25 tools) is issue search, read,
create, update, claim and progress, comments, teams, members, states, labels, relations, links, cycles, projects and
agents; `workspace_product_list` shows every product's sets with their tool counts and the URL that lists each.

### OAuth

The server's protected resource metadata (RFC 9728) is at `/.well-known/oauth-protected-resource/workspace/mcp` (and `…/workspace/mcp/<product>` for a per-product endpoint, which names that endpoint as its resource), and a 401 from
`/workspace/mcp` points there. The 401's `WWW-Authenticate` also carries `scope="…"`: the scopes to ask for, the
metadata's `scopes_supported` less any `:admin` one, so a client can choose without reading the metadata first. The
metadata names the cloud's one authorization server, shared with Notes and Tasks. The resource is
`https://<cloud>/workspace/mcp` and its scopes are `globe:read`, `globe:write`, `tasks:read`, `tasks:write`,
`flags:read`, `flags:write`, `forms:read`, `forms:write`, `incidents:read`, `incidents:write`, `incidents:admin` (not granted by default), `experiments:read`, `experiments:write`, and the same `:read` and `:write` pair for `people`, `funnel`, `support`, `chat`, `status`, `comms`, `calendar`, `admin` and `org` ([every product's scopes](/docs/developers/auth#scopes)). One consent connects every product the app asks for; `admin:read` and `admin:write` are not in the combined endpoint's default grant. The `incidents_*` tools (errors, incidents and on-call) of [Venom Incidents](/docs/developers/incidents) are in the same list. An app granted without `globe:read` (or `flags:read`, `forms:read`, or `incidents:read`)
is refused the Notes (or Flags) tools in words; without `tasks:write` or `flags:write`, that app's writes are refused. The connection shows in Settings → Connected apps as "Venom Notes, Tasks, Flags, Forms, Incidents and Experiments".

#### Scopes per endpoint

A connection asks for as little as it needs, and the metadata an MCP client reads (`scopes_supported`) lists only that.

| Endpoint | Asks for by default | Admin |
|---|---|---|
| `/workspace/mcp/<product>` (`globe`, `tasks`, `flags`, `forms`, `incidents`, `exp`, `people`, `funnel`, `support`, `chat`, `status`, `comms`, `calendar`, `admin`, `org`) | that product's `:read` and `:write` (on `/workspace/mcp/admin` that is `admin:read` and `admin:write`) | never `incidents:admin` |
| `/workspace/mcp` | `:read` and `:write` on every product except Admin | only when the app asks for it (`admin:read`, `admin:write`, `incidents:admin`) |

An app that sends `scope=` gets at most that: it can narrow, never widen. On a product endpoint, scopes of other products
are dropped; if nothing is left the request is refused with `invalid_scope`. The consent screen lists the scopes grouped by
product, in plain words. Read is always on; you can untick write or admin before you allow, and the token holds exactly
what you ticked. Connections made before this keep the scopes they were granted.

A tool outside the connection's scopes answers with an error that names the missing scope and how to reconnect, for
example `tasks:write`: remove the connection, add `https://<cloud>/workspace/mcp/tasks` again (Claude Code:
`claude mcp add --transport http venom https://<cloud>/workspace/mcp/tasks`, then `/mcp` to sign in) and keep the scope
ticked.

## Who the agent is

The same as on the per-app servers: a personal key or an OAuth app acts for its member, a shared key (not a member's) reads the shared
vaults and, in Tasks, acts as the service agent an admin bound to it. Your role is the ceiling. Every write is audited
and shows "via MCP" with the agent's name. See [Venom Tasks for agents](/docs/cloud/tasks-mcp) for delegates and claims.

## Tools

Every caller sees the same list, in the same order, so a client's cached tool definitions (and its prompt cache) stay
valid. A call the credential may not make is refused with a sentence saying why.

| Tool | What it does |
|---|---|
| `globe_vault_list`, `globe_note_search`, `globe_note_get`, `globe_note_list`, `globe_note_ask`, `globe_note_related` | reads in Notes |
| `globe_note_write`, `globe_suggestion_create` | create, append or replace a note; file suggestions for a person to apply |
| `globe_database_*`, `globe_row_*`, `globe_view_*`, `globe_note_property_update` | databases (tables) inside notes: create, rows, schema, views, import, properties ([Notes databases for agents](/docs/cloud/globe-databases-mcp.md)) |
| `globe_note_edit` | change part of a note with anchored edits (below) |
| `tasks_team_list`, `tasks_issue_search`, `tasks_issue_get`, `tasks_issue_list_mine` | Tasks' reads |
| `tasks_issue_create`, `tasks_issue_update`, `tasks_comment_create`, `tasks_issue_claim`, `tasks_issue_progress` | Tasks' writes; `tasks_issue_update` takes `edits` for the description |
| `flags_*` | every Venom Flags tool: list, get, create, update, toggle, rollout, target, evaluate, preview, history, revert, segments, environments, schedules, approvals, insights, stale flags, code references ([Build on Venom Flags](/docs/developers/flags)) |
| `exp_*` | every Venom Experiments tool, product analytics included ([Build on Venom Experiments](/docs/developers/experiments)); appended after the tools above so none of them moves. Closed without `experiments:read`, and its writes need `experiments:write` |
| `people_*` | Venom People: search, read, add, change and merge people, log and list interactions, link two people, events and companies ([People over MCP](/docs/cloud/people-mcp)); appended last. Needs a member's credential (a personal key or OAuth with `people:read`; writes need `people:write`): a team key is refused |
| `chat_*` | Venom Chat: channels, DMs, messages, threads, reactions, search, unread and a change cursor to follow channels ([Build on Venom Chat](/docs/developers/chat)); appended last. Acts as the member (a shared key is an agent member); `chat:read` / `chat:write` for OAuth. |
| `status_*` | The public status page: uptime checks and their results, maintenance windows, subscribers and the services it lists ([Status page](/docs/cloud/status-page)); appended after People. Reads need `org:read`, changes `org:manage` in the member's role (a team key reads only), plus `status:read` / `status:write` on an OAuth grant |
| `comms_*` | Venom Comms: send a message or place a call (held for a person's approval unless the profile allows agents), read messages, calls and conversations, mark a conversation read (WhatsApp read receipts), list senders, profiles and opt-outs, and opt a contact out ([Comms API](/docs/comms/api#mcp)); appended last. `comms:read` / `comms:write` on an OAuth grant |
| `admin_*` | Venom Admin: the console's admin pages as tools, acting with the caller's member role (a personal key or an OAuth grant; a shared key has none): list members and invitations, change a role, remove a member, invite and revoke (never to or from owner), list, create, change and delete spend budgets; provider keys (list, add, rotate, reorder, pause, delete: a key you supply is stored and never shown again), routing and model choice, event webhooks and their deliveries, alerts, the audit log (list, undo, export) and integrations; guardrails, team permissions, gears, daemons, prewarming and GPU grants, handoffs, live and shared sessions, request traces, usage settings, quality checks, shared memory, spend alerts, logging, key rotation policy and single sign-on provisioning and domains; evals and golden tasks, gear experiments and prompt tests, shadow routing, the local autopilot, failures, prompt filters and the secret scanner, issue intake, the library, model lifecycle and credits, starter packs, onboarding paths, the red team run, the failover drill plan, the scorecard, Ask, your own guardrails, API key scope, model access by role, the org spend cap and the session guard. Anything that spends takes its cap (`max_usd`, `daily_cap_usd`) and keeps the console's own limits. Secrets, GPU rental and cut-overs are a person's, never a tool's: signing, SCIM and join tokens, minting or rotating an API key, integration and GPU cloud credentials, creating or scaling a pool, the failover probe, a team's MCP servers, restoring a backup, public share links, the identity provider connection and turning SSO on or requiring it. `admin:read` / `admin:write`, granted by default only on `/workspace/mcp/admin`, never on the combined endpoint unless the app asks; see [Organisation settings](/docs/cloud/console-settings#mcp) |
| `org_team_*` | The organisation's teams ([Teams](/docs/cloud/teams)): one tree of teams and subteams with members (`user:<id>` or `agent:<id>`) and roles (admin, member), shared by every product. `org_team_list`, `org_team_get`, `org_team_members` read; `org_team_create`, `org_team_update`, `org_team_move`, `org_team_archive`, `org_team_member_add`, `org_team_member_role` and `org_team_member_remove` change, with the same rules as Settings → Teams: org owners and admins manage every team, a team's admins their team and its subteams. A personal key or an OAuth grant acts as the member; a shared key bound to a service agent acts as that agent; a bare shared key only reads teams that are not private. `org:read` / `org:write` (in the default grant) |
| `computers_*` | Venom Computers ([Computers for agents](/docs/computers/agents)): each agent's own persistent browser on the org's daemons. `computers_seat_list`, `computers_seat_get`, `computers_activity_list`, `computers_member_list`, `computers_approval_list`, `computers_agent_get` and `computers_run_list` read; `computers_seat_create`, `computers_seat_update`, `computers_seat_delete`, `computers_seat_start`, `computers_seat_stop`, `computers_takeover_request`, `computers_member_add`, `computers_member_remove`, `computers_approval_decide`, `computers_agent_set` and `computers_run_stop` change (agents on computers: [Agents on computers](/docs/computers/agents-on-computers)). A personal key or an OAuth grant acts as the member by their role; a shared key bound to a service agent acts as that agent, which uses its own computer and the shared computers it belongs to; a bare shared key only reads. `computers:read` / `computers:write` (in the default grant) |
| `agents_*` | Venom Agents ([Chats API and MCP tools](/docs/agents/api)): chats with coding agents in a daemon's project and with agents on a computer, run on the org's daemons, and quick chats the cloud runs with MCP tools only ([Quick chats](/docs/agents/quick-chat)). `agents_chat_list`, `agents_chat_get`, `agents_transcript_get`, `agents_change_get`, `agents_project_list`, `agents_gear_list`, `agents_workspace_list` and `agents_server_list` read; `agents_chat_create`, `agents_chat_update`, `agents_chat_archive`, `agents_chat_send`, `agents_chat_stop`, `agents_approval_decide`, `agents_question_respond`, `agents_workspace_create`, `agents_workspace_delete`, `agents_connection_create` and `agents_connection_delete` change. A chat belongs to a person: a personal key or an OAuth grant acts as the member; other keys have no access. `agents:read` / `agents:write` (in the default grant) |
| `studio_*` | Venom Studio ([Studio](/docs/studio/overview)): decks, pages and free-form HTML pages built from blocks, charts and diagrams, versioned and shared by link. `studio_catalog_get`, `studio_component_get`, `studio_layout_get`, `studio_artifact_list`, `studio_artifact_search`, `studio_outline_get`, `studio_artifact_get`, `studio_artifact_validate`, `studio_artifact_export`, `studio_preview_get`, `studio_version_list`, `studio_share_list`, `studio_theme_list`, `studio_marks_get` and `studio_research_get` read; `studio_artifact_create`, `studio_artifact_update`, `studio_content_edit`, `studio_html_edit`, `studio_artifact_duplicate`, `studio_artifact_delete`, `studio_artifact_restore`, `studio_version_restore`, `studio_share_create`, `studio_share_revoke`, `studio_theme_set`, `studio_marks_set` (the org's default header, footer, company, logo, label and numbers: [Marks](/docs/studio/marks)), `studio_research_start` (a server-run researched report: [Research runs](/docs/studio/research)) and `studio_research_cancel` change. A personal key or an OAuth grant acts as the member by their role; a shared key bound to a service agent acts as that agent; a bare shared key only reads what the org shares. `studio:read` / `studio:write` (in the default grant) |
| `calendar_*` | Venom Calendar: list a member's connected accounts and calendars, choose which calendars block time, disconnect an account ([Google accounts](/docs/calendar/google#mcp)); list, add, change and remove your .ics feeds, whose busy time blocks your booking slots ([.ics feeds](/docs/calendar/ics-feeds)); your profile, schedules and event types, free times, single-use and one-off links, and bookings (create, reschedule, cancel, confirm) ([Booking pages](/docs/calendar/booking-pages#agents)); team hosts and group polls ([Teams](/docs/calendar/teams#agents)); appended last. Needs a member's credential (a personal key, or OAuth with `calendar:read`; changes need `calendar:write`): a team key is refused. Connecting a Google account happens in the browser |
| `workspace_item_search` | search notes and issues at once, and projects, people, companies, agent chats and computers by title: `query`, `kinds`, `limit` per app (default 8, at most 25) |
| `workspace_item_get`, `workspace_link_list`, `workspace_item_link`, `workspace_item_unlink` | open any reference or pasted page link as a card, list everything linked to an item, link two items across products, and with `include: ["links"]` get an item and its linked items in one call ([References and links](/docs/cloud/references.md)) |
| `workspace_batch_run` | run up to 25 of the tools above in order, in one round trip |
| `workspace_change_list` | what changed in notes and issues since your cursor (below) |
| `workspace_product_list` | each product: what it is for, tool count, endpoint, scopes, its [tool sets](#finding-tools) and the exact connect command. Read only |
| `workspace_tool_search`, `workspace_tool_get` | find the tool for a task in plain words, then read its schema; on every endpoint, listed on the combined one and with every `?set=` ([Finding tools](#finding-tools)). Read only |
| `workspace_web_search` | the web through [Venom Search](/docs/cloud/search.md), the org's own metasearch (also callable as `search_web`). Off until an owner or admin turns it on in Settings, Search |
| `workspace_license_get` | this self-hosted install's license status: state, plan, expiry, banner, whether the daily check is on. Read only: a person uploads the license in Settings, Billing |
| `workspace_agent_list` | the apps and agents your member has connected (name, product, scope, last used). Read only: revoking access stays in Settings, Connect an agent, so an agent cannot cut off other agents |
| `workspace_draft_list` | everything Venom drafted that waits for your member: Outreach drafts, messages your bots hold, People's morning queue, Support drafts and intro asks, each with the product tools that act on it. Read only, and not in the default listing (call it by name, or use `?products=all`). See [Drafts](/docs/cloud/drafts.md) |

Resources: `globe://note/<id>`, `tasks://issue/ENG-123` and `flags://flag/<project>/<key>`.

### Tool names {#naming}

Every tool is `<product>_<resource>_<verb>`: the product (`globe`, `tasks`, `flags`, `forms`, `incidents`, `exp`, `people`, `funnel`, `support`, `chat`, `status`, `comms`, `calendar`, `admin`, `org`, or `workspace` for
tools that span products), a singular resource, and a verb. The verbs are `list`, `get`, `search`, `create`, `update`,
`delete`, `archive` and `restore`, plus a domain verb where those do not say it (`toggle`, `rollout`, `claim`, `ack`,
`publish`). A sorted list groups by product, then by object. Names match `^[a-zA-Z0-9_-]{1,64}$` and stay under 40 characters,
because clients prefix them (Claude Code shows `mcp__venom-tasks__tasks_issue_create`).

The earlier names still work. A call that uses one runs the tool that replaced it, in `tools/call`, in the steps of
`workspace_batch_run` and `flags_batch_run`, and the REST twin is untouched (its paths and operation ids did not change). They are
not listed, and the first use by each credential writes one deprecation line to the server log. Move your scripts and prompts to the new names:

| Old name | New name |
|---|---|
| `globe_vaults` | `globe_vault_list` |
| `globe_search` | `globe_note_search` |
| `globe_read` | `globe_note_get` |
| `globe_list` | `globe_note_list` |
| `globe_write` | `globe_note_write` |
| `globe_edit` | `globe_note_edit` |
| `globe_suggest` | `globe_suggestion_create` |
| `globe_ask` | `globe_note_ask` |
| `tasks_list_teams` | `tasks_team_list` |
| `tasks_search_issues` | `tasks_issue_search` |
| `tasks_get_issue` | `tasks_issue_get` |
| `tasks_create_issue` | `tasks_issue_create` |
| `tasks_update_issue` | `tasks_issue_update` |
| `tasks_comment` | `tasks_comment_create` |
| `tasks_list_my_issues` | `tasks_issue_list_mine` |
| `tasks_claim_issue` | `tasks_issue_claim` |
| `tasks_report_progress` | `tasks_issue_progress` |
| `flags_list` | `flags_flag_list` |
| `flags_get` | `flags_flag_get` |
| `flags_create` | `flags_flag_create` |
| `flags_patch` | `flags_flag_update` |
| `flags_toggle` | `flags_flag_toggle` |
| `flags_rollout` | `flags_flag_rollout` |
| `flags_target` | `flags_flag_target` |
| `flags_archive` | `flags_flag_archive` |
| `flags_restore` | `flags_flag_restore` |
| `flags_delete` | `flags_flag_delete` |
| `flags_preview` | `flags_flag_preview` |
| `flags_evaluate` | `flags_flag_evaluate` |
| `flags_history` | `flags_flag_history` |
| `flags_revert` | `flags_flag_revert` |
| `flags_stale` | `flags_flag_list_stale` |
| `flags_insights` | `flags_insight_get` |
| `flags_segments_list` | `flags_segment_list` |
| `flags_segments_get` | `flags_segment_get` |
| `flags_segments_create` | `flags_segment_create` |
| `flags_segments_patch` | `flags_segment_update` |
| `flags_segments_delete` | `flags_segment_delete` |
| `flags_environments` | `flags_environment_list` |
| `flags_code_refs` | `flags_coderef_list` |
| `flags_schedule` | `flags_change_schedule` |
| `flags_scheduled_list` | `flags_change_list` |
| `flags_scheduled_cancel` | `flags_change_cancel` |
| `flags_approvals` | `flags_approval_list` |
| `flags_batch` | `flags_batch_run` |
| `forms_list` | `forms_form_list` |
| `forms_get` | `forms_form_get` |
| `forms_create` | `forms_form_create` |
| `forms_patch` | `forms_form_update` |
| `forms_preview` | `forms_form_preview` |
| `forms_publish` | `forms_form_publish` |
| `forms_close` | `forms_form_close` |
| `forms_connect` | `forms_form_connect` |
| `forms_history` | `forms_form_history` |
| `forms_revert` | `forms_form_revert` |
| `forms_responses` | `forms_response_list` |
| `forms_summary` | `forms_response_summary` |
| `errors_list` | `incidents_error_list` |
| `errors_get` | `incidents_error_get` |
| `errors_update` | `incidents_error_update` |
| `errors_alerts_list` | `incidents_alert_list` |
| `errors_alerts_set` | `incidents_alert_set` |
| `incidents_list` | `incidents_incident_list` |
| `incidents_get` | `incidents_incident_get` |
| `incidents_open` | `incidents_incident_open` |
| `incidents_update` | `incidents_incident_update` |
| `incidents_implicate` | `incidents_incident_implicate` |
| `incidents_rollback` | `incidents_incident_rollback` |
| `incidents_postmortem` | `incidents_incident_postmortem` |
| `oncall_who` | `incidents_oncall_who` |
| `oncall_ack` | `incidents_oncall_ack` |
| `oncall_override` | `incidents_oncall_override` |
| `experiments_metrics` | `exp_metric_list` |
| `experiments_metric_create` | `exp_metric_create` |
| `experiments_list` | `exp_experiment_list` |
| `experiments_get` | `exp_experiment_get` |
| `experiments_propose` | `exp_experiment_propose` |
| `experiments_start` | `exp_experiment_start` |
| `experiments_ramp` | `exp_experiment_ramp` |
| `experiments_rollout` | `exp_experiment_rollout` |
| `experiments_results` | `exp_experiment_results` |
| `experiments_decide` | `exp_experiment_decide` |
| `experiments_stop` | `exp_experiment_stop` |
| `analytics_query` | `exp_query_run` |
| `analytics_insight_save` | `exp_insight_save` |
| `analytics_insights` | `exp_insight_list` |
| `workspace_search` | `workspace_item_search` |
| `workspace_changes` | `workspace_change_list` |
| `workspace_batch` | `workspace_batch_run` |

### Anchored edits

`globe_note_edit` (by `id`, or `vault` and `path`) and `tasks_issue_update` (`edits` instead of `description`) change text
without resending it. The operations, the same ones Linear's MCP server and coding agents use:

| `op` | Fields | Effect |
|---|---|---|
| `replace` | `old_string`, `new_string`, `replace_all?` | replace the one match (every match with `replace_all`) |
| `insert_before`, `insert_after` | `anchor`, `text` | insert next to the one match |
| `prepend`, `append` | `text` | add at the start or the end |
| `replace_range` | `from`, `to`, `new_string` | replace from `from` up to `to` (`to` stays) |

Edits apply in order, each against the text as the earlier ones left it. Every anchor must match exactly once, or
nothing changes and the answer says which edit failed and why. A note is written only if its body is still the one
the edits were applied to; if someone saved in between, the edits are checked again against the newer body once. A
note open in the editor takes the change live, and a person's typing elsewhere in it is kept.

```json
{ "id": "0193…", "edits": [
  { "op": "replace", "old_string": "Date: TBD", "new_string": "Date: 2026-12-01" },
  { "op": "insert_after", "anchor": "## Risks\n", "text": "- vendor delay\n" } ] }
```

### Batches

`workspace_batch_run` takes `calls` (1 to 25 `{tool, arguments}`) and `stop_on_error` (default true). Steps run in order;
the answer lists each step's result, marked `ok` or `refused`. A later step can use what an earlier one made or
changed: `$1.id` anywhere in a text argument becomes step 1's note id or issue identifier.

```json
{ "calls": [
  { "tool": "globe_note_write", "arguments": { "vault": "org", "path": "Retros/Nov", "body": "# Retro\n", "mode": "create" } },
  { "tool": "tasks_issue_create", "arguments": { "team": "ENG", "title": "Hold the retro", "description": "Notes: globe://note/$1.id" } },
  { "tool": "tasks_comment_create", "arguments": { "id": "$2.id", "body": "Booked for Friday." } } ] }
```

A batch is not a transaction: with `stop_on_error`, the steps before a refusal stay done and the rest do not run. A
batch cannot hold another batch.

## Safe writes and small reads

These arguments work the same on `/workspace/mcp`, `/globe/mcp` and `/tasks/mcp`.

### Versions

Every read answers a **version**: the time the note or issue last changed. `globe_note_get` shows it as
`version 2026-11-07T10:00:00.123Z`, `tasks_issue_get` as `Version:`, and both carry it as `version` in JSON. Pass it
back as `expect_version` on `globe_note_edit`, `globe_note_write` (append or replace), `tasks_issue_update` or a database write such as `globe_row_update` ([every tool that takes it](/docs/developers/conventions#versions)), and the write is
refused if someone changed the note or issue since you read it:

> ENG-12 changed since you read it (now version …); nothing was written. Read it again and redo your change on what
> it says now.

The issue check runs inside the update's transaction, and a note is written only if its body is still the one you
read, so two writers can't both win. The REST API takes the same check as `expectUpdatedAt` on
`PATCH /tasks/api/issues/{id}` (409 `version_conflict`).

### Idempotency keys

Every create takes an `idempotency_key` (up to 200 printable characters; a UUID is ideal): each `*_create`, `*_send` and
`*_place` tool ([every tool that does](/docs/developers/conventions#idempotency)), plus `globe_note_write`, `globe_suggestion_create` and `tasks_issue_progress`. A create whose own
handler has no key gets one from the server, the same way on `/workspace/mcp`, on a product endpoint, inside a batch, on
the product's own server (`/flags/mcp` and the rest) and on the REST twin (`Idempotency-Key`). The first call with a key runs. A retry with the
same key within 24 hours gets the first answer back, ending with "Replayed", and creates nothing. A call that was
refused frees its key, so you can fix the arguments and retry with the same one. Reusing a key for a different tool
is refused. Keys belong to your credential and your organisation.

### JSON, fields and `since`

Pass `format: "json"` to `globe_note_get`, `globe_note_search`, `globe_note_list`, `tasks_issue_get`, `tasks_issue_search` or
`tasks_issue_list_mine` to get the answer as `structuredContent` (and the same JSON as text, for clients that only
read text). The default stays short markdown. No tool declares an output schema, because MCP then requires
structured results on every call, which would send each answer twice.

- `fields` picks what each JSON row carries (the `id` always comes too): on `globe_note_list` (`path`, `title`,
  `version`, `status`) and on the Tasks lists (`identifier`, `title`, `state`, `stateType`, `priority`, `assignee`,
  `delegate`, `labels`, `estimate`, `dueDate`, `version`).
- `since` (an ISO date or time, such as the newest version you have) on `globe_note_list` and `tasks_issue_search`
  returns only what changed after it, so an agent that checks back re-reads nothing it already has.

```json
{ "name": "tasks_issue_search", "arguments": { "team": "ENG", "since": "2026-11-07T10:00:00.123Z", "format": "json", "fields": ["identifier", "state", "version"] } }
```

## Following changes

### `workspace_change_list`

Call it with no arguments to get a cursor that starts from now, or with `since` (a time) to start earlier. Keep the
cursor it answers and pass it back later: you get only the notes and issues created, changed or deleted in between,
one line each, oldest first, and the next cursor. Several writes to the same note or issue read as one line.

```text
2 changes:
- 2026-11-07T10:02:11Z note Plans/Launch (id 0193…) changed by Claude Code (via MCP, for ana@example.com)
- 2026-11-07T10:02:40Z comment on ENG-12 Ship the launch added
Cursor: g8812.t40417 (pass it back to see what changes next).
```

`limit` (default 50, at most 200) caps the lines; when more are waiting the answer says so. `format: "json"` gives
`{changes: [{app, kind, ref, title, op, at, by, uri}], cursor}`. You see what you can read: your personal notes, the
org's, and the issues your role reads. The logs keep a day; an older cursor starts from the oldest change kept.

### Subscriptions and the stream

To be told as it happens, subscribe to a resource and keep the stream open:

1. `initialize` answers an `Mcp-Session-Id` header. Send it on later requests.
2. `resources/subscribe` with `{"uri": "globe://note/<id>"}` or `{"uri": "tasks://issue/ENG-12"}`. You must be able to
   read it. A session holds at most 200 subscriptions; `resources/unsubscribe` drops one.
3. `GET /workspace/mcp` with `Accept: text/event-stream` and the session id opens the stream. Each change to a
   subscribed note or issue arrives as a `notifications/resources/updated` message with the URI, and you read it with
   `resources/read` or the tools. A `: ping` comment arrives every 25 seconds.
4. The stream ends after about 50 seconds; reconnect with `Last-Event-ID` (the last event's `id`, a cursor) and
   nothing is missed. `DELETE /workspace/mcp` with the session id ends the session and its subscriptions.

MCP clients that support resource subscriptions do all of this on their own.

### Webhooks {#webhooks}

For a script or service that isn't connected over MCP, send the changes to a URL instead. In Venom Cloud's
**Settings → Webhooks** (`/settings/webhooks?events=tasks,globe` opens the form with these events ticked), add an
https endpoint and pick from:

| Event | When |
|---|---|
| `tasks.issue.created` / `tasks.issue.updated` / `tasks.issue.deleted` | an issue was created, changed (state, assignee, delegate, claim, priority, labels, text) or deleted |
| `tasks.comment.created` | a comment or an agent's progress report was added |
| `tasks.issue.delegated` | an issue got a new delegate agent, with the previous one and who delegated it ([for workers](/docs/cloud/tasks-mcp#delegated-webhook)) |
| `globe.note.created` / `globe.note.updated` / `globe.note.deleted` | a note in the org vault was created, changed or trashed |
| `globe.team_note.created` / `globe.team_note.updated` / `globe.team_note.deleted` | a note in a team vault was created, changed or trashed; `data.team_ids` names the teams |

Each delivery is the org webhooks' usual envelope (`{id, type, created_at, org, data, links}`), signed with the
endpoint's secret in `venom-signature`, retried with backoff for about four hours, and listed in the delivery log
with **Retry** and **Send test**. `data` carries ids, identifiers, titles, paths, states and who; never an issue's
description, a comment's text or a note's body. Personal notes never leave through a webhook, nor do Tasks rows only
their owner sees. Team-vault notes are their own event types, so an endpoint that took `globe.note.*` keeps getting the
org vault only; tick `globe.team_note.*` to add team vaults (they are not ticked by default on a new endpoint). Changes to one issue or note within a minute arrive as one event with it as it is now, so live
typing is one `globe.note.updated` a minute. An endpoint starts with what changes after it is added; nothing older
is sent. Nothing is sent until an admin adds an endpoint.

A [private team](/docs/cloud/tasks#teams)'s issues and comments are sent like any other team's. An endpoint is the
org's own integration, added by an owner or admin, and owners and admins see every team. The receiver gets the same
fields (no description, no comment text), and the delivery log shows only each event's type and id. If an endpoint's
receiver should not learn a private team's titles, leave the `tasks.*` events off it.

```json
{ "type": "tasks.issue.updated", "data": { "identifier": "ENG-12", "title": "Ship the launch", "team_key": "ENG", "state": "In Review",
  "state_type": "started", "priority": 2, "assignee_id": "user_…", "delegate_agent_id": "key:…", "claimed": true },
  "links": { "issue": "https://cloud.usevenom.dev/tasks/issue/ENG-12" } }
```

## Agents people can see

- **Presence.** An agent that writes a note through MCP shows on that note, next to the people there, as a rounded
  square with its app's name ("Claude Code (AI agent)"), for as long as it keeps writing. `globe_note_get` tells an agent
  who else is on the note now, people and agents.
- **History.** A note's history names the agent and who it acts for: "Claude Code (via MCP, for ana@example.com)".
  Issues already record the agent and "via MCP" in their activity.
- **Working.** An issue whose agent holds a live claim shows **Working** next to the agent in the issue's properties.

## Agent access {#agent-access}

### Limits per agent

Each agent has its own window of **240 requests a minute**: a personal key's agent, each connected app, each service
agent, and each venom daemon or session that names itself with `x-venom-agent` on a shared key. Two agents on one key
no longer share a limit. The key itself keeps a ceiling of **960 a minute** over all its agents, so naming a new
session per request does not lift the limit. A batch counts one request more for each write step in it. Past either
limit: HTTP 429 with `Retry-After`, the code `rate_limit_exceeded`, and a message that says which limit and how many
seconds to wait (inside a batch, a refusal before any step runs). Every Venom MCP server counts the same way:
`/tasks/mcp`, `/globe/mcp`, `/flags/mcp`, `/forms/mcp`, `/incidents/mcp` and `/experiments/mcp`, each in its own
window. A credential with no agent of its own counts as one agent.

### Scoped service agents

A service agent is a shared key an admin bound to an agent (`POST /tasks/api/agents`). In Venom Tasks → **Settings →
Members and agents → Agent access**, an admin can narrow one: **Read only** (it never creates or changes anything),
**Apps** (Notes, Tasks or both), and **Teams** (all, or some: it reads and writes only those teams' issues, and hears
only about them in `workspace_change_list`). An admin also creates a service agent there (**New agent**: a name and a shared key) and renames one. The same page shows each agent's requests this minute against its limit.
The scope holds on `/workspace/mcp`, `/tasks/mcp` and `/globe/mcp` (a key scoped away from Notes gets 403 there).
Agents that act for a member (a personal key, a connected app) follow that member's role and have no scope of their
own.

| Endpoint | Does |
|---|---|
| `GET /tasks/api/agents` | the agents, each with `scope` `{readOnly, apps, teamIds}` and `requestsThisMinute`, and `limitPerMinute` |
| `POST /tasks/api/agents` | `{keyId, name, guidance?, teamIds?, readOnly?, apps?}`: bind a shared key to a service agent |
| `GET /tasks/api/agents/keys` | the shared keys with no agent yet (for "New agent") |
| `PATCH /tasks/api/agents/{id}` | `{name?, disabled?, readOnly?, apps?, teamIds?}`: rename a service agent, turn it off or on, or change its scope (`null` = all) |

## Limits

- 240 requests a minute per agent and 960 per credential (above).
- A request body is at most 2 MiB; a note at most 200 KB; at most 50 edits per call.
- `workspace_item_search` waits up to 3 seconds for each app and answers with what it has; an app that isn't bought or
  doesn't answer says so under its heading.
- The stream needs `Accept: text/event-stream` (otherwise 406) and the session id from `initialize` (otherwise 400).

## Conformance {#conformance}

Every Venom MCP server speaks MCP 2025-11-25 (and the earlier revisions a client asks for) and is tested against it with
the official MCP SDK client, offline, on every change. What a client can count on, on every endpoint:

- **Tool lists page.** `tools/list` answers `nextCursor` when there is more (every endpoint fits one page of 2,000 today).
  A cursor the server did not hand out is a JSON-RPC error `-32602`.
- **Annotations on every tool**, all four: `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`. A
  read is never marked as a write; a delete is destructive; a create is not idempotent (it takes an idempotency key
  instead); a tool that reaches outside Venom, such as sending an SMS, has `openWorldHint: true`.
- **The scope in the description.** Each product tool's description ends with the OAuth scope it needs, such as
  `OAuth scope: flags:write.`, the same scope the server checks the token against. The scope follows the annotation: a
  read-only tool needs `:read`, any other `:write`. A product's batch runner (`flags_batch_run`) needs `:read` and
  checks each step. An owner's or admin's setting needs `:admin`, and says so: Flags' projects, environments, SDK
  keys and webhooks (`flags:admin`), and Incidents' alert and fingerprint rules, on-call schedules, escalation
  policies, alert sources and loop settings (`incidents:admin`). An app without that scope is refused before the call
  runs, naming the scope.
- **Lists page with `cursor` and `limit`.** A list answers `next_cursor` when there is more (null on the last page);
  pass it back as `cursor`. Every list in every product pages this way (a list read in full: 100 rows a page by
  default, at most 500), and so does its REST route, with `cursor` and `limit` in the query string. Lists that page
  by `before`, `after` or `offset` keep those arguments, and `cursor` works on top of them. Only Computers' three
  lists don't page yet; the conformance suite keeps their names, and that list only shrinks. A cursor the list did not
  give is refused in words. A few answers that were a bare array in JSON are now `{ items, next_cursor }`: Flags'
  lists and the trash, shared, dashboard, automation and template lists of Notes.
- **Schemas that hold.** Every `inputSchema` is valid JSON Schema with its required fields, enums, a minimum and maximum
  on every `limit` and a `maxItems` on every list, and states whether it takes other arguments.
- **Structured answers.** A tool that answers `structuredContent` on every call declares an `outputSchema`
  (`workspace_product_list`, `workspace_agent_list`, `workspace_license_get`). Other tools answer it when you pass
  `format: "json"`, so a client that shows both does not get every answer twice.
- **Two kinds of error.** A broken request is a JSON-RPC error: `-32700` (not JSON), `-32600` (not a request), `-32601`
  (no such method), `-32602` (no such tool, arguments that are not an object, a bad cursor). A call the tool refuses
  (a bad argument, no access, a missing scope, no add-on) is a result with `isError: true` and a sentence that says what
  to do, so the model can fix its call.
- **The REST twin takes what the tool takes.** Every argument a tool takes is a field (or query parameter) of its
  `/api/v1` route, except the ones the path, `Idempotency-Key` or `If-Match` carry.

The suite also checks the parity table (`lib/mcp/parity.ts`): every route or button without a tool says why in
words, and every tool it points an agent to instead exists. The exemptions were reviewed for VEN-349; each one is a
person's act (a secret pasted once, a sign-in, a public page's history), a browser's own state, a machine call, or the
transport itself, and names the tool an agent uses instead where there is one.

## Prompts

The server offers three prompts (`prompts/list`), workflows your client can show you as commands. Claude Code
lists them as `/mcp__venom__<name>`. They are instructions for the tools above and add no access of their own.

| Prompt | Arguments | What the agent does |
|---|---|---|
| `work_my_issues` | `team` (optional) | Lists the issues delegated to it, claims the most urgent, does the work, reports progress and moves it to In Review. Stops after three. |
| `session_note` | `title`, `vault` (`me` or `org`, optional) | Saves this session as a note (summary, decisions, changes, open questions, next steps), or adds to an existing note on the same topic, and links the issues it touched. |
| `triage_inbox` | `team` (optional) | Goes through issues in Triage: finds duplicates, sets priority, labels and estimate, asks for missing details, and ends with a table of decisions. |

## Speed

Each call's time inside the server comes back in a `Server-Timing: route;dur=<ms>` header: authentication, the rate
limit and the work, not the network. The budgets:

| Call | p50 | p95 | Answer size |
|---|---|---|---|
| read (a note or an issue) | 60 ms | 200 ms | 8 KB |
| search (`workspace_item_search`, 10 hits) | 120 ms | 400 ms | 4 KB |
| write (one edit or update) | 90 ms | 300 ms | 1 KB |
| `workspace_batch_run` of 10 writes | 400 ms | 1.2 s | 6 KB |

`make mcp-bench KEY=vck_… [URL=http://localhost:3100] [RUNS=12] [VAULT=me]` measures them against a cloud: a scratch
note (`Bench/mcp-bench.md`) is read, searched for, edited and edited ten times in a batch, `RUNS` times after a
warm-up. It prints p50, p95, max and the largest answer for each kind, and exits 1 when a p95 or an answer is over
its budget. Use a personal API key (one that acts for a member), since a shared key can't write notes. `JSON=1` prints
the figures as JSON.
