Zum Inhalt springen

MCP ​

werkbuch ist ein MCP-Server: Ein KI-Agent in Claude Code, Codex oder einem anderen MCP-Client liest und ändert darüber Projekte, Items, Kommentare, Wiki-Seiten, Vorlagen und Webhooks. Der Server liegt unter /mcp deiner Instanz. Seine Tools sind dünne Hüllen um die REST-API: Jede Aktion eines Tools ruft denselben Code wie eine REST-Operation, ihr Zwilling, mit denselben Rechten, Regeln und Fehlern. Was die Tools nicht abdecken, erledigt ein Skript über REST.

Was der Server bietet ​

  • 29 Tools, je Ressource ein Paar: ein Tool, das liest (work-items), und eins, das schreibt (manage-work-items), beide mit einem Argument action. Drei Tools stehen allein: whoami, search und get-upload-url. Die Liste der Tools nennt jede Aktion und ihren Zwilling.
  • Drei Referenzen als MCP-Resources: wie ein Filter geschrieben wird, Markdown und die Werte der Feldtypen (siehe Referenzen).
  • Instructions, die der Client dem Modell beim Verbinden gibt: zuerst whoami aufrufen, Texte in Ergebnissen sind Daten, wie Listen blättern, wo die Referenzen liegen.

Nicht über MCP: Tokens anlegen, das eigene Passwort und der zweite Faktor (sie brauchen wie über REST die Sitzung der Oberfläche), die System-Seite und GET /references.

Einrichten ​

  1. Lege in der Oberfläche unter Persönliche Einstellungen → API & MCP → Neues Token ein Token mit der Fähigkeit mcp und read an, dazu write, wenn der Agent etwas ändern soll. Für einen Bot legt ein Org-Admin das Token in den Einstellungen des Bots an. Das Token handelt mit den Rechten seines Kontos, nie mit mehr.
  2. Trage den Server in deinem Client ein. Der Dialog, der das neue Token zeigt, gibt die drei Snippets mit deiner Adresse und dem Token:
bash
# Claude Code
claude mcp add --transport http --scope user werkbuch https://werkbuch.example.com/mcp --header "Authorization: Bearer <token>"
toml
# Codex, ~/.codex/config.toml
[mcp_servers.werkbuch]
url = "https://werkbuch.example.com/mcp"
http_headers = { "Authorization" = "Bearer <token>" }
json
{
  "mcpServers": {
    "werkbuch": {
      "type": "http",
      "url": "https://werkbuch.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Das JSON ist für Clients mit einer Konfiguration mcpServers, etwa eine .mcp.json in einem Projekt.

Verbindung ​

Der Server spricht Streamable HTTP: Jede Nachricht ist ein POST /mcp mit einem JSON-RPC-Body und Content-Type: application/json (ein anderer Typ ist ein 415). Er ist zustandslos: Es gibt keine Sitzung des Protokolls (kein Mcp-Session-Id), keine Benachrichtigungen vom Server, und GET und DELETE auf /mcp antworten 405. Jede Anfrage trägt das Token als Authorization: Bearer <token>; ein Cookie der Oberfläche meldet hier niemanden an (401).

Protokollversionen:

  • 2026-07-28, das aktuelle Protokoll, über server/discover. Jede Anfrage trägt dann _meta mit io.modelcontextprotocol/protocolVersion und io.modelcontextprotocol/clientCapabilities und die Header MCP-Protocol-Version: 2026-07-28, Mcp-Method (die Methode des Bodys) und bei tools/call und resources/read Mcp-Name (das Tool bzw. die URI). Ein fehlender oder widersprechender Header ist der JSON-RPC-Fehler -32020 mit dem Status 400.
  • 2025-11-25, 2025-06-18 und 2025-03-26 über initialize; ein Client, der eine ältere Version erfragt, bekommt 2025-11-25.

Ein Browser kann den Server nicht für eine andere Seite benutzen: Ein Origin-Header, der nicht die Adresse deiner Instanz ist, ist ein 403; eine Anfrage ohne Origin (jeder Client auf der Kommandozeile) geht durch. tools/list nennt alle Tools, die das Token benutzen darf, auf einer Seite.

bash
curl https://werkbuch.example.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' -H 'Mcp-Name: whoami' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "whoami", "arguments": {}, "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}}}}'

Was ein Token sieht ​

Hinein kommt nur ein Token mit der Fähigkeit mcp. Ein Tool, das liest, braucht dazu read, ein Tool, das schreibt (manage-… und get-upload-url), braucht write. Ein Tool, das das Token nicht benutzen darf, fehlt in tools/list; wer es trotzdem aufruft, bekommt den JSON-RPC-Fehler -32602 („Tool [x] not found.“). Ein Token mit nur read und mcp sieht die 15 lesenden Tools und kann nichts ändern. Die Referenzen brauchen nur mcp.

Darüber hinaus sieht ein Tool genau, was sein Konto über REST sieht. Was das Konto nicht sehen darf, bekommt dieselbe Antwort wie etwas, das es nicht gibt (404): ein Item eines privaten Projekts, ein Kommentar daran, sein Key in der Suche. Eine Relation oder ein Verweis auf ein solches Item zeigt das andere Ende verborgen, ohne Key, Titel und ID.

Grenzen ​

  • Anfragen: 300 je Minute je gültigem Token (MCP_RATE_LIMIT), ohne gültiges Token 300 je Adresse. Das ist ein eigenes Kontingent neben den 600 der REST-API: Ein Agent, der beides nutzt, bremst das andere nicht. Gezählt wird vor der Anmeldung. Jede Antwort trägt X-RateLimit-Limit und X-RateLimit-Remaining; über der Grenze ist die Antwort 429 mit Retry-After. Hinter einem Reverse Proxy braucht die Zählung je Adresse den Proxy in TRUSTED_PROXIES (Betrieb).
  • Geteilt mit REST: Ein Test-Ping und redeliver eines Webhooks zählen in denselben 6 je Minute und Konto wie über REST, Uploads über get-upload-url in denselben 60 je Minute und Konto. Ein Tool über einer solchen Grenze antwortet mit dem Fehler 429 too_many_requests und retry_after in Sekunden.
  • Bodies: Ein JSON-Body über 8 MiB (8 388 608 Bytes) ist ein 413; Uploads haben ihre eigene Grenze, ATTACHMENTS_MAX_MB.
  • Seiten: per_page ist 1 bis 100, weggelassen 25.

Tools ​

Ein Tool mit mehreren Aktionen nimmt das Argument action. Ein Tool mit einer Aktion (whoami, search, get-upload-url, automations, manage-automations, relations, attachments, manage-attachments) nimmt keins; die Tabelle nennt seine Aktion trotzdem (call bei den ersten dreien). Die Doku schreibt eine Aktion als tool:aktion, etwa work-items:get. Pflicht nennt die Argumente, die eine Aktion außer action braucht; REST-Zwilling ist die Operation unter /api/v1, der die Aktion folgt, mit Parametern, Body und Antwort in der Referenz unter /api/docs.

whoami ​

Das Konto des Tokens: Person oder Bot, Sprache, Zeitzone, Rolle in der Organisation und die Rechte dieser Rolle. Als Erstes aufrufen. (Braucht read.)

AktionZweckPflichtREST-Zwilling
callDas Konto des Tokens.–GET /me

Sucht Items, Wiki-Seiten, Projekte, Personen und Views zugleich, wie die Befehlspalette. Jedes Wort muss treffen, ein Key (WEB-47) stellt sein Item nach vorn. type_id, state_category, assignee_id (none allein: Items ohne Assignee) und label_id engen die Items ein. Treffer sind schlank. (Braucht read.)

AktionZweckPflichtREST-Zwilling
callSucht.qGET /search

get-upload-url ​

Eine Adresse, an die eine Datei geht, siehe Datei hochladen. (Braucht write.)

AktionZweckPflichtREST-Zwilling
callEine Adresse für den Upload.input–

organization ​

Die Organisation und ihre Kataloge: Workflows, Typen, Properties, Labels, Relationstypen und Resolutions. Jedes Konto liest sie. (Braucht read.)

AktionZweckPflichtREST-Zwilling
getDie Organisation.–GET /organization
state-usageDie Items je Status eines Projekts oder eines Workflows, archivierte eingeschlossen (project oder workflow).–GET /state-usage
list-workflowsDie Workflows.–GET /workflows
get-workflowEin Workflow.idGET /workflows/{workflow}
list-typesDie Typen.–GET /work-item-types
get-typeEin Typ.idGET /work-item-types/{workItemType}
list-propertiesDie Properties.–GET /properties
get-propertyEine Property.idGET /properties/{property}
list-labelsDie Labels.–GET /labels
get-labelEin Label.idGET /labels/{label}
list-relation-typesDie Relationstypen.–GET /relation-types
get-relation-typeEin Relationstyp.idGET /relation-types/{relationType}
list-resolutionsDie Resolutions.–GET /resolutions
get-resolutionEine Resolution.idGET /resolutions/{resolution}

manage-organization ​

Ändert die Organisation und ihre Kataloge; nur Org-Admins. update-… ersetzt den Eintrag ganz, wie PUT. (Braucht write.)

AktionZweckPflichtREST-Zwilling
updateÄndert die Organisation; nur die genannten Schlüssel ändern sich.inputPATCH /organization
create-workflowLegt einen Workflow an.inputPOST /workflows
update-workflowErsetzt einen Workflow.id, inputPUT /workflows/{workflow}
delete-workflowLöscht einen Workflow.idDELETE /workflows/{workflow}
create-typeLegt einen Typ an.inputPOST /work-item-types
update-typeErsetzt einen Typ.id, inputPUT /work-item-types/{workItemType}
delete-typeLöscht einen Typ (archiviert ihn, solange Items ihn tragen).idDELETE /work-item-types/{workItemType}
create-propertyLegt eine Property an.inputPOST /properties
update-propertyErsetzt eine Property.id, inputPUT /properties/{property}
delete-propertyLöscht eine Property mit ihren Werten.idDELETE /properties/{property}
create-labelLegt ein Label an.inputPOST /labels
update-labelErsetzt ein Label.id, inputPUT /labels/{label}
delete-labelLöscht ein Label.idDELETE /labels/{label}
create-relation-typeLegt einen Relationstyp an.inputPOST /relation-types
update-relation-typeErsetzt einen Relationstyp.id, inputPUT /relation-types/{relationType}
delete-relation-typeLöscht einen Relationstyp mit seinen Relationen.idDELETE /relation-types/{relationType}
create-resolutionLegt eine Resolution an.inputPOST /resolutions
update-resolutionErsetzt eine Resolution.id, inputPUT /resolutions/{resolution}
delete-resolutionLöscht eine Resolution (archiviert sie, solange Items sie tragen).idDELETE /resolutions/{resolution}

people ​

Konten: Personen und Bots, offene Einladungen, API-Tokens (die eigenen; Org-Admins auch die der Bots) und wer in einem Projekt erwähnt werden kann. (Braucht read.)

AktionZweckPflichtREST-Zwilling
list-usersDie Konten, Personen vor Bots (filter.type nimmt person und bot).–GET /users
get-userEin Konto.idGET /users/{user}
list-botsDie Bots.–GET /bots
list-invitationsDie offenen Einladungen.–GET /invitations
list-tokensDie API-Tokens des eigenen Kontos oder des Kontos in filter.user_id.–GET /tokens
mentionableWer in einem Projekt erwähnt werden kann.projectGET /mentions

manage-people ​

Ändert Konten; die meisten Aktionen sind für Org-Admins. Eine neue E-Mail-Adresse einer Person kommt nur aus der Oberfläche (403 session_required), und Tokens entstehen nur dort. (Braucht write.)

AktionZweckPflichtREST-Zwilling
update-userÄndert ein Profil; nur die genannten Schlüssel ändern sich.id, inputPATCH /users/{user}
set-roleSetzt die Rolle in der Organisation (org_role).id, inputPUT /users/{user}/role
deactivateDeaktiviert ein Konto; seine Tokens und Sitzungen enden.idPOST /users/{user}/deactivate
reactivateAktiviert ein Konto wieder; Tokens kommen nicht zurück.idPOST /users/{user}/reactivate
create-botLegt einen Bot an.inputPOST /bots
inviteLädt eine Adresse ein; antwortet {link, invitation}.inputPOST /invitations
revoke-tokenWiderruft ein API-Token.idDELETE /tokens/{token}

projects ​

Die Projekte, die das Konto sieht, ein Projekt, seine Mitglieder und die eigenen Favoriten. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listDie Projekte des Kontos (filter.member nur die, in denen es Mitglied ist; include members).–GET /projects
getEin Projekt.projectGET /projects/{project}
membersDie Mitglieder eines Projekts, Personen und Bots mit ihrer Rolle.projectGET /projects/{project}/members
favoritesDie eigenen Favoriten, Projekte und Views in einer Reihenfolge.–GET /favorites

manage-projects ​

Projekte, ihre Mitglieder und die eigenen Favoriten. Ein Projekt ändern seine Admins. (Braucht write.)

AktionZweckPflichtREST-Zwilling
createLegt ein Projekt an; das Konto wird sein Admin.inputPOST /projects
updateÄndert ein Projekt; nur die genannten Schlüssel ändern sich.project, inputPATCH /projects/{project}
archiveArchiviert ein Projekt; seine Items sind schreibgeschützt.projectPOST /projects/{project}/archive
restoreHolt ein archiviertes Projekt zurück.projectPOST /projects/{project}/restore
deleteLöscht ein Projekt sofort für alle; seine Daten gehen im Hintergrund.projectDELETE /projects/{project}
set-workflowWechselt den Workflow; jeder benutzte Status braucht ein Ziel in mapping, sonst 422 mit states.project, inputPUT /projects/{project}/workflow
redistribute-ranksGibt den Items neue kurze Ränge in ihrer Ordnung; antwortet {redistributed}.projectPOST /projects/{project}/redistribute-ranks
joinTritt einem Projekt als Mitglied bei.projectPOST /projects/{project}/join
add-memberFügt ein Konto mit einer Rolle hinzu.project, inputPOST /projects/{project}/members
update-memberÄndert die Rolle eines Mitglieds.project, user, inputPATCH /projects/{project}/members/{user}
remove-memberEntfernt ein Mitglied; die Lead-Person bleibt.project, userDELETE /projects/{project}/members/{user}
toggle-favoriteNimmt ein Projekt oder eine View in die eigenen Favoriten auf oder heraus; antwortet {kind, id, favorite}.inputPOST /favorites/toggle

automations ​

Die fünf Automatisierungen eines Projekts mit ihren Einstellungen; link_references ist ohne gespeicherte Zeile an. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listDie Automatisierungen eines Projekts.projectGET /projects/{project}/automations

manage-automations ​

Schaltet eine Automatisierung eines Projekts und setzt ihre Einstellungen; die Admins des Projekts. (Braucht write.)

AktionZweckPflichtREST-Zwilling
updateSchaltet eine Automatisierung an oder aus und setzt ihre Einstellungen.project, key, inputPUT /projects/{project}/automations/{key}

work-items ​

Listen nach einer View und der Kurzform von filter, Abfragen mit einem Body, Gruppen und Zählungen, ein Item mit dem, was es einbettet, seine History und seine Beobachter. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listEine Seite Items (schlank, außer lean ist 0).–GET /work-items
queryEine Seite Items nach einem Filter in input.–POST /work-items/query
groupsDie Gruppen einer Abfrage und ihre Zahlen.inputPOST /work-items/groups
countsDie Zahl der Items je benanntem Filter.inputPOST /work-items/counts
getEin Item; include bettet mehr ein.itemGET /work-items/{item}
historyDie History eines Items, älteste zuerst.itemGET /work-items/{item}/history
subscribersWer ein Item beobachtet.itemGET /work-items/{item}/subscribers

manage-work-items ​

Legt Items an und ändert sie. Eine Beschreibung mit base_description_version wird mit 409 description_conflict abgelehnt, wenn sie inzwischen jemand geändert hat. (Braucht write.)

AktionZweckPflichtREST-Zwilling
createLegt ein Item an.inputPOST /work-items
updateÄndert die Schlüssel aus input.item, inputPATCH /work-items/{item}
transitionZieht ein Item in einen anderen Status.item, inputPOST /work-items/{item}/transition
change-typeGibt einem Item einen anderen Typ.item, inputPUT /work-items/{item}/type
archiveArchiviert ein geschlossenes Item.itemPOST /work-items/{item}/archive
restoreHolt ein archiviertes Item zurück.itemPOST /work-items/{item}/restore
deleteLöscht ein Item endgültig.itemDELETE /work-items/{item}
bulk-updateEine Änderung für viele Items.inputPOST /work-items/bulk
subscribeBeobachtet ein Item.itemPUT /work-items/{item}/subscription
unsubscribeBeobachtet ein Item nicht mehr.itemDELETE /work-items/{item}/subscription

relations ​

Die Relationen eines Items. Ein Ende in einem Projekt, das das Konto nicht sieht, ist hidden, ohne Key, Titel und ID. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listDie Relationen eines Items.itemGET /work-items/{item}/relations

manage-relations ​

Verknüpft Items und entfernt Relationen. (Braucht write.)

AktionZweckPflichtREST-Zwilling
addVerknüpft ein Item (item, die Quelle) mit input.target_id (ULID oder Key).item, inputPOST /work-items/{item}/relations
removeEntfernt eine Relation, von jedem Ende aus, das das Konto ändern darf.relationDELETE /relations/{relation}

comments ​

Die Kommentare eines Items, älteste zuerst, mit ihren Reaktionen. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listEine Seite der Kommentare eines Items.itemGET /work-items/{item}/comments
getEin Kommentar.commentGET /comments/{comment}

manage-comments ​

Schreibt Kommentare. Bearbeiten darf nur, wer ihn schrieb; löschen dazu die Projekt-Admins. (Braucht write.)

AktionZweckPflichtREST-Zwilling
addKommentiert ein Item.item, inputPOST /work-items/{item}/comments
editErsetzt den Text des eigenen Kommentars.comment, inputPATCH /comments/{comment}
deleteLöscht einen Kommentar (wer ihn schrieb oder ein Projekt-Admin).commentDELETE /comments/{comment}
reactFügt die eigene Reaktion hinzu.comment, inputPUT /comments/{comment}/reactions
unreactNimmt die eigene Reaktion zurück.comment, inputDELETE /comments/{comment}/reactions

attachments ​

Die Daten eines Bilds oder einer Datei. Die Datei selbst liefert url mit demselben Bearer-Token (?download=1 zum Herunterladen). (Braucht read.)

AktionZweckPflichtREST-Zwilling
getDie Daten eines Anhangs.attachmentGET /attachments/{attachment}

manage-attachments ​

Löscht eine Datei aus der Dateiliste eines Items oder einen eigenen Upload, den noch kein Text nennt. Ein Bild oder eine Datei in einem Text geht mit dem Text (409 attachment_inline). (Braucht write.)

AktionZweckPflichtREST-Zwilling
deleteLöscht einen Anhang.attachmentDELETE /attachments/{attachment}

pages ​

Das Wiki eines Projekts: der Baum, eine Seite mit ihrem Text, die Versionen einer Seite, die Seiten, die ein Work Item nennen, wo sich eine Seite als PDF laden lässt. (Braucht read.)

AktionZweckPflichtREST-Zwilling
treeDer ganze Baum eines Projekts, ohne Text.projectGET /projects/{project}/pages
getEine Seite mit ihrem Text.pageGET /pages/{page}
versionsDie Versionen einer Seite, neueste zuerst, ohne Text.pageGET /pages/{page}/versions
versionEine Version einer Seite mit ihrem Text.page, page_versionGET /pages/{page}/versions/{pageVersion}
itemDie Seiten, die ein Work Item nennen, nach Titel, ohne Text.itemGET /work-items/{item}/pages
pdfWo sich eine Seite als PDF laden lässt (mit subpages samt Teilbaum); url mit demselben Token abrufen.pageGET /pages/{page}/pdf

manage-pages ​

Schreibt Wiki-Seiten, mit dem Konfliktschutz der REST-API (base_version, keep_current). (Braucht write.)

AktionZweckPflichtREST-Zwilling
createEine neue Seite am Ende ihrer Geschwister.project, inputPOST /projects/{project}/pages
updateSpeichert die gesendeten Schlüssel.page, inputPATCH /pages/{page}
moveVerschiebt eine Seite mit ihrem Teilbaum.page, inputPOST /pages/{page}/move
deleteLöscht eine Seite mit ihrem Teilbaum; antwortet {deleted}.pageDELETE /pages/{page}
restore-versionMacht eine Version zur aktuellen Seite.page, page_versionPOST /pages/{page}/versions/{pageVersion}/restore

templates ​

Vorlagen für Items: die Liste, eine Vorlage, ihre Läufe, der Entwurf eines Items daraus und die nächsten Termine eines Zeitplans. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listEine Seite der Vorlagen aller Projekte, die das Konto sieht.–GET /templates
getEine Vorlage.templateGET /templates/{template}
runsDie Läufe einer Vorlage, neueste zuerst.templateGET /templates/{template}/runs
draftDie Felder eines neuen Items aus einer Vorlage, Platzhalter gefüllt.templateGET /templates/{template}/draft
previewDie nächsten Termine eines Zeitplans und ein Titel mit gefüllten Platzhaltern; speichert nichts.inputPOST /templates/preview

manage-templates ​

Schreibt Vorlagen und führt sie sofort aus. Ein gescheiterter Lauf antwortet mit seinem Satz, nicht mit einem Fehler. (Braucht write.)

AktionZweckPflichtREST-Zwilling
createEine neue Vorlage in einem Projekt.project, inputPOST /projects/{project}/templates
updateErsetzt eine Vorlage ganz.template, inputPUT /templates/{template}
deleteLöscht eine Vorlage; Items daraus bleiben.templateDELETE /templates/{template}
runFührt eine Vorlage sofort aus; antwortet den Lauf und sein Item (keins, wenn der Lauf scheiterte).templatePOST /templates/{template}/run

views ​

Die Views des Teams und eine Seite der Items einer View. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listDie Views, nach Name.–GET /views
getEine View mit Filter und Darstellung.viewGET /views/{view}
itemsEine Seite der Items einer View (schlank, außer lean ist false).viewPOST /work-items/query

manage-views ​

Legt Views an, ersetzt und löscht sie; wer die View anlegte oder ein Org-Admin. (Braucht write.)

AktionZweckPflichtREST-Zwilling
createLegt eine View an.inputPOST /views
updateErsetzt eine View (alle vier Schlüssel).view, inputPUT /views/{view}
deleteLöscht eine View samt den Sternen aller daran.viewDELETE /views/{view}

notifications ​

Die eigene Inbox und die eigenen Benachrichtigungseinstellungen. Ein Bot hat eine leere Inbox. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listEine Seite der eigenen Inbox, neueste zuerst.–GET /notifications
preferencesDie ganze Matrix aus Arten und Kanälen mit dem Wert, der gilt.–GET /notification-preferences

manage-notifications ​

Markiert eigene Benachrichtigungen als gelesen oder ungelesen, löscht sie und ändert die Einstellungen. (Braucht write.)

AktionZweckPflichtREST-Zwilling
readMarkiert Benachrichtigungen als gelesen: nach IDs oder alle ungelesenen.inputPOST /notifications/read
unreadMarkiert gelesene Benachrichtigungen wieder als ungelesen.inputPOST /notifications/unread
deleteLöscht eine Benachrichtigung der eigenen Inbox.notificationDELETE /notifications/{notification}
save-preferencesÄndert die genannten Zellen der Einstellungen; antwortet die ganze Matrix.inputPUT /notification-preferences

webhooks ​

Webhooks und ihr Zustellprotokoll; nur Org-Admins. Das Geheimnis steht nie darin. (Braucht read.)

AktionZweckPflichtREST-Zwilling
listEine Seite der Webhooks.–GET /webhooks
getEin Webhook.webhookGET /webhooks/{webhook}
deliveriesDie Versuche eines Webhooks, neueste zuerst.webhookGET /webhooks/{webhook}/deliveries

manage-webhooks ​

Schreibt Webhooks; nur Org-Admins. create und rotate-secret nennen das Geheimnis einmal. ping und redeliver rufen den Empfänger auf, zusammen mit der REST-API 6-mal je Minute und Konto. (Braucht write.)

AktionZweckPflichtREST-Zwilling
createLegt einen Webhook an; antwortet {data, secret}.inputPOST /webhooks
updateErsetzt einen Webhook ganz; ohne Geheimnis in der Antwort.webhook, inputPUT /webhooks/{webhook}
deleteLöscht einen Webhook mit seinen Versuchen.webhookDELETE /webhooks/{webhook}
rotate-secretEin neues Geheimnis, das alte gilt nicht mehr; antwortet {data, secret}.webhookPOST /webhooks/{webhook}/rotate-secret
pingSendet sofort einen Test-Ping und antwortet seinen Versuch.webhookPOST /webhooks/{webhook}/ping
redeliverSendet eine Zustellung erneut und antwortet den neuen Versuch.webhook, deliveryPOST /webhooks/{webhook}/deliveries/{delivery}/redeliver

Argumente ​

  • Referenzen im Pfad des Zwillings sind Argumente in snake_case: item (ULID oder Key, auch ein früherer: das Item kommt mit seinem aktuellen Key, eine Umleitung gibt es nicht), project (ULID, Kennung oder frühere Kennung), page, page_version, comment, template, view, webhook usw. (ULIDs in jeder Schreibweise), id für einen Eintrag eines Katalogs, ein Konto oder ein Token, außer wo die Route das Konto neben einem Projekt als {user} nennt: manage-projects nimmt das Mitglied in update-member und remove-member als user.
  • input ist der Body des REST-Zwillings, mit denselben Schlüsseln und demselben Schema wie unter /api/docs. Rich Text geht als Markdown hinein (description, body, content) oder als Tiptap-JSON unter dem Schlüssel mit _json, wie über REST.
  • Queries eines GET-Zwillings sind eigene Argumente: filter ist ein Objekt ({"assignee": ["me"]}), Listen sind JSON-Listen (["person", "bot"]), Flags true und false oder 1 und 0. Texte werden wie über REST getrimmt, auch Unicode-Leerraum.
  • Seiten: cursor ist das meta.next_cursor der Seite davor, per_page weggelassen 25 (REST: 100). Listen von Items sind schlank, wenn lean fehlt (work-items:list, work-items:query, views:items, templates:list): ohne Beschreibung und ohne Markdown der Rich-Text-Werte; mit lean: false kommen sie mit, oder das Item über work-items:get. Wer beides setzt, bekommt dieselbe Antwort wie über REST.

Ergebnisse ​

Das Ergebnis eines Tools ist der Body der REST-Antwort, als structuredContent und als JSON-Text gespiegelt in content, mit drei Unterschieden:

  • Rich Text nur als Markdown: description, body, content und die Rich-Text-Werte in values sind Markdown für das Konto (aktuelle Handles, Keys von Items, die es sieht, [hidden](item:…) für den Rest); die Formen mit _json fallen weg.
  • Keine links: Eine Liste hat data und meta; meta.path ist die Adresse des REST-Zwillings, meta.next_cursor führt zur nächsten Seite.
  • Antworten ohne Body (204, 202) sind {"done": true}.

Ein Tool, das schreibt, antwortet, was REST antwortet: das Item nach der Änderung, {updated, rejected} von manage-work-items:bulk-update, {deleted} von manage-pages:delete, den Lauf von manage-templates:run, auch wenn er scheiterte (mit seinem Satz in error).

Fehler ​

Eine Ablehnung ist ein Ergebnis mit isError: true. Sein Text ist eine Zeile <status> <reason>: <detail>, danach je Feldfehler eine Zeile <feld>: <satz>; structuredContent ist das Problem, das REST antworten würde, mit demselben reason und in der Sprache des Kontos. Ein 429 hat dazu retry_after in Sekunden.

text
422 validation_failed: Die Eingabe ist nicht gültig.
values.customer: „Kunde“ ist ein Pflichtfeld.

Manche Fehler kommen, bevor ein Tool läuft, und sind HTTP-Antworten: 401 ohne gültiges Token oder für ein deaktiviertes Konto (mit WWW-Authenticate), 403 für ein Token ohne mcp oder ein fremdes Origin, 413, 415, 429, jeweils mit einem Problem. Ein Tool, das das Token nicht benutzen darf, und ein unbekanntes Tool sind der JSON-RPC-Fehler -32602.

Rich Text und Erwähnungen ​

Schreib Markdown wie über REST: @handle erwähnt eine Person oder einen Bot, die im Projekt Arbeit übernehmen können (people:mentionable nennt sie), ein Key wie WEB-12 wird ein Verweis, wenn das Konto das Item sieht, ![alt](attachment:<id>) zeigt ein hochgeladenes Bild. Die Referenz ist die Resource werkbuch://reference/markdown, derselbe Text wie der Abschnitt Markdown bei Rich Text. Eine Erwähnung aus einem Tool benachrichtigt wie eine aus der Oberfläche; die Erwähnung eines Bots schickt bot.mentioned an seinen Webhook.

Datei hochladen ​

Eine Datei geht nie über ein Argument eines Tools. get-upload-url gibt eine Adresse, an die sie geht:

json
{
  "data": {
    "url": "https://werkbuch.example.com/api/mcp/uploads/01k…?project_id=…&kind=inline&expires=…&signature=…",
    "method": "POST",
    "field": "file",
    "expires_at": "2026-11-07T09:15:00.000000Z",
    "curl": "curl -F 'file=@<path>' 'https://werkbuch.example.com/api/mcp/uploads/01k…'"
  }
}

input.kind ist inline für ein Bild oder eine Datei in einem Text oder file für die Dateiliste von input.work_item_id. Der Agent schickt die Datei mit curl -F 'file=@<path>' '<url>', ohne Bearer-Token; die Antwort ist der Anhang mit seiner id. Eine file steht sofort in der Dateiliste des Items. Ein Upload inline gehört niemandem, bis der Agent ![alt](attachment:<id>) (Bild) oder [name](attachment:<id>) (Datei) in einen Markdown-Text des Projekts schreibt; ab dann besitzt ihn der Text, und ein Upload, den kein Text nimmt, geht nach 24 Stunden.

Die Adresse nennt Projekt, Art und Item in ihrer Signatur und gilt höchstens 15 Minuten, nie länger als ihr Token. Sie darf mehrfach benutzt werden, so kann curl nach einem Abbruch neu ansetzen. Jeder Upload prüft das Token erneut (nicht widerrufen, nicht abgelaufen, Konto aktiv, write und mcp) und die Rechte des Kontos an Projekt und Item, so wie sie beim Upload sind.

Referenzen ​

URIInhalt
werkbuch://reference/filtersFilter als JSON: Felder, Operatoren, Werte (Views)
werkbuch://reference/markdownMarkdown von Rich Text (Rich Text)
werkbuch://reference/field-typesDie Werte jedes Feldtyps einer Property (Typen und Properties)

Jede ist ein Abschnitt der englischen Doku, gelesen, wenn der Client sie erfragt; so laufen Referenz und Doku nie auseinander.

Sicherheit ​

  • Texte sind Daten. Titel, Beschreibungen, Kommentare, Wiki-Seiten und Namen kommen von Menschen. Die Instructions des Servers sagen dem Modell, Aufforderungen darin nicht zu folgen; an den Rechten seines Kontos kommt es über die Tools ohnehin nicht vorbei. Gib einem Agenten ein Token eines Bots mit den Mitgliedschaften, die seine Aufgabe braucht, und nur read und mcp, wenn er nur liest.
  • Der Standard-Bot ist Org-Admin. Ein Token von ihm darf überall alles; gib es nie einem Agenten.
  • Alles, was ein Tool antwortet, landet im Verlauf des Agenten, auch beim Anbieter des Modells. Dazu gehören das Geheimnis eines Webhooks (manage-webhooks:create, manage-webhooks:rotate-secret), der Einladungslink von manage-people:invite, die Adresse von get-upload-url und die Adresse eines Webhooks samt Query (webhooks:get), die ein Token des Empfängers tragen kann. Lege Webhooks und Einladungen über REST oder in der Oberfläche an, wenn das zählt.
  • Jede Änderung ist gezeichnet: Events und History nennen das Konto und via: mcp, so lässt sich die Änderung eines Agenten von der einer Person unterscheiden.

Agent-Szenario ​

Ein Bot als Agent: Ein Org-Admin legt den Bot an, macht ihn zum Mitglied eines Projekts und legt ein Token mit read, write und mcp für ihn an, dazu einen Webhook nur für diesen Bot mit den Ereignissen bot.*.

  1. Jemand weist dem Bot ein Item zu. Der Webhook bot.assigned erreicht den Agenten mit dem Item in data.item.
  2. Der Agent verbindet sich mit seinem Token mit /mcp und ruft whoami: Er erfährt sein Konto und seine Rechte.
  3. work-items:get mit item (dem Key aus dem Webhook) liest das Item, die Beschreibung als Markdown.
  4. Er erledigt die Arbeit und meldet sich mit manage-comments:add (item, input.body in Markdown).
  5. manage-work-items:transition (item, input.to_state_id) zieht das Item weiter; die History zeigt den Bot mit via: mcp.

bot.mentioned weckt den Agenten genauso, wenn jemand @handle des Bots schreibt. Über REST sind dieselben Schritte GET /me, GET /work-items/{item}, POST /work-items/{item}/comments und POST /work-items/{item}/transition.