MCP-Werkzeugkatalog¶

Expecto stellt seinen vollen Funktionsumfang als MCP-Server bereit, sodass ein KI-Assistent (Claude Desktop, Claude Code, Cursor oder ein eigener Client) die Plattform direkt steuern kann: Lieferanten onboarden, Verträge und Transformer aufbauen, Sessions ausführen und Ergebnisse prüfen. Diese Seite listet alle verfügbaren Werkzeuge, nach Domäne gruppiert.

Verbindung und Authentifizierung beschreibt der Entwickler-Quickstart (Abschnitt „Derselbe Ablauf über MCP"). Kurz gesagt: Richten Sie Ihren Client auf <EXPECTO_BASE_URL>/mcp/ und authentifizieren Sie sich mit demselben X-API-Key-Header wie bei der REST-API.

Den Katalog lesen

Die Beschreibungen unten sind Einzeiler. Ihr MCP-Client legt das vollständige Eingabeschema jedes Werkzeugs (Parameternamen, Typen, Pflichtfelder) per Introspektion offen — die meisten Clients zeigen es beim Inspizieren oder Aufrufen eines Werkzeugs an. Die Parameter in Klammern sind die Eingaben, die ein Werkzeug akzeptiert; welche davon Pflicht sind, hängt vom Werkzeug ab. Die entsprechende REST-Oberfläche ist interaktiv unter <EXPECTO_BASE_URL>/api/docs dokumentiert.

Alle Werkzeuge sind auf die Organisation hinter Ihrem API-Schlüssel beschränkt. Werkzeuge, die den Zustand verändern (create_*, update_*, delete_*, run_*, approve_*, …), erfordern die entsprechende Berechtigung des Schlüssels.

Identität & Health¶

Werkzeug	Zweck
`get_identity`	Liefert Principal, Organisation und effektive Berechtigungen hinter dem API-Schlüssel.
`health`	Prüft Status und Version des MCP-Servers.

Projekte¶

Werkzeug	Zweck
`list_projects`	Projekte der Organisation auflisten (optionale Suche).
`get_project`	Vollständige Projektdetails: Entities, Kataloge, Datenverträge, Empfänger und `context_schema` (erforderliche Session-Context-Skalare/-Tabellen, die vor dem Pipeline-Lauf gesetzt werden müssen).
`get_project_instructions`	Betriebsanweisungen eines Projekts lesen (Markdown).
`create_project`	Ein Projekt anlegen (Delivery Standard); optional das Export-`output_format` setzen.
`update_project`	Projekteinstellungen ändern (Freigabemodus, Session-Erstellungsmodus, Blocking-Schwere, Export-`output_format`).
`set_project_context_schema`	Das Session-Kontextschema des Projekts ersetzen (Skalare + Tabellen, je mit `required` / `filled_by`). Vorher mit `get_project` lesen, zusammenführen und das gesamte Ergebnis übergeben; integrationsbefüllte Felder mit `filled_by: "integration"` markieren.
`update_project_instructions`	Betriebsanweisungen eines Projekts ersetzen.
`delete_project`	Ein Projekt und alle zugehörigen Ressourcen löschen.
`attach_entity_to_project`	Eine bestehende Entity unter einer semantischen Rolle anhängen.
`detach_entity_from_project`	Eine Entity anhand ihres Rollennamens lösen.
`attach_catalog_to_project`	Einen Katalog auf Organisationsebene an ein Projekt anhängen.
`detach_catalog_from_project`	Einen Katalog auf Organisationsebene vom Projekt lösen.

Entities¶

Zielschemata samt zeilenbasierten Validierungsregeln.

Werkzeug	Zweck
`list_entities`	Entities (Zielschemata) der Organisation auflisten.
`get_entity`	Entity-Details inklusive Schema und Validierungsregeln.
`create_entity`	Eine neue Entity anlegen (organisations- oder projektbezogen).
`update_entity`	Name oder Beschreibung einer Entity ändern.
`delete_entity`	Eine Entity samt Schema/Regeln löschen.
`set_entity_schema`	Das JSON-Schema einer Entity anlegen oder ersetzen.
`get_entity_schema`	Die JSON-Schema-Definition einer Entity abrufen.
`create_entity_rule`	Eine Validierungsregel auf einer Entity anlegen. `message` akzeptiert einen String oder ein mehrsprachiges Objekt (`{"en": …, "de": …, "ru": …}`, `"en"` erforderlich).
`update_entity_rule`	Eine bestehende Validierungsregel ändern. `message` akzeptiert einen String oder ein mehrsprachiges Objekt.
`delete_entity_rule`	Eine Validierungsregel von einer Entity löschen.

Datenverträge¶

Format-Vereinbarungen mit Lieferanten und ihre unveränderlichen Revisionen.

Werkzeug	Zweck
`list_data_contracts`	Datenverträge auflisten (Format-Vereinbarungen mit Lieferanten).
`get_data_contract`	Vertragsdetails inklusive Revisionen und Quellen.
`create_data_contract`	Einen neuen Datenvertrag anlegen (optional mit eigener `external_id`, eindeutig pro Organisation).
`add_source_to_contract`	Eine Quelle (Rolle + Typ + Parsing-Konfiguration) zu einer Revision hinzufügen.
`create_revision`	Eine neue Entwurfs-Revision auf einem bestehenden Vertrag anlegen.
`activate_revision`	Eine Entwurfs-Revision aktivieren (mit `valid_from`-Periode).
`update_data_contract`	Name, Beschreibung oder `external_id` eines Vertrags ändern (leerer String löscht den Wert; nutzbar in der v1-Session-Erstellung als `data_contract: {"external_id": …}`).
`delete_data_contract`	Einen Vertrag samt allen Revisionen/Quellen löschen.

Transformer¶

Feld-Mappings von den Quellen eines Vertrags auf das Zielschema einer Entity.

Werkzeug	Zweck
`list_transformers`	Transformer eines Datenvertrags auflisten.
`get_transformer`	Ein Transformer mit allen Feld-Mappings.
`create_transformer`	Einen Transformer anlegen (Mappings vom Vertrag zur Entity; optionale rollenbezogene Zeilenfilter).
`update_transformer_mappings`	Die Feld-Mappings eines Transformers ersetzen, optional auch die Zeilenfilter.
`validate_transformer_expressions`	Alle Mapping-Ausdrücke (und Zeilenfilter) eines Transformers validieren.
`preview_transformer_sql`	Das kompilierte DuckDB-SQL eines Transformers anzeigen.
`delete_transformer`	Einen Transformer aus einem Datenvertrag löschen.

Zeilenfilter (row_filters_json). create_transformer und update_transformer_mappings akzeptieren optional eine Map {Rolle: Prädikat}. Jedes Prädikat ist ein boolescher DuckDB-SQL-Ausdruck; Eingabezeilen, für die er false ergibt, werden vor dem Mapping verworfen und erreichen weder die Entity-Daten noch Validierung, Abstimmung oder das Export-Paket. Damit lassen sich z. B. explizit nicht gemappte Konten aus der SAP-Ausgabe ausschließen, etwa {"postings": "\"Konto\" NOT IN (SELECT \"code\" FROM cat_kontenplan__provider WHERE \"mapping_type\" = 'ignore')"}. Beim Update lässt ein weggelassenes row_filters_json bestehende Filter unverändert; {} löscht sie. Die Anzahl verworfener Zeilen steht in der Transform-Zusammenfassung.

Kataloge¶

Referenzdatensätze (Kontenpläne, Code-Tabellen, Ausschlusslisten). Ein Katalog ist auf die Organisation, ein Projekt oder — über data_provider_id — einen einzelnen Lieferanten beschränkt.

Werkzeug	Zweck
`list_catalogs`	Kataloge auflisten. Filtern nach `project_id` oder nach `data_provider_id` für lieferantenbezogene Kataloge.
`get_catalog_data`	Spalten und Zeilen eines Katalogs lesen (paginiert).
`create_catalog`	Einen Katalog anlegen — organisationsweit, projektbezogen (`project_id`) oder lieferantenbezogen (`data_provider_id`).
`update_catalog`	Name oder Beschreibung eines Katalogs ändern.
`delete_catalog`	Einen Katalog samt Daten löschen.
`import_catalog_data`	CSV/Excel in einen Katalog importieren (ersetzt bestehende Daten).
`add_catalog_column`	Eine Spalte (mit Standardwert) anhängen, ohne neu zu importieren — bestehende Zeilen bleiben erhalten.
`edit_catalog_cell`	Eine einzelne Zelle per Zeilenindex setzen, z. B. `mapping_type = 'ignore'` für ein Konto.

Datenlieferanten¶

Lieferanten, die Daten einreichen. Ein Lieferant erhält Zugriff auf ein Projekt, kann Mitglieds-Benutzerkonten haben und lieferantenbezogene Kataloge besitzen.

Werkzeug	Zweck
`list_data_providers`	Lieferanten (Data Provider) auflisten. Die zurückgegebene `id` dient als `data_provider_id` für lieferantenbezogene Kataloge.
`get_data_provider`	Details eines einzelnen Lieferanten anhand der id.
`create_data_provider`	Lieferant anlegen (`name`, optional `external_id`, `language` en/de/ru).
`update_data_provider`	Umbenennen, `external_id` ändern, Nachrichten-`language` (en/de/ru) oder `is_active` setzen.
`deactivate_data_provider`	Lieferant deaktivieren (Soft Delete — `is_active = false`).
`list_provider_members`	Die einem Lieferanten zugeordneten Benutzerkonten auflisten.
`add_provider_member`	Benutzer per `user_id` oder `email` mit einer `role` (`contributor` / `manager`) zuordnen; eine unbekannte E-Mail wird automatisch in die Organisation aufgenommen.
`remove_provider_member`	Mitglied entfernen (per Mitglieds-id).
`list_provider_access`	Projektzugriffe eines Lieferanten auflisten.
`grant_provider_access`	Zugriff auf ein `project_id` gewähren (optional auf ein `data_contract_id` eingeschränkt).
`revoke_provider_access`	Einen Zugriff entziehen (per Zugriffs-id).

Integrationen, Kontextquellen & ausgehende Bindungen¶

Verbindungen zu externen Systemen und die Projektkonfiguration darum herum. Der Adapter einer Verbindung deklariert Fähigkeiten: context (automatisches Befüllen des Session-Kontexts — BuiltAPI, PostgreSQL) und/oder outbound (Schreiben von Session-Ereignissen in die externe Plattform — Salesforce). Kontextquellen lassen den Aufrufer nur Abfrageparameter senden (z. B. Periode, Fondsnummer) — den Rest holt Expecto bei der Session-Erstellung selbst; ausgehende Bindungen übertragen Prüfergebnisse nach Abschluss eines Laufs.

Tool	Zweck
`list_connection_types`	Katalog der unterstützten Verbindungstypen: jeder Eintrag enthält die `capabilities` des Typs (`context` / `outbound`) und die Formular-Metadaten zum Anlegen einer Verbindung dieses Typs — base_url-Form, Credential-Form (einzelnes Token oder strukturierte Felder) und Config-Felder mit Pflicht-Markierung. Vor `create_integration_connection` aufrufen.
`create_integration_connection`	Org-weite Verbindung anlegen (`name`, `type` = `builtapi`, `postgres` oder `salesforce`, `base_url` — eine API-URL, ein `postgresql://`-DSN oder die My-Domain-Instanz-URL von Salesforce, `config_json` — `workspace_id` bei BuiltAPI, `api_version` bei Salesforce, nur schreibbares `credentials` — ein Token-String oder `{client_id, client_secret}` für OAuth-Typen).
`list_integration_connections`	Verbindungen auflisten; Antworten enthalten `capabilities` (`context` / `outbound`) und `has_credentials`, nie das Geheimnis.
`update_integration_connection`	Umbenennen, Konfiguration ändern, Token rotieren (`credentials`) oder löschen (`clear_credentials`), `is_active` umschalten.
`test_integration_connection`	Gespeicherte Verbindung (`connection_id`, hinterlegte Zugangsdaten) oder ungespeicherte Angaben mit einem günstigen authentifizierten Aufruf prüfen; liefert `{ok, error_kind, message}`.
`delete_integration_connection`	Verbindung löschen; abgelehnt, solange Kontextquellen oder ausgehende Bindungen eines Projekts sie referenzieren.
`set_project_context_sources`	Deklarieren, was geholt wird: Quellen mit BuiltAPI-Abfrage — `records_search` (Filter + Projektion) oder `aggregation` (Mongo-Pipeline mit `$lookup`) — oder PostgreSQL-`sql`-Abfrage (einzelnes read-only `SELECT`); `{{ context.* }}` / `{{ session.* }}`-Platzhalter — und der Kontexttabelle bzw. dem Skalar, den jede Quelle befüllt. BuiltAPI-Abfragen werden automatisch paginiert und holen alle Zeilen; das optionale `take` ist ein Gesamtzeilenlimit (1–100 000), keine Seitengröße. Ohne `take` schlägt ein Ergebnis über 100 000 Zeilen mit einem expliziten Fehler fehl, statt stillschweigend abgeschnitten zu werden.
`get_project_context_sources`	Kontextquellen-Konfiguration des Projekts lesen.
`test_context_source`	Abfrage einer Quelle mit Beispielwerten für Platzhalter probeweise ausführen; liefert eine Vorschau (Zeilenanzahl, Spalten, erste Zeilen) oder einen semantischen Fehler, ohne eine Session anzulegen.
`fetch_session_context`	Automatischen Kontextabruf einer Session erneut ausführen (bis zur Bestätigung erlaubt); Ergebnis steht im `context_fetch_report`.
`set_project_outbound_bindings`	Deklarieren, welche Session-Ereignisse wohin geschrieben werden: Bindungen mit einer outbound-fähigen Verbindung, `events` (z. B. `session.checked`, `session.failed`) und adapterspezifischem `mapping` — für Salesforce: `sobject` + `fields` mit `{{ … }}`-Vorlagen über Envelope-Felder (`session_id`, `run_id`, `health`, …) und `{{ context.* }}`.
`get_project_outbound_bindings`	Ausgehende Bindungen des Projekts lesen.

Integrationsbefüllte Felder im Kontextschema des Projekts mit filled_by: "integration" markieren, damit Aufrufer sie nicht liefern müssen; ein ausstehender oder fehlgeschlagener Abruf blockiert die Pipeline vor dem Parse mit verständlichen Gründen je Quelle.

Die Anleitungen je Plattform (Einrichtung auf Salesforce-Seite, Abfragearten, Limits, Fehlersemantik) stehen im Abschnitt Integrationen.

Webhooks¶

Ausgehende Webhooks für Session-Lifecycle-Ereignisse (Standard Webhooks-konform). Endpunkte sind org- oder projektbezogen; Signaturgeheimnisse werden einmalig angezeigt und Fernet-verschlüsselt gespeichert.

Tool	Zweck
`list_webhook_endpoints`	Webhook-Endpunkte der Organisation auflisten.
`get_webhook_endpoint`	Details eines Endpunkts per id.
`create_webhook_endpoint`	Endpunkt anlegen (`url`, `event_types`, optional `project_id`, optional Auth-Header). Secret nur mit `reveal_secret=true`.
`update_webhook_endpoint`	URL, Ereignistypen, Aktiv-Status oder Auth-Header ändern.
`delete_webhook_endpoint`	Endpunkt und seine Zustellungen löschen.
`rotate_webhook_secret`	Signaturgeheimnis rotieren (mit `reveal_secret=true` einmalig sichtbar).
`send_webhook_ping`	Synthetisches `webhook.ping` zur Verbindungsprüfung senden.
`list_webhook_deliveries`	Zustellversuche auflisten — eines Endpunkts, einer Verbindung (`connection_id`) oder der ganzen Organisation; Bindungs-Zustellungen tragen `connection_id` / `project_id` / `binding_name`, eine erfolgreiche speichert die Referenz des angelegten Datensatzes.
`get_webhook_delivery`	Details einer Zustellung inkl. Auszug der letzten Antwort.
`replay_webhook_delivery`	Eine frühere Zustellung erneut senden — Endpunkt-Zustellungen mit dem ursprünglich signierten Body, Bindungs-Zustellungen über den Adapter.

Geschäftsregeln¶

Entitätsübergreifende Abstimmung und Prüfungen auf Projektebene (DuckDB-SQL / Ausdruck).

Werkzeug	Zweck
`list_business_rules`	Geschäftsregeln eines Projekts auflisten.
`get_business_rule`	Eine bestimmte Geschäftsregel mit allen Details.
`create_business_rule`	Eine Geschäftsregel anlegen (optional über `applicable_when_sources` gesteuert). `message` akzeptiert einen String oder ein mehrsprachiges Objekt (`{"en": …, "de": …, "ru": …}`, `"en"` erforderlich).
`update_business_rule`	Eine Geschäftsregel ändern. `message` akzeptiert einen String oder ein mehrsprachiges Objekt.
`delete_business_rule`	Eine Geschäftsregel aus einem Projekt löschen.

Sessions¶

Ein Liefervorgang: Dateien → Parsen → Transformieren → Validieren → Prüfen → Bestätigen → Freigeben → Export.

Werkzeug	Zweck
`list_sessions`	Sessions auflisten (Filter nach Projekt, Status, Health, Suche).
`get_session`	Session-Details: Dateien (mit `parse_validation_summary` pro Datei), Transformer, Pipeline-Status sowie `context_validation_errors` und `file_validation_errors`.
`create_session`	Eine Liefer-Session für Vertrag + Periode (+ Lieferant) anlegen.
`upload_session_file`	Eine Datei zu einer Quellrolle hochladen.
`run_session_pipeline`	Die vollständige Pipeline ausführen (Parsen → Transformieren → Validieren → Prüfen); liefert `job_id` (zum Statusabruf) und `run_id` — die stabile ID des angelegten Laufs (einer pro Ausführung, siehe `GET /sessions/{id}/runs`). Bei fehlgeschlagenem Pre-Flight-Gate werden `error` + `details` mit den fehlenden Kontextfeldern oder Quelldateien zurückgegeben. Eine Session mit `health=blocked` kann erneut gestartet werden (jeder Aufruf legt einen neuen Lauf an; `blocked` bleibt, bis der neue Lauf sauber durchläuft). Läuft der automatische Kontextabruf noch, wird sofort geparst (das technische Ergebnis wartet nicht auf den Kontext) und der Lauf wartet dann vor der Transformation — `get_job_status` zeigt `run_status = waiting`, `waiting_for = context_fetch` — und läuft von selbst weiter, sobald der Abruf abgeschlossen ist (gleiche `run_id` / `job_id`); ein fehlgeschlagener Abruf oder ein Warten über das Timeout hinaus schließt ihn als `errors`.
`set_session_context`	Session-Kontextwerte setzen (Skalare und Tabellen).
`get_session_parse_issues`	Parse-Validierungsfehler einer hochgeladenen Datei: `summary`-Zähler, `groups` nach (Prüfung, Spalte) mit Anzahl, Formathinweisen und Beispielzeilen sowie eine paginierte Rohliste `issues`. Einziger Weg, die vollständigen Parse-Fehler zu lesen — `get_session` liefert nur die Zusammenfassung.
`get_session_violations`	Validierungsverletzungen eines Session-Transformers.
`get_session_check_violations`	Verletzungen einer bestimmten Geschäftsregel-Prüfung.
`confirm_session`	Eine geprüfte Session bestätigen (vom Einreicher geprüft).
`approve_session`	Eine bestätigte Session freigeben (finale Freigabe vor Export).
`reject_session`	Eine bestätigte Session ablehnen und zur Korrektur zurücksenden.
`export_session`	Das Ausgabepaket einer Session als verfolgbaren Job exportieren; das Projekt muss ein Ausgabeformat konfiguriert haben.
`add_session_comment`	Einen Kommentar zu einer Session hinzufügen.
`list_session_comments`	Die Kommentare einer Session chronologisch auflisten.

Jobs¶

Asynchrone Arbeit (Pipeline-Läufe, Exporte, Importe) wird als Jobs verfolgt.

Werkzeug	Zweck
`get_job_status`	Status eines asynchronen Jobs (Pipeline-Lauf, Export, Import). Bei einem Pipeline-Job zusätzlich `run_id`, `run_status` und `waiting_for` (`context_fetch`, solange der Lauf auf den Kontextabruf wartet).
`list_jobs`	Aktuelle asynchrone Jobs der Organisation.