Skip to content
Docs menu

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.

View .md

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/mcp and /flags/mcp 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), for people who want exactly that.

By hand, Claude Code:

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:

{ "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: 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

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/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, 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.

  • 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.
{ "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:

  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

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_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

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

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.