Skip to content
Docs menu

MCP servers

Connect an agent to Venom over MCP. One connection at /workspace/mcp whose listed products you switch on, or one server per product at /workspace/mcp/<product>, the connect commands for common clients, and how a raw JSON-RPC call looks.

View .md

Connect once to /workspace/mcp and switch on the products whose tools you want listed, or connect a product's own server. Either way an agent loads only the tools it needs. All endpoints share one authorization server, one rate limit and one change feed, so one sign-in covers every product.

Endpoints

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
Cross-product /workspace/mcp venom 16 listed (every tool callable by name) every product's :read and :write

1179 tools in all. Generated from the code on every docs build.

  • The transport is Streamable HTTP: JSON-RPC over POST, and an event stream on GET for resources you subscribe to. The server speaks MCP protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
  • A self-hosted Venom Cloud serves the same paths on its own origin.
  • experiments works in place of exp in a path.

The combined endpoint

/workspace/mcp lists the cross-product tools (workspace_*): search across notes and issues, a batch that runs many tool calls in one round trip, the change feed, the product list, the connected agents and the license. Over an OAuth connection it also lists the core set of each product its person switched on, on the console's Connect page or with workspace_listing_set (switching products on); that connection's initialize declares tools.listChanged and its stream sends notifications/tools/list_changed when the switches change. A product's tool runs there when called by name whether it is listed or not, alone or in a batch, so older scripts keep working; the scopes alone decide what may be called. ?products=all (or ?products=tasks,globe) lists those tools too; an unknown product is a 400 naming the real ones.

16 tools: 12 read, 4 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.

Tool Title Access Scope REST route
workspace_agent_list List connected agents read each product's GET /api/v1/agents
workspace_batch_run Run several tools in one call write (destructive) each product's POST /api/v1/batch
workspace_change_list What changed read each product's GET /api/v1/changes
workspace_draft_list List drafts waiting for the member read each product's GET /api/v1/drafts
workspace_item_get Open items by reference read each product's GET /api/v1/items
workspace_item_link Link two items write each product's POST /api/v1/items/links
workspace_item_search Search every kind of item read each product's GET /api/v1/search
workspace_item_unlink Remove a link between two items write (destructive) each product's DELETE /api/v1/items/links
workspace_license_get Read the license status read each product's GET /api/v1/license
workspace_link_list Everything linked to an item read each product's GET /api/v1/items/links
workspace_listing_get Read a connection's listing read each product's GET /api/v1/listing
workspace_listing_set Switch products on for this connection write each product's PUT /api/v1/listing
workspace_product_list List Venom's products read each product's GET /api/v1/products
workspace_tool_get Read tools' schemas read each product's GET /api/v1/tools
workspace_tool_search Find the tool for a task read each product's GET /api/v1/tools/search
workspace_web_search Search the web (Venom Search) read each product's POST /api/v1/web/search

On a product endpoint, workspace_batch_run is listed and held to that product's tools; a tool of another product is unknown there.

Connect a client

Claude Code, signing in through the browser, one connection for every product:

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

Then run /mcp to sign in, and switch on the products to list on the console's Connect page (/connect). For a connector limited to one product, connect its own endpoint instead:

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

Then run /mcp to sign in to each. With a personal API key instead, add --header "Authorization: Bearer vck_…".

Cursor, VS Code and other clients that read 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_…" } }
} }

ChatGPT, Claude and other apps that connect by URL take the endpoint and run the OAuth sign-in. The console's Connect an agent page (/connect) writes these lines for you. See Authentication and scopes.

A raw call

Your own agent can call a tool without an MCP library. tools/list lists the endpoint's tools with their input schemas and annotations (readOnlyHint, destructiveHint); tools/call runs one:

curl -X POST "$VENOM_CLOUD/workspace/mcp/globe" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "globe_note_search", "arguments": {"query": "launch plan", "limit": 5}}}'

A refusal is a normal result with isError: true and the reason as text. Every caller gets the same tool list in the same order, so a client's cached tool definitions stay valid; a call the credential may not make is refused in words.

Naming

A tool is <product>_<resource>_<verb>, for example tasks_issue_create. The verbs are list, get, search, create, update, delete, archive and restore, plus a domain verb where those do not fit (claim, toggle, publish). Names stay under 40 characters because clients prefix them (Claude Code shows mcp__venom-tasks__tasks_issue_create). Older names still run; Venom for agents lists them.

More

Venom for agents covers the rest of the MCP server in depth: anchored edits, batches and $1.id references, versions and idempotency keys, the change feed, resource subscriptions, presence, service agents, prompts and speed budgets.