Entwickler

Claude und MCP

Claude arbeitet in VentionDesk wie ein Mitarbeiter: Es zieht Aufgaben, setzt sie um und meldet zurück — mit genau den Rechten des Schlüssels, den du ihm gibst. VentionDesk führt dafür kein eigenes Modell aus und berechnet nichts: Du bringst dein eigenes Claude mit (Claude Code mit deinem Claude-Abo oder Anthropic-Schlüssel).

Zwei Wege führen dorthin: der MCP-Server — empfohlen für Claude Code — und die API direkt, etwa aus eigenen Skripten.

1. Agenten-Schlüssel anlegen

Einstellungen › Rollen & Zugänge › „Neuer Schlüssel", Art „Agent":

Berechtigungen: für die Aufgabenarbeit projects:read, tasks:read und tasks:write; notes:write, wenn Claude Notizen anlegen soll; agent:run, wenn Läufe protokolliert werden sollen.
Projekte: alle oder nur die, an denen Claude arbeiten soll.
Läuft ab: Vorschlag 365 Tage.

Der Schlüssel (vd_live_…) erscheint genau einmal. Direkt darunter steht die Karte „Claude verbinden" mit dem fertigen Befehl samt Schlüssel.

Agenten-Schlüssel dürfen tickets:read und tickets:write nicht tragen: Vorgänge enthalten Namen, Adressen und Bildschirmfotos deiner Kunden. Die Werkzeuge für Vorgänge (unten) antworten einem Agenten-Schlüssel deshalb mit fehlender Berechtigung.

2. Claude Code verbinden

Claude Code installieren und anmelden, dann im Terminal im Ordner deines Projekts:

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

Ersetze vd_live_… durch deinen Schlüssel — oder kopiere den Befehl gleich aus der Karte „Claude verbinden". Claude Code spricht damit über HTTP mit dem MCP-Server von VentionDesk (POST https://api.ventiondesk.com/mcp, zustandslos). Der Server nimmt nur Agenten-Schlüssel an; das Token einer angemeldeten Person weist er ab.

Danach fragst du Claude einfach: „Welche Aufgaben sind in VentionDesk offen?" oder „Nimm dir die nächste Aufgabe im Projekt shop."

3. Die Werkzeuge

Der MCP-Server stellt elf Werkzeuge bereit. Jedes ruft die API mit deinem Schlüssel auf — was ein Werkzeug darf, bestimmt also der Schlüssel.

Werkzeug	Was es tut
`ventiondesk_list_projects`	Listet die Projekte, die der Schlüssel sehen darf, optional nach Status.
`ventiondesk_get_project`	Ein Projekt über seinen Slug — mit Repository, Zweig, Stack und Aufgabenstand.
`ventiondesk_list_tasks`	Listet Aufgaben, gefiltert nach Projekt, Status und ob sie gerade gezogen werden können.
`ventiondesk_get_task`	Eine Aufgabe mit Beschreibung, bisherigen Rückmeldungen und Anhängen.
`ventiondesk_claim_task`	Übernimmt eine Aufgabe — atomar, zwei Läufe bekommen nie dieselbe.
`ventiondesk_report_task_result`	Meldet den Stand einer Aufgabe zurück und setzt damit ihren Status.
`ventiondesk_create_task`	Legt eine neue Aufgabe an, für etwas, das beim Arbeiten aufgefallen ist (Titel ab 25 Zeichen).
`ventiondesk_list_tickets`	Listet Vorgänge eines Projekts.
`ventiondesk_get_ticket`	Ein Vorgang samt Verlauf.
`ventiondesk_add_ticket_note`	Schreibt eine interne Notiz in den Verlauf eines Vorgangs.
`ventiondesk_draft_ticket_reply`	Legt einen Entwurf einer Kundenantwort an — gesendet wird er nicht.

Ein Werkzeug, das dem Kunden antwortet, gibt es bewusst nicht: Claude bereitet Antworten als Entwurf vor, senden tut ein Mensch.

4. Rückmeldungen

Claude meldet jede Aufgabe mit einer von sechs Rückmeldungen zurück:

Rückmeldung	Anzeige	Wirkung
`arbeitet`	Arbeitet weiter	Zwischenstand. Die Aufgabe bleibt „In Bearbeitung".
`kontrolle`	Kontrolle nötig	Umgesetzt und ausgeliefert. Status „Kontrollieren" (Spalte Review); verlangt einen Beleg.
`frage`	Rückfrage an dich	Rückfrage. Status „Rückfrage"; die Aufgabe wird nicht erneut gezogen, bis jemand antwortet.
`master`	Für den Inhaber zu tun	Liegt beim Inhaber, ohne Statuswechsel — etwa ein Schritt, zu dem Claude keinen Zugang hat.
`blockiert`	Blockiert	Kommt nicht weiter. Die Aufgabe bleibt „In Bearbeitung" und liegt beim Menschen.
`erledigt`	Erledigt	Fertig. Status „Erledigt"; verlangt einen Beleg.

Auf „Rückfrage", „Kontrolle nötig", „Für den Inhaber zu tun" und „Blockiert" antwortest du im Aufgaben-Detail mit Freigabe oder Absage — siehe Aufgaben und Board. Die Aufgabe geht danach an Claude zurück.

Claude zieht nur Aufgaben, die niemandem oder Claude zugewiesen sind und weder zurückgestellt, in Kontrolle noch erledigt sind. Eine Aufgabe, an der Claude schon so oft gescheitert ist wie erlaubt (Vorgabe: drei Versuche, über maxAttempts einstellbar), bietet VentionDesk nicht mehr an; jede Antwort eines Menschen setzt den Zähler zurück.

5. Commits mit Aufgaben verknüpfen

Steht in einer Commit-Nachricht die Zeile

VentionDesk-Task: <Aufgaben-ID>

verknüpft VentionDesk den Commit mit der Aufgabe — vorausgesetzt, GitHub ist verbunden und das Repository im Projekt eingetragen. Die ID ist die UUID der Aufgabe, wie sie die API und die Werkzeuge liefern.

6. Ohne MCP: der Aufgaben-Runner und die API

Wer Claude oder ein anderes Werkzeug ohne MCP arbeiten lässt, benutzt dieselben Endpunkte direkt:

Lauf beginnen (optional, Scope agent:run): POST /v1/agent/runs; während der Arbeit POST /v1/agent/runs/:id/heartbeat, am Ende POST /v1/agent/runs/:id/finish. Ein Lauf ohne Lebenszeichen wird nach einer Weile als abgebrochen markiert.
Ziehen: GET /v1/tasks?projectSlug=<slug>&claimable=true, dann POST /v1/tasks/:id/claim.
Zurückmelden: POST /v1/tasks/:id/result mit state (arbeitet, kontrolle, frage, master, blockiert, erledigt), summaryMd, detailsMd und bei kontrolle und erledigt einem Beleg in evidence.
Neues anlegen: POST /v1/tasks.

VentionDesk selbst benutzt dafür einen kleinen Aufgaben-Runner aus abhängigkeitsfreien Node-Skripten (pull.mjs zieht, push.mjs meldet mit --state zurück, create.mjs legt an, finish.mjs schließt den Lauf), gesteuert über die Umgebungsvariablen VENTIONDESK_API_KEY und VENTIONDESK_API_URL. Er ist nicht als Paket veröffentlicht; für Claude Code ist der MCP-Weg oben der einfachere.

Alle Endpunkte mit Parametern: API-Referenz.