Developers

Claude and MCP

Claude works in VentionDesk like a team member: it pulls tasks, implements them and reports back — with exactly the rights of the key you give it. VentionDesk does not run a model of its own for this and charges nothing: you bring your own Claude (Claude Code with your Claude subscription or Anthropic key).

Two ways lead there: the MCP server — recommended for Claude Code — and the API directly, for example from your own scripts. It also works without a key: every person connects Claude, ChatGPT, Cursor or Codex with their own sign-in — see Connect AI apps.

1. Create an agent key

Settings › API keys › “New key”, kind “Agent”:

Permissions: for working on tasks projects:read, tasks:read and tasks:write; notes:write if Claude should create notes; agent:run if runs should be logged. You only switch on tickets, replies to customers, invoice and quote drafts, errors, times, key figures, roadmap and ideas if you explicitly want to (see below).
Projects: all, or only those Claude should work on.
Expires: suggestion 365 days.

The key (vd_live_…) appears exactly once. Directly below it is the “Connect Claude” card with the ready-made command including the key.

Tickets, replies, finances and reports — your decision

By default an agent key sees no tickets, no errors, no times and no key figures, writes to no customer and touches neither invoice nor quote, roadmap or ideas. You switch on each of these scopes per key yourself — when creating it or later under “Permissions” in the key list. For each one, the form says what the key may then do.

Scope	What the key may then do
`tickets:read`	Read the tickets of its projects, including history, names, email addresses and screenshots. What it reads goes to the AI service you enter the key into — for that you need a data processing agreement with its provider (Art. 28 GDPR).
`tickets:write`	Create tickets, write internal notes and reply drafts. Nothing of this reaches the customer.
`tickets:reply`	Reply to customers by email — immediately, without a person reading the reply. The same way as “Send reply”: your sender, your footer, the email thread. Every reply always carries the notice that an AI assistant wrote it. At most 20 replies per hour and 3 per ticket and day. Requires `tickets:read`.
`invoices:write`	Create invoice drafts in its projects — also from open hours — and change their line items. Finalising, sending, cancelling and payments stay with you; the database enforces this, not just the interface.
`quotes:write`	Create and change quote drafts in its projects, maintain their line items and delete them again. Sending (and with it the number), accepting, declining and turning a quote into an invoice stay with you. It does not create a quote for a prospect without a customer record.
`errors:read`	Read the errors of its projects from your error tracker: title, level, status, number of events and affected users, times, link. No stack traces, no access data of the tracker.
`errors:write`	Mark an open error as resolved — first at the tracker (with the access of your error source), only on success in VentionDesk. If the access is read-only, the error stays open and Claude gets the reason. If it reappears, it counts as a regression (“Error again” in the bell, a new task after your threshold). Hiding and deleting stay with you. Requires `errors:read`.
`time:read`	Read the time entries of its projects: day, duration, description, task, billable and billed yes/no, name of the person. No hourly rates, no amounts. Your staff members’ names thereby go to the AI service.
`stats:read`	Key figures of its projects for reports: progress, tasks per status, open and overdue tickets, roadmap, monitors, deployments, open pull requests. No revenue, no budget, no costs.
`roadmap:write`	Read, create, rename, move, order and tick off roadmap phases of its projects — the next open phase is the milestone in the cockpit. Deleting stays with you.
`ideas:write`	Create new ideas, with one of its projects or (with “all projects”) without. Reading, changing and deleting stay with you — including the ideas it created itself.

In a ticket’s history, every reply from the agent is marked “sent by AI” with the name of the key.

2. Connect Claude Code

Install Claude Code and sign in, then in the terminal in your project’s folder:

claude mcp add --transport http ventiondesk https://api.ventiondesk.com/mcp --header "Authorization: Bearer vd_live_…"

Replace vd_live_… with your key — or copy the command straight from the “Connect Claude” card. Claude Code then talks over HTTP to VentionDesk’s MCP server (POST https://api.ventiondesk.com/mcp, stateless). The server accepts agent keys and the sign-in of a connected AI app; it rejects the token of a person signed in in the browser.

After that you simply ask Claude: “Which tasks are open in VentionDesk?” or “Take the next task in the project shop.”

3. The tools

The MCP server provides 38 tools. Each one calls the API with your key — so what a tool may do is determined by the key. If it lacks the scope, the tool answers with a missing permission.

Tool	What it does
`ventiondesk_list_projects`	Lists the projects the key may see, optionally by status.
`ventiondesk_get_project`	A project by its slug — with repository, branch, stack and task counts.
`ventiondesk_list_tasks`	Lists tasks, filtered by project, status and whether they can be pulled right now.
`ventiondesk_get_task`	A task with description, earlier results, project context and, on request, its images.
`ventiondesk_claim_next_task`	Claims the next open task by the runner's rule and shows it in full.
`ventiondesk_claim_task`	Claims a task — atomically, two runs never get the same one.
`ventiondesk_report_task_result`	Reports the state of a task and thereby sets its status.
`ventiondesk_create_task`	Creates a new task, for something noticed while working (title of 25 characters or more).
`ventiondesk_start_run`	Opens a run under which claims and results are logged.
`ventiondesk_finish_run`	Closes the run with a status and a one-line summary.
`ventiondesk_list_tickets`	Lists the tickets of a project.
`ventiondesk_get_ticket`	A ticket including its history.
`ventiondesk_add_ticket_note`	Writes an internal note into a ticket’s history.
`ventiondesk_draft_ticket_reply`	Creates a draft of a customer reply — it is not sent.
`ventiondesk_send_ticket_reply`	Sends the customer a reply by email — only with `tickets:reply`.
`ventiondesk_list_invoice_drafts`	Lists the invoice drafts of the key’s projects.
`ventiondesk_get_invoice_draft`	An invoice draft including line items.
`ventiondesk_create_invoice_draft`	Creates an invoice draft in a project.
`ventiondesk_invoice_from_unbilled`	Turns a project’s open hours into a draft, one line item per entry.
`ventiondesk_add_invoice_position`	Adds a line item to a draft.
`ventiondesk_update_invoice_position`	Changes a line item of a draft.
`ventiondesk_delete_invoice_position`	Removes a line item from a draft.
`ventiondesk_list_quote_drafts`	Lists the quote drafts of the key’s projects — only with `quotes:write`.
`ventiondesk_get_quote_draft`	A quote draft including line items.
`ventiondesk_create_quote_draft`	Creates a quote draft in a project; the recipient is the project’s customer.
`ventiondesk_update_quote_draft`	Changes title or validity of a quote draft.
`ventiondesk_delete_quote_draft`	Deletes a quote draft — it does not have a number yet.
`ventiondesk_add_quote_position`	Adds a line item to a quote draft.
`ventiondesk_update_quote_position`	Changes a line item of a quote draft.
`ventiondesk_delete_quote_position`	Removes a line item from a quote draft.
`ventiondesk_list_project_errors`	The open errors of a project — only with `errors:read`.
`ventiondesk_resolve_error`	Marks an open error as resolved at the tracker and here — only with `errors:write`.
`ventiondesk_list_time_entries`	The time entries of a project without rates and amounts — only with `time:read`.
`ventiondesk_get_project_report`	The project status for a report, without money — only with `stats:read`.
`ventiondesk_list_roadmap`	The roadmap phases of a project — only with `roadmap:write`.
`ventiondesk_create_roadmap_phase`	Creates a roadmap phase.
`ventiondesk_update_roadmap_phase`	Changes, orders or ticks off a phase.
`ventiondesk_create_idea`	Creates a new idea — only with `ideas:write`.

Without tickets:reply, Claude prepares replies as drafts and a person sends them. There is no tool for finalising, sending or paying an invoice, nor one for sending, accepting or declining a quote, for hiding or deleting an error, for deleting a phase or for reading, changing and deleting ideas.

4. Results

Claude reports back on every task with one of six results:

Result	Shown as	Effect
`arbeitet`	Still working	Progress update. The task stays “In progress”.
`kontrolle`	Needs review	Implemented and shipped. Status “To review” (Review column); requires evidence.
`frage`	Question for you	Question. Status “Question”; the task is not pulled again until someone answers.
`master`	For the owner to do	With the owner, without a status change — for example a step Claude has no access to.
`blockiert`	Blocked	Cannot continue. The task stays “In progress” and is with a person.
`erledigt`	Done	Done. Status “Done”; requires evidence.

To “Question”, “Needs review”, “For the owner to do” and “Blocked” you answer in the task detail view with approval or rejection — see Tasks and board. The task then goes back to Claude.

A round like /aufgaben, even without a file system (Claude in the browser or the app): “Work on the next open VentionDesk task” is enough. Claude claims the next task — the same selection as the runner —, reads the description, the history including rejections and the project (repository, live address, board link), fetches screenshots only when needed (withAttachments, at most three images of 1 MB each, other files as a link valid for one hour), reports the result with evidence and closes the round (claiming, reporting and closing the run are in the table above). Claude passes the runId from the claim on to the report and the close; a run without a sign of life is marked as timed out after 30 minutes.

Claude only pulls tasks that are assigned to nobody or to Claude and are neither on hold, in review nor done. A task Claude has already failed as often as allowed (default: three attempts, adjustable via maxAttempts) is no longer offered by VentionDesk; every answer from a person resets the counter.

5. Linking commits to tasks

If a commit message contains the line

VentionDesk-Task: <task ID>

VentionDesk links the commit to the task — provided GitHub is connected and the repository is entered in the project. The ID is the task’s UUID, as returned by the API and the tools.

6. Without MCP: the task runner and the API

If you let Claude or another tool work without MCP, it uses the same endpoints directly:

Start a run (optional, scope agent:run): POST /v1/agent/runs; during the work POST /v1/agent/runs/:id/heartbeat, at the end POST /v1/agent/runs/:id/finish. A run without a sign of life is marked as aborted after a while.
Pull: GET /v1/tasks?projectSlug=<slug>&claimable=true, then POST /v1/tasks/:id/claim.
Report back: POST /v1/tasks/:id/result with state (arbeitet, kontrolle, frage, master, blockiert, erledigt), summaryMd, detailsMd and, with kontrolle and erledigt, evidence in evidence.
Create new ones: POST /v1/tasks.

VentionDesk itself uses a small task runner made of dependency-free Node scripts for this (pull.mjs pulls, push.mjs reports back with --state, create.mjs creates, finish.mjs closes the run), controlled via the environment variables VENTIONDESK_API_KEY and VENTIONDESK_API_URL. It is not published as a package; for Claude Code the MCP way above is the simpler one.

All endpoints with parameters: API reference.