Venom for agents (one MCP server for notes, tasks and flags)
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.
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,/tasks/mcpand/flags/mcpanswer as before (the Notes one gainsglobe_note_edittoo). Use/workspace/mcpfor 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.
- 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.
- Your connections. Every app you connected, when it was last used, and Disconnect, which stops its tokens at
once. A connection to
/workspace/mcpalso shows a switch per product, with the number of tools each adds, and the connection's total. - Advanced. A connector limited to one product (
/workspace/mcp/<product>, below), for people who want exactly that.
By hand, Claude Code:
claude mcp add --transport http venom https://cloud.usevenom.dev/workspace/mcpthen /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:
{ "mcpServers": { "venom": { "url": "https://cloud.usevenom.dev/workspace/mcp" } } }Switching products on
Each product you switch on for a connection adds its core set of tools (tool sets; 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.
- 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:
initializeon/workspace/mcpover an OAuth connection declarestools.listChanged. When you change the switches, the connection's notification stream (GET /workspace/mcpwith itsMcp-Session-Id) sendsnotifications/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_getreads a connection's switches and counts (this one by default, or another of your own by id fromworkspace_agent_list).workspace_listing_setchanges them, for the connection the agent is calling through only (productsreplaces the list;addandremoveedit 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_searchfinds them. REST:GET /api/v1/listingandPUT /api/v1/listingwith a token issued for/workspace/mcp. Each change is audited asworkspace.listing_set.
One server per product
There are over a thousand tools in all (the MCP servers page has the current count), and listing
them costs context in every session. Besides the one connection above, 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:
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/tasksthen 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, the 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) 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:
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:
{ "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
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.
{ "query": "move issue to cycle" }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.
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). 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 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 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) |
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) |
exp_* |
every Venom Experiments tool, product analytics included (Build on Venom 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); 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); 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); 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); 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 |
org_team_* |
The organisation's teams (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): 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). 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): 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). 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): 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), studio_research_start (a server-run researched report: Research runs) 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); list, add, change and remove your .ics feeds, whose busy time blocks your booking slots (.ics feeds); your profile, schedules and event types, free times, single-use and one-off links, and bookings (create, reschedule, cancel, confirm) (Booking pages); team hosts and group polls (Teams); 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) |
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 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). Read only |
workspace_web_search |
the web through Venom Search, 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 |
Resources: globe://note/<id>, tasks://issue/ENG-123 and flags://flag/<project>/<key>.
Tool names
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.
{ "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.
{ "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), 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), 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.
fieldspicks what each JSON row carries (theidalways comes too): onglobe_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) onglobe_note_listandtasks_issue_searchreturns only what changed after it, so an agent that checks back re-reads nothing it already has.
{ "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.
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:
initializeanswers anMcp-Session-Idheader. Send it on later requests.resources/subscribewith{"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/unsubscribedrops one.GET /workspace/mcpwithAccept: text/event-streamand the session id opens the stream. Each change to a subscribed note or issue arrives as anotifications/resources/updatedmessage with the URI, and you read it withresources/reador the tools. A: pingcomment arrives every 25 seconds.- The stream ends after about 50 seconds; reconnect with
Last-Event-ID(the last event'sid, a cursor) and nothing is missed.DELETE /workspace/mcpwith the session id ends the session and its subscriptions.
MCP clients that support resource subscriptions do all of this on their own.
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) |
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'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.
{ "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_gettells 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
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_searchwaits 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 frominitialize(otherwise 400).
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/listanswersnextCursorwhen 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,idempotentHintandopenWorldHint. 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, hasopenWorldHint: 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:readand 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
cursorandlimit. A list answersnext_cursorwhen there is more (null on the last page); pass it back ascursor. 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, withcursorandlimitin the query string. Lists that page bybefore,afteroroffsetkeep those arguments, andcursorworks 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
inputSchemais valid JSON Schema with its required fields, enums, a minimum and maximum on everylimitand amaxItemson every list, and states whether it takes other arguments. - Structured answers. A tool that answers
structuredContenton every call declares anoutputSchema(workspace_product_list,workspace_agent_list,workspace_license_get). Other tools answer it when you passformat: "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 withisError: trueand 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/v1route, except the ones the path,Idempotency-KeyorIf-Matchcarry.
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.