MCP-Endpoint

Verbinde einen MCP-Client, wenn ein Agent Tale-Tools entdecken, Wissen abrufen oder Automatisierungen entwickeln und ausführen soll. Die Verbindung verwendet denselben API-Schlüssel und Organisationskontext wie REST. Tale ist dabei der Server: Dein externer Client ruft Tale auf.

Beginne mit initialize, prüfe tools/list und rufe vor dem Schreiben einer Automatisierung get_docs auf. Deine Installation liefert ihre unterstützte Grammatik selbst. Der Client muss Knotentypen und Konfigurationsfelder deshalb nicht erraten.

Einen Client verbinden

Die Verbindung vorbereiten

Erstelle einen API-Schlüssel und hinterlege ihn in der sicheren Konfiguration deines Clients. Unter Einstellungen > API > MCP findest du Endpunkt, Organisations-Slug und eine kopierbare Anfrage zur Tool-Erkennung.

Der Client muss entfernte HTTP-Endpunkte mit eigenen Headern unterstützen. Es gibt keinen SSE-Ereignisstrom, keine Sitzung zum Löschen und keinen OAuth-Anmeldeablauf. OAuth-Discovery-URLs antworten mit JSON und 404; ein Client, der diesen Ablauf voraussetzt, braucht eine andere Authentifizierungskonfiguration. Ein reiner stdio-Client kann diese URL nicht direkt nutzen.

Sende in wiederverwendbaren Integrationen immer den Organisations-Header. Er ist nur bei genau einer Mitgliedschaft optional. Ohne ihn führt ein Schlüsselinhaber mit mehreren Organisationen zu 400 ORG_SLUG_REQUIRED. Ein unbekannter Slug liefert 404 ORG_SLUG_INVALID, eine Organisation ohne Mitgliedschaft 403 ORG_FORBIDDEN.

Initialisieren und die Referenz abrufen

Die Beispiele setzen TALE_URL, TALE_API_KEY und TALE_ORG_SLUG in deiner Umgebung voraus. TALE_URL ist die Anwendungsadresse ohne /api/v1.

curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-client","version":"1.0.0"}}}'

Der Server meldet sich als tale-platform. Lies result.protocolVersion und sende den ausgehandelten Wert bei späteren Aufrufen als MCP-Protocol-Version. Das nächste Beispiel verwendet 2025-06-18; passe ihn an, falls die ältere Revision ausgehandelt wurde. Ein nicht unterstützter Headerwert führt zu 400.

curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'MCP-Protocol-Version: 2025-06-18' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_docs","arguments":{}}}'

Bei Erfolg enthält get_docs die Automatisierungsreferenz als Text, ohne gesetztes Fehlerkennzeichen. Mit method: "tools/list" erhältst du stattdessen die Tool-Schemas. Der aktuelle Katalog umfasst 22 Tools. Bewahre die JSON-RPC-id, damit dein Client Antwort und Anfrage zuordnen kann.

Transport und Sammelanfragen

Jeder zusätzliche Tool-Aufruf im Batch verbraucht dasselbe Anfragebudget wie ein eigener Aufruf. Ist das Budget erschöpft, enthält der betroffene Eintrag JSON-RPC -32000 mit data.retryAfterMs. Die HTTP-Antwort bleibt 200 ohne Retry-After. Eine einzelne Anfrage, die bereits am HTTP-Eingang abgelehnt wird, erhält REST 429. Behandle beide Fälle nach der Referenz zu Ratenlimits.

Der Endpunkt liefert keine CORS-Header für API-Schlüssel in Webseiten. Bewahre den Schlüssel auf einem vertrauenswürdigen Server oder im Zugangsdaten-Speicher des MCP-Clients auf.

Die Tools

tools/list liefert das Eingabeschema jedes Tools. Fehlende, falsch typisierte, leere oder unerwartete Argumente führen vor der Ausführung zu JSON-RPC -32602. Das Dokument in validate_automation, run_automation, test_automation oder save_automation hat bewusst eine offene Hülle: get_docs erklärt die Grammatik, die Engine validiert den Inhalt.

Tools liefern außerdem readOnlyHint, destructiveHint, idempotentHint und openWorldHint. Ein Host kann damit einen Aufruf erklären; die Hinweise erteilen aber weder Rechte noch Sicherheitsgarantien. Lesezugriffe sind als solche markiert, Speichern schreibt eine Version, Bereitstellung und Triggeränderungen können Bestehendes ersetzen. Live-Ausführungen können echte Dienste ansprechen.

Automatisierungen entwickeln

Arbeite in dieser Reihenfolge: Grammatik und Katalog lesen, Dokument validieren, mit Mocks ausführen, Akzeptanztests ausführen, Version speichern und dann bereitstellen. Ein erfolgreicher Mock-Test bestätigt den simulierten Ablauf. Er bestätigt keine echten Zugangsdaten, Netzwerkverbindungen oder Auswirkungen beim Anbieter.

Läufe und Trigger verwalten

Beide Tools für bereitgestellte Versionen verwenden denselben dauerhaften Runner mit denselben Berechtigungsprüfungen und Ausführungsdaten. start_run akzeptiert optional projectId. Eine projektgebundene Automatisierung darf nur in einem ihrer Installationsprojekte laufen; bei genau einer Bindung kann dieses automatisch gewählt werden. Ohne Bindungen bedeutet eine fehlende Angabe Organisationskontext. Lies projectIds aus list_automations und die tatsächliche projectId aus dem zurückgegebenen Handle, statt die REST-URL zum Abfragen zu erraten.

Capabilities und Wissen

Das Capability-Verzeichnis enthält derzeit bereitgestellte Automatisierungen. Integrierte Tools, Connector-Aktionen, Skills und externe MCP-Server gehören nicht dazu. Eine bereitgestellte Automatisierung aufzurufen entspricht derselben Live-Operation wie run_deployed. Wenn eine Genehmigung nötig ist, kann der Client anhand von pending erklären, dass zuerst ein Mensch entscheiden muss.

Was der Schlüssel darf

Der Schlüssel identifiziert seinen Inhaber. Er erweitert weder dessen Rolle noch dessen Projektzugriff. Auch eine Live-Ausführung über invoke_capability durchläuft die Ausführungsprüfungen.

Lies vor dem Einrichten privilegierter Tools GET /api/v1/me: capabilities.developer nennt die aktuelle Rollenberechtigung. deploymentEditor gehört dagegen zu einer separaten Freigabeliste des Betreibers und erteilt keine MCP-Bearbeitungsrechte. Tool-Fehler verwenden weiterhin das unten beschriebene MCP-Format; die REST-Berechtigungsabfrage ändert die JSON-RPC-Fehlerbehandlung nicht.

Protokollfehler und abgelehnte Tools unterscheiden

Zu den Tool-Codes gehören AUTOMATION_NOT_FOUND, AUTOMATION_VERSION_UNKNOWN, AUTOMATION_NOT_DEPLOYED, RUN_NOT_FOUND, AUTOMATION_INVALID, AUTOMATION_TESTS_FAILING, LIVE_MODE_UNAVAILABLE und NOT_SUPPORTED. Letzterer bedeutet, dass der Host den Vorgang für Läufe, Versionen oder Trigger nicht unterstützt. start_run lehnt einen wiederverwendeten idempotencyKey mit anderen Argumenten als IDEMPOTENCY_KEY_REUSED ab; invoke_capability lehnt eine ID, die das Register nicht führt — eine nur gespeicherte Automatisierung steht nicht darin —, als CAPABILITY_NOT_FOUND ab und Eingaben, die ihr Schema zurückweist, als CAPABILITY_INPUT_INVALID; get_knowledge reicht die eigenen Codes der Wissens-Tür durch (KNOWLEDGE_UNAVAILABLE, wenn die Suche selbst fehlgeschlagen ist). Plattformfehler behalten ihren eigenen Code, Hinweis und gegebenenfalls Daten; fehlender Entwicklerzugriff liefert etwa FORBIDDEN_DEVELOPER_SETTINGS.

Ein unbekannter Automatisierungsname ist auch bei list_versions, list_runs und list_triggers ein Fehler. Eine leere Liste bedeutet, dass eine vorhandene Automatisierung keine passenden Einträge hat. Ungültige Dokumente für Tools, die ein gültiges Dokument benötigen, fehlgeschlagene Suchen und fehlende Bereitstellungen setzen isError: true. Nur das Validierungstool meldet ein ungültiges Dokument als normales Prüfergebnis.

Wo das hingehört

REST und MCP teilen Schlüssel, Organisationskontext und dauerhafte Ausführungsobjekte. Verwende REST für ausdrückliche HTTP-Routen und MCP für Clients mit Tool-Erkennung und Tool-Aufrufen. Über diesen Endpunkt registriert oder ruft Tale keine externen MCP-Server auf.