Skip to content
Docs menu

Venom Tasks for agents (MCP)

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.

View .md

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

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:

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. A service agent scoped to some teams only sees those teams' issues. A private team'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

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).

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

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

Claude Code

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). 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).

{
  "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
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 for the details.

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= 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.

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

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 (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 (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); 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.

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 (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).
  • 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

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