Tecto docs
tectoapp.io

MCP-Server

Tecto bringt einen hauseigenen MCP-Server mit. Damit kann ein Assistent (Claude, eine Agenten-CLI, alles, was das Protokoll spricht) die Boards eines Workspace lesen und bewegen, ohne dass jemand Klebecode schreiben muss.

Es gibt nichts zu installieren. Der Server läuft auf Ihrer Tecto-Instanz und antwortet unter https://app.tectoapp.io/mcp; Sie richten den Assistenten auf diese Adresse und geben ihm ein Token.

Er ist eine dünne Schicht über der öffentlichen API: Der Endpunkt hat keine eigene Rechtelogik, sondern stellt gewöhnliche API-Anfragen mit Ihrem Zugangsdatum. Ein Assistent sieht und ändert damit genau das, was Sie können. Karteninhalte gehen als kanonisches Markdown über die Leitung.

Einrichtung

Zuerst ein Token anlegen: Einstellungen → Tokens, im Workspace, in dem der Assistent arbeiten soll. content:read, wenn er nur lesen soll, content:write, wenn er auch schreiben soll. Das Geheimnis wird einmal angezeigt.

Ein hier erstelltes Token gilt hier: Es liest und schreibt, was Tecto Ihnen zeigt, und nichts, was in den anderen Apps liegt. Deshalb müssen Sie dem Assistenten auch nicht sagen, welchen Workspace er nehmen soll: Das Token nennt einen, und der Endpunkt liest ihn dort ab.

In der Konfigurationsdatei eines MCP-Hosts:

{
  "mcpServers": {
    "tecto": {
      "type": "http",
      "url": "https://app.tectoapp.io/mcp",
      "headers": {
        "Authorization": "Bearer tecto_pat_…"
      }
    }
  }
}

Die Hosts schreiben das unterschiedlich; gebraucht werden überall dieselben zwei Dinge: die Adresse und der Authorization-Header. In Claude Code etwa:

claude mcp add --transport http tecto https://app.tectoapp.io/mcp \
  --header "Authorization: Bearer tecto_pat_…"

Wenn Ihr Konto in mehreren Workspaces ist und Sie einen ausdrücklich nennen möchten, verwenden Sie stattdessen https://app.tectoapp.io/mcp/w/<Workspace-ID>. Ein Token kann immer nur seinen eigenen Workspace nennen, die beiden müssen also übereinstimmen.

Dass ein Assistent nur liest, regelt das Token und keine Einstellung: Ein content:read-Token weist der Server bei jedem Schreibvorgang ab, und das ist eine härtere Zusicherung als ein Schalter auf der Clientseite.

Als Connector hinzufügen

Hosts ohne Header-Feld (dazu gehört claude.ai) fügen den Endpunkt als Connector hinzu und melden Sie stattdessen an. Tragen Sie dieselbe Adresse https://app.tectoapp.io/mcp in den Connector-Dialog ein; der Rest ist eine Anmeldung und ein Bildschirm mit der Frage, ob Sie verbinden möchten. Nichts zu kopieren, kein Token, das Sie aufbewahren müssen.

Ein Connector reicht weiter als ein Token, und der Bildschirm sagt das, bevor Sie zustimmen:

  • Er gilt für jeden Workspace, in dem Sie Mitglied sind, nicht für einen.
  • Er liest und schreibt, was Sie können. Einen nur lesenden Connector gibt es nicht; für einen Assistenten, der nur schauen soll, erstellen Sie ein Token mit content:read.
  • Er sieht weiterhin nur Tecto, und er hört auf zu funktionieren, wenn Ihr Zugriff endet.

Weil ein Connector mehrere Workspaces umfasst, sagt der Assistent bei jedem Aufruf, welchen er meint. Er bekommt ein zusätzliches Werkzeug, list_workspaces, und jedes andere Werkzeug verlangt die ID eines Workspace als workspace, ohne Vorgabe: Weiß der Assistent nicht, welchen Sie meinen, fragt er nach. Jede Antwort außer der Liste beginnt mit dem Workspace, in dem er gehandelt hat. Soll ein Connector in einem Workspace bleiben, fügen Sie stattdessen https://app.tectoapp.io/mcp/w/<Workspace-ID> hinzu.

Was der Assistent bekommt

Nur lesend, sofern nicht markiert.

  • get_workspace: Name und Zuschnitt des Workspace, den das Token öffnet.
  • list_boards / get_board: die Boards, und Titel, Icon, Spalten und Lanes eines Boards, mit der configVersion, die die Strukturwerkzeuge brauchen.
  • get_board_cards: die Karten eines Boards, gruppiert nach Spalte × Lane, mit ehrlichen Gesamtzahlen und Cursorn je Gruppe für lange Spalten. Mit filters (Feldschlüssel, eq, ne, contains, is_empty oder is_not_empty, oder gt, gte, lt, lte bei einer Zahl oder einem Datum, und ein Wert wie der Name einer Option) und match (all oder any) kommen nur die passenden Karten, und die Gesamtzahlen zählen nur diese. Archivierte Karten fehlen und werden nur gezählt; archived (include oder only) liefert sie mit. Jede Karte trägt ihre number, die Nummer #42 aus der App.
  • get_my_work - als wer das Token handelt (eine Person, oder ein Bot und wessen Bot), die Karten, in deren Personen-Feldern es steht, mit Board, Spalte und Lane, und seine ungelesenen Erwähnungen.
  • create_board (schreibend): ein neues Board in einer Sammlung, mit den Standardspalten, die auch die App anlegen würde, und auf Wunsch mit Lanes.
  • update_board (schreibend): ein Board umbenennen, sein Icon setzen oder entfernen.
  • update_board_columns / update_board_lanes (schreibend): Spalten oder Lanes in einem Schritt anlegen, umbenennen, sortieren und entfernen. Die configVersion aus get_board schützt den Schreibvorgang: Hat sich das Board inzwischen geändert, wird nichts geschrieben. Eine Spalte oder Lane, auf der noch Karten liegen, lässt sich nur entfernen, wenn der Aufruf sagt, wohin die Karten sollen (moveCardsTo), oder ausdrücklich in Kauf nimmt, dass sie ihren Platz verlieren (unplaceCards). Kartenseiten werden nie gelöscht. Ein Name, den schon eine andere Spalte bzw. Lane des Boards trägt, wird abgelehnt, ebenso eine Lane mit dem Namen der Zeile ohne Lane; create_board prüft seine Namen, bevor das Board entsteht.
  • add_card (schreibend): eine neue Karte am Spaltenende, oder eine bestehende Seite als Karte angeheftet.
  • move_card (schreibend): Spalte, Lane und Position in einem Schritt, derselbe transaktionale Move wie in der App.
  • archive_card (schreibend) - eine Karte auf einem Board archivieren oder mit archived: false aus dem Archiv holen. Die Karte behält Spalte, Lane und Position. Mit allBoards wird sie auch auf allen anderen Boards archiviert, auf denen sie liegt und die der Token bearbeiten darf; aus dem Archiv geholt wird sie nur auf dem einen Board.
  • get_card / update_card (schreibend): der Karteninhalt als kanonisches Markdown, gelesen und im Ganzen ersetzt. get_card nimmt die Seiten-ID oder die Kartennummer (42 für #42) und nennt die Nummer im Kopf. Eine im Inhalt angeheftete andere Karte ist ein basalt-card-Block, wie im Board-Text. Text, den das Schreiben nicht ändert, behält seine Kommentare; nur ein Kommentar an Text, den das Schreiben löscht, verliert seinen Bezug.
  • list_automations / list_automation_runs - die Automationen eines Boards mit Zeitplan, Kartenvorlage, Ziel-Spalte und Lane, Status und nächstem Lauf, und was jede Regel zuletzt getan hat.
  • create_automation / update_automation (schreibend) - eine Regel, die nach Zeitplan (täglich, wöchentlich oder monatlich, zu einer Uhrzeit in einer Zeitzone) eine Karte aus einer Vorlage anlegt. update_automation pausiert und setzt eine Regel fort und ändert einzelne Teile ihrer Vorlage.
  • run_automation (schreibend) - eine Regel jetzt einmal auslösen. Die Antwort sagt, ob sie eine Karte angelegt hat, übersprungen wurde (die vorige Karte ist nicht erledigt) oder sich selbst pausiert hat (ihre Spalte fehlt).
  • delete_automation (schreibend) - eine Regel löschen; ihre Karten bleiben.
  • get_board_text / update_board_text (schreibend): der Text „Über dieses Board" als kanonisches Markdown, gelesen und im Ganzen ersetzt, mit derselben Versionsprüfung wie bei Karten. Eine im Text angeheftete Karte ist ein basalt-card-Block und bleibt angeheftet, solange der Block bleibt.
  • comment_on_card (schreibend) / list_card_comments: die Diskussion der Karte.
  • ask_on_card (schreibend) / list_card_questions / withdraw_question (schreibend): eine Rückfrage mit zwei bis sechs Optionen, die jemand auf der Karte mit einem Klick beantwortet (siehe Rückfragen an einer Karte). Eine Option kann die Karte in eine Spalte verschieben. get_card nennt die offenen Rückfragen der Karte nach dem Text, get_my_work die Antworten auf die eigenen Rückfragen der letzten 14 Tage. Beantwortet wird in der App, nicht vom Assistenten.
  • list_card_chat / reply_in_card_chat (schreibend): der Chat einer Karte mit ihrem Agenten (siehe Chat mit dem Agenten einer Karte). Nur der Agent der Karte antwortet, auf eine wartende Nachricht mit ihrer Id, oder sagt mit failed, dass er es nicht konnte. get_my_work nennt die Nachrichten, die auf Sie warten.
  • prepare_attachment_upload (schreibend): eine Adresse für genau einen Upload (15 Minuten gültig, bis 25 MiB), um eine Datei wie einen Screenshot oder ein kurzes Video an eine Karte zu hängen. Der Assistent schickt die Datei per HTTP-PUT dorthin (curl --fail -T shot.png "<Adresse>") und bekommt das Markdown zurück, das sie einbettet; das fügt er selbst mit update_card in die Karte ein. Bilder erscheinen direkt, andere Dateien als Link.
  • search: Volltext über den Workspace; jeder Treffer sagt, was er ist.

Einem Assistenten eine eigene Identität geben

Ein Assistent, der mit Ihrem Token arbeitet, handelt als Sie: Seine Kommentare und Änderungen tragen Ihren Namen, und er kann die Karten, die für ihn gedacht sind, nicht von Ihren unterscheiden. Ein Bot löst beides. Legen Sie ihn unter Einstellungen → Tokens → Bots an, erstellen Sie dort ein Token für den Bot und geben Sie dem Assistenten dieses Token statt Ihres.

  • Bei allem, was der Bot tut, steht sein Name mit „(Bot, gehört …)". Ein Profilbild bekommt er unter Einstellungen → Tokens → Bots mit Bild hochladen….
  • Ein Bot ist ein Mitglied wie jedes andere: Tragen Sie ihn in ein Personen-Feld ein oder erwähnen Sie ihn, um ihm eine Karte zu geben. Mit get_my_work findet er, was ihm gegeben wurde.
  • Ein Bot hat nie mehr Rechte als die Person, der er gehört, und belegt keinen Platz im Tarif. Verlässt diese Person den Workspace, funktionieren seine Tokens nicht mehr.

Was der Assistent nicht darf, durfte auch das Token nicht: Rechte, Sichtbarkeit und Papierkorb-Semantik gehören dem Server, nicht der MCP-Schicht.

Wenn etwas abgelehnt wird

Der Endpunkt antwortet wie die API, eine Ablehnung sagt also, welcher der drei Fälle vorliegt:

  • 401: kein Zugangsdatum, oder eines, das unbekannt, widerrufen oder abgelaufen ist.
  • 403: ein Zugangsdatum, das das nicht darf: ein Token ganz ohne content:read, ein content:read-Token, das schreiben soll, oder eines, das zu einem anderen Workspace gehört als dem, den die Adresse nennt.
  • Alles andere ist die gewöhnliche Antwort der API, mit ihrem eigenen Wortlaut durchgereicht.