Überblick
Kanban-Board für KI-Agenten: der Agent führt das Board
Ein Kanban-Board für KI-Agenten: Der Agent legt es an, schreibt und verschiebt Karten, kommentiert und bucht Zeit über MCP oder API, Regeln erledigen den Rest.
Die meisten Boards werden von Hand aktualisiert: Jemand schaut ins Repository und zieht die Karte. Erledigt ein Coding-Agent die Arbeit, kann dieser Schritt wegfallen. Derselbe Agent, der den Code schreibt, kann auch das Board lesen, Karten anlegen, verschieben, kommentieren und die Zeit darauf buchen, über dasselbe API-Token, das er sowieso schon hat.
Die Einrichtung für Claude Code, Cursor und Codex steht auf Zuuna für KI-Agenten; wie eine Git-Regel auf dem Board nach dem Merge eine Karte verschiebt, steht bei der Git-Integration.
So arbeiten wir selbst damit
Zuunas eigene Entwicklung läuft genau so. Coding-Agenten, Claude Code darunter, legen die Karten für ihre Arbeit über die API an, kommentieren, was sie getan haben, und buchen ihre Zeit auf der Karte. Sie committen mit dem Karten-Schlüssel, und die Regeln auf unserem Board schieben die Karten von da an weiter.
Von der leeren Spalte bis erledigt
Ein Board, das leer anfängt: Ein einziger API-Aufruf legt es an, POST /api/v1/boards, mit Titel und der ID der Gruppe, zu der es gehört. Es kommt ohne Spalten zurück, die nächsten Aufrufe legen sie an, eine nach der anderen: POST /api/v1/boards/{id}/columns, für „Als Nächstes“, „In Arbeit“, „Review“ und „Erledigt“.
curl -X POST https://app.zuuna.de/api/v1/boards \
-H "Authorization: Bearer zk_live_dein_token" \
-H "Content-Type: application/json" \
-d '{"title": "App-Board", "groupId": "grp_1a2b3c"}'Von da an läuft das meiste aus dem Leben einer Karte über den MCP-Server allein. Der Agent legt die Karte mit zuuna_create_card an, mit Titel und Spalte („Als Nächstes“), dazu einem Idempotency-Key, damit ein Retry nach einer abgebrochenen Verbindung sie nicht doppelt anlegt. Typ, Fälligkeitsdatum, Schätzung oder Story Points setzt er stattdessen über die REST-API, mit PATCH /api/v1/cards/APP-12, denn das MCP-Werkzeug zuuna_update_card deckt nur Titel, Beschreibung und Priorität ab. Er verschiebt die Karte zwischen Spalten mit zuuna_move_card und kommentiert mit zuuna_comment, wenn ein Stück Arbeit fertig ist. Läuft der Agent in einer Shell, so wie Claude Code curl ausführt, kann er die Zeit auch direkt buchen: POST /api/v1/cards/APP-12/time mit {"duration": "1h 15m"}, oder einen laufenden Timer starten und stoppen mit {"action": "start"} und {"action": "stop"}. Mehr dazu auf der Seite Zeiterfassung; wenn du diese Stunden abrechnest, lies Projektmanagement mit Zeiterfassung und Rechnungen.
Die Regeln erledigen den Rest
Nichts davon schiebt eine Karte von selbst über den Punkt hinaus, an dem der Agent sie liegen lässt. Weiter tragen sie die Automationen, die du in den Board-Einstellungen anlegst: ein Auslöser, dann eine oder mehrere Aktionen, wahlweise eingeschränkt durch eine Bedingung wie die aktuelle Spalte der Karte. Ein paar werden sinnvoll, sobald ein Agent, oder ein verbundenes Repository, solche Ereignisse auslöst:
- Commit mit Karte verknüpft, über den CLI-Hook oder ein verbundenes Repository, dann Karte nach „In Arbeit“ verschieben, mit der Option, die sie nur vorwärts bewegen lässt.
- Pull Request gemergt, dann Karte nach „Erledigt“ verschieben. Dafür braucht es ein verbundenes GitHub-, GitLab- oder Gitea-Repository.
- CI fehlgeschlagen, dann Karte zurück nach „In Arbeit“ verschieben und kommentieren; eine Regel kann mehr als eine Aktion ausführen.
- Karte nach „Review“ verschoben, dann einer Person zuweisen, oder die vorhandenen Zugewiesenen benachrichtigen.
- Zeit auf einer Karte gebucht, die noch in „Als Nächstes“ liegt, dann nach „In Arbeit“ verschieben, denn gebuchte Zeit heißt, die Arbeit hat begonnen.
Der Agent arbeitet unter diesen Regeln und kann sie nicht ändern. Nur die REST-API kann sie lesen, mit GET /api/v1/boards/{id}/automations, das jede Regel mit ihren letzten fünf Läufen zurückgibt, sodass der Agent sagen kann, welche Regel eine Karte verschoben hat. MCP-Server und CLI haben überhaupt keinen Zugriff auf Regeln, und kein Token kann, auf keinem der drei Wege, eine Regel anlegen oder bearbeiten. Ein Mensch legt eine Regel in den Board-Einstellungen an, in etwa einer Minute.
Drei Wege hinein: MCP, API, CLI
| Gut für | Braucht | |
|---|---|---|
| MCP-Server | Board lesen, Karten anlegen und verschieben, kommentieren: die tägliche Runde, aus Claude Code, Cursor oder Codex heraus | Einen MCP-Client und ZUUNA_API_TOKEN |
| REST-API | Alles davon, plus Boards und Spalten anlegen, Custom Fields, Checklisten, Verknüpfungen, Sprints, Zeiterfassung, Kommentare lesen und Automationen lesen | Eine Shell, die der Agent nutzen kann, etwa Claude Code mit curl |
CLI (zuuna-cli) | Commits automatisch mit Karten verknüpfen, Releases aus Git-Tags schneiden | Git und curl, ein Token, sonst nichts |
Claude Code bindet den MCP-Server mit einem Befehl ein:
claude mcp add zuuna \
-e ZUUNA_API_TOKEN=zk_live_dein_token \
-- npx -y mcp-server-zuunaFür Cursor und Codex steht die Einrichtung auf der Agenten-Seite: Zuuna für KI-Agenten.
Scopes halten den Agenten in Grenzen
Ein API-Token trägt Scopes, und die Scopes entscheiden, was der Agent darf, nicht der Code, der zufällig läuft. Zwölf gibt es: boards:read, boards:write, cards:read, cards:write, comments:read, comments:write, time:read, time:write, git:write, releases:write, deployments:write und webhooks:manage. Ein Agent, der das Board nur beobachten und darüber berichten soll, braucht nur boards:read und cards:read. Einer, der die Runde oben durchläuft, Karten anlegt und verschiebt und Zeit bucht, braucht die passenden Write-Scopes, sonst nichts. Ein Token mit git:write oder deployments:write reicht weiter, als die meisten Agenten-Setups brauchen; vergib das pro Token, nicht standardmäßig.
Was das Board für Agenten nicht tut
- Keine eingebaute KI plant oder priorisiert das Board. Das entscheidet der Agent, der den Code schreibt, nicht Zuuna.
- Labels oder Epics setzen, eine Volltextsuche ausführen oder eine Karte auf ein anderes Board schieben geht über die API nicht. Das bleibt manuell, in der App.
- Es deployt nichts. Deploy-Gates und Releases laufen weiter über deine eigene Pipeline.
MCP, API und CLI brauchen alle drei den Developer-Tarif, denselben, der auch die Git-Integration freischaltet. Neue Workspaces bekommen 14 Tage Testphase im gewählten Tarif, ohne Kreditkarte, und jeder Workspace läuft auf Servern in Deutschland. Wie du den ersten Token anlegst, zeigt API-Token erstellen und erste Abfrage. Referenz: REST-API, CLI.
Häufige Fragen
Brauche ich einen kostenpflichtigen Tarif, damit ein Agent das Board nutzen kann?
Alles, was ein Agent über die API macht, und damit auch über MCP-Server und CLI, braucht den Developer-Tarif. Neue Workspaces bekommen 14 Tage Testphase im gewählten Tarif, ohne Kreditkarte.
Kann der Agent Automationsregeln selbst anlegen oder ändern?
Nein, mit Absicht. Nur die REST-API kann Regeln lesen; MCP-Server und CLI haben überhaupt keinen Zugriff darauf, und kein Token kann irgendwo eine Regel anlegen oder ändern. Der Agent kann über die API lesen, was existiert, erklären, welche Regel eine Karte verschoben hat, und eine neue Regel in Worten vorschlagen; ein Mensch legt sie in den Board-Einstellungen an.
Was hält den Agenten davon ab, mehr zu tun, als er soll?
Die Scopes auf seinem API-Token. Ein Token mit nur boards:read und cards:read kann nur ansehen; alles Weitere braucht die passenden Write-Scopes, und niemand zwingt dich, mehr zu vergeben, als die Runde braucht.
Braucht der Agent den MCP-Server, oder reicht curl?
Beides funktioniert. Der MCP-Server deckt die tägliche Runde ab: Board lesen, Karten anlegen, verschieben und kommentieren, aus Claude Code, Cursor oder Codex heraus. Ein Agent mit einer Shell kann für alles darüber hinaus, wie ein Board anlegen, Zeit buchen oder Kommentare lesen, direkt die REST-API aufrufen.
Funktioniert das auch mit anderen Agenten als Claude Code?
Ja. Alles, was das Model Context Protocol spricht, funktioniert mit dem MCP-Server; für Claude Code, Cursor und Codex gibt es je eine dokumentierte Einrichtung auf der Agenten-Seite. Ein Agent mit einer Shell kann auch direkt die REST-API aufrufen, ganz ohne MCP.