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.
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_updatesetsdelegate(an agent) andassignee(a person) apart. - Claim.
tasks_issue_claimdelegates 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_progressrenews 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}/leasegives 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 agentClaude 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=offleaves it out of sessions. Thevenom taskscommands below still work.- An MCP server of your own called
taskstakes 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.
Searching issues like a saved view
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, asGET /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 asfilter.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 withmanual), as Display > Reverse ordering does;closed_last: completed and canceled issues last, the most recently closed first.tasks_issue_exporttakes the same asreverseandclosedLast.label(every one of these label names),project(a name or id),cycle(current,next,previous, an id, or withteama cycle number),priority(a list, 0 to 4) andinclude_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
429withretry-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:
GETandDELETEanswer405, so clients use plain POST. - A
401carrieswww-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}/noteslists them (globe: falsewhen 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 atTasks/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-2resolves 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;GETshows 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_usdin 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}/suggestionslists the chips;POSTfinds suggestions now;POST /tasks/api/suggestions/{id} {action: "accept" | "dismiss"}decides one. The cronGET /api/cron/tasks-triageruns 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 |