---
title: MCP servers
description: 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.
section: developers
order: 3
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/mcp/listing.ts, services/nodejs-cloud/lib/mcp/products.ts, services/nodejs-cloud/lib/mcp/workspace.ts, services/nodejs-cloud/lib/mcp/workspace-tools.ts, services/nodejs-cloud/lib/mcp/rpc.ts, services/nodejs-cloud/app/workspace/mcp]
features: []
---

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 {#endpoints}

| Product | Endpoint | Server name | Tools | Scopes |
|---|---|---|---|---|
| [Notes](/docs/developers/globe) | `/workspace/mcp/globe` | `venom-globe` | 92 | `globe:read` `globe:write` |
| [Tasks](/docs/developers/tasks) | `/workspace/mcp/tasks` | `venom-tasks` | 221 | `tasks:read` `tasks:write` |
| [Flags](/docs/developers/flags) | `/workspace/mcp/flags` | `venom-flags` | 42 | `flags:read` `flags:write` |
| [Forms](/docs/developers/forms) | `/workspace/mcp/forms` | `venom-forms` | 19 | `forms:read` `forms:write` |
| [Incidents](/docs/developers/incidents) | `/workspace/mcp/incidents` | `venom-incidents` | 56 | `incidents:read` `incidents:write` `incidents:admin` |
| [Experiments](/docs/developers/experiments) | `/workspace/mcp/exp` | `venom-experiments` | 25 | `experiments:read` `experiments:write` |
| [People](/docs/developers/people) | `/workspace/mcp/people` | `venom-people` | 135 | `people:read` `people:write` |
| [Funnel](/docs/developers/funnel) | `/workspace/mcp/funnel` | `venom-funnel` | 38 | `funnel:read` `funnel:write` |
| [Support](/docs/developers/support) | `/workspace/mcp/support` | `venom-support` | 26 | `support:read` `support:write` |
| [Chat](/docs/developers/chat) | `/workspace/mcp/chat` | `venom-chat` | 32 | `chat:read` `chat:write` |
| [Status page](/docs/developers/status) | `/workspace/mcp/status` | `venom-status` | 16 | `status:read` `status:write` |
| [Comms](/docs/developers/comms) | `/workspace/mcp/comms` | `venom-comms` | 27 | `comms:read` `comms:write` |
| [Calendar](/docs/developers/calendar) | `/workspace/mcp/calendar` | `venom-calendar` | 41 | `calendar:read` `calendar:write` |
| [Admin](/docs/developers/admin) | `/workspace/mcp/admin` | `venom-admin` | 269 | `admin:read` `admin:write` |
| [Org](/docs/developers/org) | `/workspace/mcp/org` | `venom-org` | 10 | `org:read` `org:write` |
| [Computers](/docs/developers/computers) | `/workspace/mcp/computers` | `venom-computers` | 36 | `computers:read` `computers:write` |
| [Agents](/docs/developers/agents) | `/workspace/mcp/agents` | `venom-agents` | 48 | `agents:read` `agents:write` |
| [Studio](/docs/developers/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 {#combined}

`/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](/docs/cloud/workspace-mcp#listing)); 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 {#connect}

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

```bash
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:

```bash
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:

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

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](/docs/developers/auth.md#oauth).

## A raw call {#raw}

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:

```bash
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 {#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](/docs/cloud/workspace-mcp.md#naming)
lists them.

## More {#more}

[Venom for agents](/docs/cloud/workspace-mcp.md) 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.
