---
title: Venom Tasks for agents (MCP)
description: Connect Claude Code, venom, Qoder or any MCP client to Venom Tasks, delegate issues to agents, link issues and notes, and let AI triage suggest a team, labels, a priority and duplicates.
section: cloud
order: 246
audience: [user, operator, agent]
sources: [services/nodejs-cloud/app/tasks/mcp/route.ts, services/nodejs-cloud/lib/tasks/mcp, services/nodejs-cloud/lib/tasks/agents.ts, services/nodejs-cloud/lib/tasks/assigned.ts, services/nodejs-cloud/app/tasks/mcp/assigned, services/nodejs-cloud/lib/tasks/globe-link.ts, services/nodejs-cloud/lib/tasks/triage, services/nodejs-cloud/lib/oauth, services/nodejs-cloud/migrations/0126_tasks_mcp.sql, services/nodejs-cloud/migrations/0127_tasks_triage_ai.sql, cli/src/tasks-command.ts, docs/tasks.md]
features: [cloud.tasks, automation.task, cloud.well-known]
---

Venom Tasks is your organisation's issue tracker. Agents are first-class in it: an issue keeps a person as its
**assignee**, the one who owns it, and can be **delegated** to an agent that does the work. Any agent that speaks the
Model Context Protocol can find issues, claim one, report progress and move it along, and everything it writes is
marked "via MCP" with the agent's name.

- **Endpoint:** `https://cloud.usevenom.dev/tasks/mcp`. It uses Streamable HTTP, is stateless, and takes JSON-RPC
  over POST. 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.
- **Add-on:** Tasks is an add-on. If your organisation hasn't added it, the handshake still works and every tool
  answers with a short message saying where to add it.

## Who the agent is

Every credential becomes an agent with an id. That id is what an issue is delegated to and what its comments and
changes record.

| Credential | Agent | What it may do |
|---|---|---|
| Personal key ("This key is mine" in Settings → API keys) | `key:<key id>`, a **personal** agent acting for you | what your role allows |
| OAuth app you connected | `mcp:<client id>:<you>`, a personal agent | what your role allows, within the scopes you granted |
| Team key bound to a **service** agent | `key:<key id>`, the service agent's name | read and write, in the teams the admin picked, following the agent's guidance |
| Team key with no service agent | none | read only |
| A venom session or daemon, with `x-venom-agent` | `daemon:<id>` or `session:<id>`, a **venom** agent | what the key allows |

Your role sets the ceiling: owners and admins get `tasks:read`, `tasks:write` and `tasks:admin`; developers get read and
write; billing and viewer members read only. An OAuth grant narrows that further, never widens it. A read-only caller
sees only the read tools. A private team's issues are the team's members' (and `tasks:admin` callers'): for anyone
else the tools answer as if the issue did not exist, and searches and team lists leave the team out.

An admin binds a team key to a service agent with `POST /tasks/api/agents {keyId, name, guidance?, teamIds?}`, renames
one and turns an agent off or on with `PATCH /tasks/api/agents/{id} {name?, disabled?}` (all `tasks:admin`).
`GET /tasks/api/agents/keys` lists the team keys that have no agent yet. In **Settings → Members and agents → Agent
access**, **New agent** does the same from a name and a key, and **Rename** changes a service agent's name (the others
are named by what connects). A turned-off agent's requests
are refused. `GET /tasks/api/agents` lists everyone work can be delegated to, the org's daemons included: it feeds the
delegate picker on an issue.

## Delegation and claims

- **Delegate, not assignee.** Delegating never changes who owns the issue. `tasks_issue_update` sets `delegate` (an
  agent) and `assignee` (a person) apart.
- **Claim.** `tasks_issue_claim` delegates the issue to the calling agent and moves it to the team's first started
  state. The claim is a **30-minute lease**. While it is live, another agent's claim is refused and names the holder.
- **Renew.** Each `tasks_issue_progress` renews the lease. When a lease runs out, the claim is cleared (the sweep cron
  does it) but the delegate stays, so the issue still shows who was on it. `GET /tasks/api/issues/{id}/lease` gives the
  live claim for the issue page's "working" pulse. The issue's assignee (its creator when nobody is assigned) gets a
  **claim expired** item in the Inbox: "Claude Code stopped working on ENG-12: its claim expired".
- **Guidance.** A service agent's guidance (up to 32 KB) is shown to it at the end of `tasks_issue_get`.

## Push: issues delegated to you {#push}

`GET /tasks/mcp/assigned` is a server-sent event stream for one agent, with the same credentials as `/tasks/mcp`
(a Venom API key or a connected app; it needs an agent, so a team key with no bound service agent gets 403). It sends
an `assigned` event for each open issue delegated to the agent that has no live claim:

```text
id: 4121
event: assigned
data: {"seq":4121,"issueId":"…","identifier":"ENG-42","title":"…","teamId":"…","stateType":"unstarted","priority":1}
```

On connect it first sends what is already delegated (so a worker that was down misses nothing), then each new
delegation as it happens. Reconnect with `Last-Event-ID` (or `?after=`) to skip the replay. The stream pings every 25
seconds and closes after about 4.5 minutes; reconnect. After an event, claim the issue with `tasks_issue_claim`. A
GitHub label can start this: see [GitHub issues as intents](/docs/cloud/tasks-github#intents). A service agent scoped
to some teams only sees those teams' issues. A [private team](/docs/cloud/tasks#teams)'s issue is sent only when the
credential may see the team (the key's member is in it, or the key has `tasks:admin`). Each connection counts as one
request in the agent's rate limit.

### Without a held-open connection {#delegated-webhook}

A worker that cannot keep a stream open (a serverless function, a queue consumer) can be told by a webhook instead.
An org admin adds an endpoint in **Settings → Webhooks** that takes `tasks.issue.delegated`. It is sent each time an
issue gets a new delegate agent, at creation or later, with the issue's id, identifier, title and team, the
`delegate_agent_id`, the `previous_delegate_agent_id` and who delegated it (`by`); never the description. Taking the
delegate away, or an agent claiming an issue for itself, sends nothing. The receiver filters on `delegate_agent_id`
for its own agent, then claims the issue with `tasks_issue_claim` as above. Deliveries are signed and retried like
every org webhook ([Webhooks and events](/docs/developers/webhooks)).

```json
{ "type": "tasks.issue.delegated", "data": { "issue_id": "…", "identifier": "ENG-42", "title": "Fix the build", "team_key": "ENG",
  "delegate_agent_id": "key:…", "previous_delegate_agent_id": null, "by": { "kind": "member", "id": "user_…", "agent_id": null, "via": "app" } },
  "links": { "issue": "https://cloud.usevenom.dev/tasks/issue/ENG-42" } }
```

## Connect

Keep the key out of files you commit. The examples read it from an environment variable:

```bash
export VENOM_TASKS_KEY=vck_…   # a personal key, or a team key bound to a service agent
```

### Claude Code

```bash
claude mcp add --transport http tasks https://cloud.usevenom.dev/tasks/mcp \
  --header "Authorization: Bearer $VENOM_TASKS_KEY"
```

Add `--scope user` to have it in every project. `claude mcp list` should show `tasks` as connected.

### venom

Nothing to set up. After `venom cloud login`, every venom session registers the `tasks` server
(`/workspace/mcp/tasks`) with that login's key, next to `globe` and every other Venom product
([What agents connect to by default](/docs/cloud/agent-defaults)). Its tools are deferred like any MCP server's: the
agent finds them with `tool_search` when it needs them, so they don't add to every request's tool list.

- `VENOM_TASKS_MCP=off` leaves it out of sessions. The `venom tasks` commands below still work.
- An MCP server of your own called `tasks` takes its place.
- If your organisation's policy has an MCP allowlist without `tasks`, it is left out.

From the terminal, the same tools as commands:

| Command | What it does |
|---|---|
| `venom tasks list [--all] [--json]` | the issues delegated to this login's agent and assigned to you; `--all` includes done and canceled ones |
| `venom tasks show <ID> [--json]` | one issue (`ENG-123`): fields, description, recent comments |
| `venom tasks claim <ID>` | delegate it to this agent and move it to started; the assignee stays |
| `venom tasks comment <ID> <text…>` | a comment on the issue |
| `venom tasks comment <ID> <text…> --progress [--state <s>]` | a progress report, which renews the claim; `--state` also moves the issue |

Each command is one call to `<cloud>/tasks/mcp`, and nothing is contacted without a login.

### Qoder, Cursor and other clients (mcpServers JSON)

In Qoder, add a server in its MCP settings and paste the entry below. Cursor reads `~/.cursor/mcp.json` (or
`.cursor/mcp.json` in a project).

```json
{
  "mcpServers": {
    "tasks": {
      "type": "http",
      "url": "https://cloud.usevenom.dev/tasks/mcp",
      "headers": { "Authorization": "Bearer ${VENOM_TASKS_KEY}" }
    }
  }
}
```

If your client does not expand `${VENOM_TASKS_KEY}`, paste the key itself, and keep that file out of version control.

### Apps that sign in with OAuth

Give the app the endpoint URL and nothing else. It registers itself and opens Venom Cloud's consent page, which names
the app, your organisation, Venom Tasks and what the app asked for. **Allow** connects it as you.

| Scope | What it may do |
|---|---|
| `tasks:read` | search and read issues |
| `tasks:write` | create, change, comment, claim and report progress |
| `tasks:admin` | (reserved for agent and team settings) |

Tasks and Notes share one authorization server, but each is its own protected resource:
`/.well-known/oauth-protected-resource/tasks/mcp` names `<origin>/tasks/mcp`, and a token issued for Notes is refused
here (and the other way round). Connecting an app to both makes two grants. Each is listed in **Settings → Connected
apps** with its product, and **Disconnect** ends it at once.

## Tools

| Tool | Arguments | What it does |
|---|---|---|
| `tasks_team_list` | none | the teams you can see: key (`ENG`), name, parent and path for a subteam, workflow states |
| `tasks_issue_search` | `query?`, `team?`, `subteams?`, `state?`, `assignee?`, `sla?`, `label?`, `project?`, `cycle?`, `priority?`, `filter?`, `view?`, `order_by?`, `descending?`, `closed_last?`, `include_archived?`, `since?`, `limit?`, `cursor?` | issues by text and filters, one line each with state, priority, assignee and delegate; `team` covers its subteams unless `subteams` is false. Search before you create. [The list's own query](#issue-search) |
| `tasks_issue_get` | `id`, `offset?`, `max_chars?` | one issue: fields, description (in pages), sub-issues, relations, linked notes, newest comments, and the agent's guidance |
| `tasks_issue_list_mine` | `include_done?`, `limit?` | the issues delegated to you (the calling agent) or assigned to the member you act for |
| `tasks_issue_create` | `team`, `title`, `description?`, `state?`, `priority?`, `labels?`, `assignee?`, `delegate?`, `project?`, `cycle?`, `parent?`, `triage?` | a new issue; `triage: true` puts it in the team's Triage for a person to review |
| `tasks_issue_update` | `id` and what changes: `title`, `description`, `state`, `priority`, `assignee`, `delegate`, `labels` or `add_labels`/`remove_labels`, `estimate`, `project`, `cycle`, `snooze_until` (an ISO time ahead, or `null`: hides a triage issue until then); `expect_text_version` (the text version `tasks_issue_get` showed: a title or description change is refused if someone changed the text since, and the refusal carries the text now; REST twin: `409 stale`) | changes only what you pass; `edits` always apply to the text as it is now |
| `tasks_comment_create` | `id`, `body`, `reply_to?` | a comment |
| `tasks_issue_claim` | `id` | delegate it to you and move it to started (the lease above) |
| `tasks_issue_progress` | `id`, `body`, `state?` | a progress comment that renews your claim, optionally moving the issue |

States go by name ("In Review") or type (`backlog`, `unstarted`, `started`, `completed` or "done", `canceled`,
`triage`). Each issue is also a resource, `tasks://issue/ENG-123`, for clients that read resources.

Descriptions and comments are markdown. To fold a long log or prompt away, write a collapsible section: a line
`> [!toggle]- Summary` with the content quoted under it (`> line`), or `<details><summary>Summary</summary>…</details>`.
People see it closed with the summary showing; `tasks_issue_get` returns the text as written. See
[the API](/docs/cloud/tasks-api.md#issues) for the details.

### Searching issues like a saved view {#issue-search}

`tasks_issue_search` asks the same query the app's issue lists do, so an agent can ask anything a saved view can, and
gets the issues the list shows in the order it shows them:

- `filter`: the list's filter tree, as [`GET /tasks/api/issues?filter=`](/docs/cloud/tasks-api.md) takes it: a condition
  `{"field", "op", "value"}` or a group `{"and": [...]}` / `{"or": [...]}`, at most 4 deep and 50 conditions. A tree the
  list would refuse is refused with the part that failed, such as `filter.and[1].or[0]: priority is 0–4.`
- `view`: a saved view by id or name: its filter and its order.
- `order_by`: any order the list takes (`manual`, `priority`, `updated`, `created`, `dueDate`, `identifier`, `estimate`,
  `title`, `requests`, `customers`, `revenue`, `state`, `assignee`, `delegate`, `started`, `completed`, `timeInStatus`,
  `links`). Without it (and without a view) the newest activity comes first, as before.
- `descending`: the order the other way round, ties included (not with `manual`), as Display > Reverse ordering does; `closed_last`: completed and canceled issues last, the most recently closed first. `tasks_issue_export` takes the same as `reverse` and `closedLast`.
- `label` (every one of these label names), `project` (a name or id), `cycle` (`current`, `next`, `previous`, an id, or
  with `team` a cycle number), `priority` (a list, 0 to 4) and `include_archived`.

The other arguments are shorthands ANDed with `filter`. Sub-teams and private teams follow the list's rules: a team
condition covers its sub-teams unless `subteams` is false, and a private team's issues appear only to its members.

```json
{ "filter": { "and": [
    { "field": "stateType", "op": "in", "value": ["started"] },
    { "or": [ { "field": "priority", "op": "in", "value": [1, 2] }, { "field": "dueDate", "op": "lt", "value": "+7d" } ] }
  ] },
  "order_by": "timeInStatus" }
```

On the REST twin, `GET /api/v1/issues` takes the same arguments, `filter` as JSON in the query string.

## Everything else the app does {#more}

Beyond the nine issue tools above, every other action of Venom Tasks has a tool: labels and label groups, workflow states (`tasks_state_*`), teams and their members, issue templates, recurring issues, triage rules (`tasks_triagerule_*`, with `tasks_triagerule_test` for a dry run), AI triage settings, cycles, projects with milestones, status updates, links and documents, initiatives, [Pulse](/docs/cloud/tasks-pulse.md) (`tasks_pulse_get`, follows, weekly digests), saved views, favourites, notifications, agents, and on an issue its history (`tasks_issue_history`, `tasks_issue_revert`), subscriptions, relations, comments (`tasks_comment_list`, `_update`, `_delete`), reactions, attachments (`tasks_attachment_create` takes a small file as base64), links, linked notes, pull requests and [customer requests](/docs/cloud/tasks-customer-requests.md) (`tasks_request_*`, `tasks_projectrequest_*`, `tasks_customer_search`). `tasks_issue_batch` changes up to 50 issues in one call (all or nothing). `tasks_issue_move` moves issues filed in the wrong team to another one (`ids`, `teamId`, `subIssues`, `dryRun`): each gets the new team's next number, the old identifier keeps resolving, and the answer lists what was mapped or cleared ([Move to another team](/docs/cloud/tasks.md#move-to-team)); `tasks_project_move` does the same for a project and, with `moveIssues`, its issues, 100 per call while `remaining` is above 0. The full list, and what is left to a person on purpose, is on [what agents can do](/docs/cloud/agents-capabilities.md).

Each of these runs the app's own handler as the agent, so the same checks apply: a read-only credential does not see the write tools, `tasks:admin` is needed for team and workflow settings, secrets are refused, and every change is recorded as made via MCP with the agent's name. Arguments are the fields of the [REST API](/docs/cloud/tasks-api.md) (camelCase); a service agent limited to some teams may use the issue tools but not these. The same tools are on the REST twin under `/api/v1/tasks/...` (`/api/v1/openapi.json`). The import wizard and the GitHub connection's token and secret stay in the console.

## Limits and safety

- **Rate limit:** 240 requests a minute per agent and 960 per credential over all its agents, then `429` with
  `retry-after` (see [Agent access](/docs/cloud/workspace-mcp#agent-access)).
- **Request size:** 1 MiB per request; a comment is at most 64 KB.
- **Secrets:** a write that contains a credential (an API key, a token, a private key) is refused before anything is
  stored.
- **Audit:** every write is recorded in the organisation's audit log (`tasks.mcp.*`) under the credential and agent,
  with ids, never the text.
- **No sessions:** `GET` and `DELETE` answer `405`, so clients use plain POST.
- **A `401`** carries `www-authenticate: Bearer realm="venom-tasks", resource_metadata=…`, which is how OAuth clients
  find the sign-in.

## Issues and notes {#issues-and-globe-notes}

With Venom Notes too, `[[ENG-123]]` in a note shows as a chip with the issue's state and title, old identifiers
included (after a move between teams). The issue lists the notes that link it, each only to members who may read it:
an org vault note to everyone, a personal note to its owner. From the issue:

- `GET /tasks/api/issues/{id}/notes` lists them (`globe: false` when the org has no Notes; nothing breaks).
- `POST /tasks/api/issues/{id}/notes {noteId}` links an existing note; `{create: true, vault?: "me" | "org"}` makes
  **a note in Notes** at `Tasks/ENG-123 <title>` that links back.
- `DELETE /tasks/api/issues/{id}/notes?noteId=…` removes a link made from the issue (a note's own `[[link]]` stays).
- `GET /tasks/api/refs?ids=ENG-1,ENG-2` resolves chips for Notes (up to 200).

## AI triage

AI triage suggests, for an issue in Triage: a team, labels, a priority, an assignee, and possible duplicates found by
text and by meaning. Suggestions are chips on the issue, each with a reason: **accept** applies it as you, **dismiss**
records it. Nothing changes on its own unless the team turned on auto-triage, and then only labels and a priority the
model is confident about (score 0.75 or more); a duplicate or a team move always waits for a person.

- It is **off by default** for each team, because it spends your organisation's own model budget.
  `PUT /tasks/api/teams/{id}/ai-triage {enabled}` (`tasks:admin`) turns it on; `GET` shows the switch, the daily cap
  and today's spend.
- Calls go through your organisation's gateway like any request, with the summary model of its default gear, and are
  capped at **$1 a day** per organisation by default (`tasks_triage_daily_cap_usd` in the org's settings, up to 100).
  At the cap, triage waits until the next UTC day and the issue stays untriaged.
- Without a model, it still suggests duplicates from the search.
- The issue's text is sent as data: instructions inside it are ignored, and only teams, labels, people and issues it
  was offered can come back.
- `GET /tasks/api/issues/{id}/suggestions` lists the chips; `POST` finds suggestions now; `POST
  /tasks/api/suggestions/{id} {action: "accept" | "dismiss"}` decides one. The cron `GET /api/cron/tasks-triage` runs
  every five minutes over new issues in Triage.

## Troubleshooting

| You see | Why | Fix |
|---|---|---|
| `401` with `resource_metadata=…/tasks/mcp` | no key, a wrong or revoked one, or a Notes OAuth token | check the `Authorization` header; connect the app to Tasks itself |
| "Venom Tasks is an add-on…" | the organisation hasn't added Tasks | an owner or billing admin adds it (Settings → Billing) |
| only four tools listed | a read-only credential: a team key with no service agent, a viewer role, or `tasks:read` only | use a personal key, bind the team key to a service agent, or grant `tasks:write` |
| "claimed by … until …" | another agent holds a live lease | wait for it to run out, or ask its owner |
| `403` naming `x-venom-agent` | the header names a daemon that isn't your organisation's | send your own daemon's id, or leave the header out |
| `429` | more than 240 requests in a minute from this agent, or 960 on this credential | wait for `retry-after` seconds |
