Tools

Der MCP-Server hat kein Tool pro Funktion. Über drei allgemeine Tools erreicht ein KI-Client jede Operation der REST-API (Englisch) außer Datei-Uploads, immer in Ihrem Namen und mit Ihren Rechten. Ein viertes Tool gibt Ihr eigenes Profil zurück. Bekommt die API eine neue Funktion, können Clients sie sofort nutzen.

Drei Tools lesen nur. Write to the API ist als Tool gekennzeichnet, das Daten ändern kann, deshalb fragen Clients standardmäßig nach Ihrer Zustimmung. In den meisten Clients können Sie es für ein Gespräch oder dauerhaft erlauben. Rechte und Sicherheit erklärt, was ein Client darf.

Wie ein Client die Tools nutzt

Jeder Client bekommt vom Server außerdem eine kurze Anleitung. Sie beschreibt drei Schritte: die Operation mit search_api finden, lesen, was sie annimmt, und sie dann mit api_read oder api_write aufrufen. Außerdem erfährt der Client daraus, dass:

• Pfade von Arbeitselementen Schlüssel wie ACM-12 akzeptieren
• Benutzerfilter me akzeptieren
• Löschen confirm: true braucht, das erst nach Ihrer Zustimmung gesendet wird, und nur funktioniert, wenn Ihre Organisation es erlaubt
• Text mit mode: append an ein Drive-Dokument angefügt wird, weil sonst das ganze Dokument ersetzt wird

search_api

Findet API-Operationen und beschreibt sie. Das Tool liefert nur die Dokumentation der API, nie Daten aus Ihrer Organisation.

• Mit query liefert es höchstens 12 Treffer als {id, method, path, summary}, dazu einen hint für den nächsten Schritt.
• Mit operation_id beschreibt es diese Operation: ihre Beschreibung, das nötige Recht, Pfadparameter, Query-Parameter, Filter, Sortierungen, Includes, Body-Felder, die Funktion, zu der sie gehört, und ein oder zwei Beispiele. Die ID funktioniert mit und ohne das Präfix api.v2..
• Ohne Eingabe listet es jede Operations-ID auf, nach Bereich gruppiert.

Operationen, die Ihre Organisation nicht nutzen kann, fehlen: die von Bereichen, die Ihre Organisation nicht nutzt, Löschvorgänge, solange Destruktive Aktionen erlauben aus ist, und Datei-Uploads.

api_read

Sendet ein GET an eine beliebige API-Operation.

Pfade und Query

• Ein leerer Pfad listet die Ressourcen auf, die die API anbietet.
• Der Pfad darf mit /api/v2 beginnen; das Präfix wird ignoriert.
• Der ganze Pfad hat höchstens 256 Zeichen. Seine Segmente bestehen nur aus Buchstaben, Ziffern, - und _, und jeder Platzhalter muss ausgefüllt sein.
• Pfade von Arbeitselementen akzeptieren Schlüssel, etwa work-items/ACM-12. Benutzerfilter akzeptieren me.
• Query-Objekte sind höchstens drei Ebenen tief verschachtelt, etwa filter[due_date][gte], mit insgesamt höchstens 60 Parametern.
• Null-Werte werden weggelassen. Listen werden zu kommagetrennten Werten.

Listen und Seiten

Listen kommen in Seiten zu 10 Einträgen in der Ansicht summary zurück, sofern der Aufruf nichts anderes verlangt. Für die nächste Seite wird meta.page.next_cursor der vorherigen Antwort als cursor übergeben. Ist next_cursor gleich null, gibt es keine weiteren Seiten.

Einige Listen akzeptieren auch eine Seitennummer. Ihr meta.page enthält immer current_page und last_page. Beide sind null, solange der Aufruf kein page sendet. Ein Aufruf mit page bekommt immer next_cursor: null. Die letzte Seite ist erreicht, wenn current_page gleich last_page ist.

api_write

Sendet ein POST, PATCH oder DELETE an eine beliebige API-Operation.

Die Pfad- und Query-Regeln von api_read gelten auch hier. Der Body wird genau so geprüft, wie die REST-API ihn prüft: Ein Feld, das die Operation nicht annimmt, wird unter Nennung seines Namens abgelehnt, nie ignoriert.

Löschen braucht zweierlei: Destruktive Aktionen erlauben muss für Ihre Organisation eingeschaltet sein, und der Aufruf muss confirm: true mitsenden. Fehlt eines davon, wird nichts gelöscht. Was als Löschen gilt nennt die Operationen, die das betrifft. Bei DELETE /projects/{project} löscht die Query {"force": true} das Projekt endgültig, statt es so zu löschen, dass es sich wiederherstellen lässt.

Auch das Ersetzen des ganzen Texts eines Drive-Dokuments braucht confirm: true, weil dabei die Formatierung verloren geht und alles, was andere getippt haben, seit der Client das Dokument gelesen hat. Wer nur Text mit {"mode": "append"} im Body anfügt, braucht keine Bestätigung.

api_write lehnt diese Aufrufe ab, bevor irgendetwas ausgeführt wird:

Bei den ersten beiden wird der Datensatz vor der Ablehnung nicht gelesen. Eine Ablehnung verrät also nie, ob es den Datensatz gibt.

Schreibvorgänge über MCP sind nicht gegen Duplikate geschützt. Ein Idempotency-Key ist weder nötig, noch wird er verwendet. Ein Client, der nicht sicher ist, ob ein Schreibvorgang ausgeführt wurde, sollte deshalb erst lesen, bevor er es noch einmal versucht.

Hat die Anmeldung einer App auch Berechtigungen für die REST-API angefordert, ist die App über MCP ebenfalls an diese Berechtigungen gebunden. Berechtigungen aus einer Anmeldung umfassen nie das Löschen, deshalb kann eine solche App über MCP nicht löschen.

get-current-user-tool

Gibt Ihr eigenes Profil zurück. Das Tool nimmt keine Eingabe an.

{
  "id": 34,
  "name": "Jamie Doe",
  "email": "jamie@acme.example",
  "email_verified_at": "2026-02-03T09:15:00+00:00",
  "timezone": "Europe/Amsterdam",
  "locale": "en",
  "job_title": "Project manager",
  "date_employed": "2025-09-01",
  "roles": ["Project manager"],
  "created_at": "2025-08-28T14:02:11+00:00"
}

Die Zeitstempel enthalten einen Zeitzonen-Offset. date_employed ist ein Datum (YYYY-MM-DD). Felder ohne Wert sind null.

Antworten

Eine erfolgreiche Antwort ist der Antwort-Body der API mit zwei Änderungen:

• Zuerst kommt ein Schlüssel status mit dem HTTP-Status, mit dem die API geantwortet hat, zum Beispiel 200 oder 201.
• Jedes links-Objekt wird entfernt. Ein Client setzt eine Liste mit meta.page.next_cursor fort und ruft andere Datensätze über ihren Pfad auf.

Ein Löschen liefert keinen Body, deshalb gibt das Tool {"status": 204} zurück.

Eine Antwort darf etwa 30.000 Zeichen umfassen. Das Limit zählt Bytes, deshalb passt bei Text mit Umlauten, Akzenten oder Emoji etwas weniger hinein. Eine längere Antwort wird gekürzt, aber nie stillschweigend: meta.mcp_truncated sagt, was weggelassen wurde. Fehlen Zeilen einer Liste, wird next_cursor geleert, weil er sie sonst überspringen würde. Der hint erklärt, wie man lückenlos weiterblättert. So sieht das meta-Objekt einer gekürzten Liste aus:

{
  "page": {
    "per_page": 10,
    "next_cursor": null,
    "prev_cursor": null,
    "total": null
  },
  "mcp_truncated": {
    "reason": "response_budget",
    "returned": 6,
    "omitted": 4,
    "hint": "Only the first 6 of 10 rows fit. Repeat this request with per_page=6 (and the same cursor, if any) to page through without gaps."
  }
}

Ist ein einzelner langer Text das Problem, listet mcp_truncated stattdessen die gekürzten Felder auf, jeweils mit ihrem pointer, der Zahl der behaltenen Zeichen (kept) und der ursprünglichen Länge (length).

Fehler

Ein abgelehnter Aufruf kommt als Tool-Fehler zurück. Er enthält dasselbe Fehlerdokument (problem+json, Englisch), das die REST-API liefert, mit demselben Status und Typ. Fragen Sie etwas ab, das Sie nicht sehen dürfen, kommt ein 404 zurück, genau wie über HTTP.

{
  "type": "https://developers.plnnrly.com/api/v2/problems/forbidden-by-policy",
  "title": "Forbidden by policy",
  "status": 403,
  "detail": "This organisation does not allow AI clients to delete data. An administrator can turn on Allow destructive actions under Settings › Administration › MCP & API.",
  "instance": "/api/v2/work-items/ACM-12",
  "request_id": "01M4WVYY50K7T2B9QH3D6N8RXP"
}

Auf einen Pfad oder eine Query, mit denen die Tools nichts anfangen können, kommt malformed-request zurück. Dessen errors[].code ist invalid (ein Pfad oder Wert, der nicht erlaubt ist), too_many (mehr als 60 Query-Parameter) oder too_deep (mehr als drei Ebenen verschachtelt).

Limits

• Jeder Benutzer darf 60 MCP-Anfragen pro Minute senden. Gezählt wird jede Anfrage, die der Client an den Server sendet, auch die zum Aufbau der Verbindung und zum Auflisten der Tools, nicht nur Tool-Aufrufe. Ein Client über dem Limit bekommt 429.
• Die Rate-Limits und Rate-Einheiten der REST-API gelten nicht für Aufrufe über MCP.
• Eine Antwort umfasst höchstens etwa 30.000 Zeichen.
• Der Client erneuert seine Anmeldung jede Stunde. Ein Client, der 30 Tage lang nicht benutzt wurde, muss sich erneut anmelden.

Limits im Überblick (Englisch) listet jedes Limit der REST-API auf.

Was MCP nicht kann

• Dateien hochladen. Für einen Anhang oder eine Drive-Datei ist ein Byte-Upload nötig, den MCP-Clients nicht ausführen können. Nutzen Sie die REST-API mit einem API-Token; siehe Dateien hoch- und herunterladen (Englisch).
• Löschen, solange der Schalter aus ist. Löschen funktioniert nur, solange Ihre Organisation destruktive Aktionen erlaubt.

Siehe auch

• Was Sie fragen können
• Rechte und Sicherheit
• Fehlerbehebung
• Fehler und Wiederholungen (Englisch)