Crevio

npx add-mcp 'https://mcp.crevio.co/mcp'

MCP-Server

Verbinde Claude, Cursor oder einen beliebigen MCP-kompatiblen Agenten mit deinem Crevio-Konto: Delegiere Arbeit mit ask_crevio an den Crevio-Agenten, verfolge und setze Runs fort und führe Skripte gegen die gesamte Crevio-API und deine Integrationen aus.

Der Crevio-MCP-Server ermöglicht jedem MCP-kompatiblen Agenten, Arbeit an Crevio zu delegieren – und, wenn er die Steuerung selbst übernehmen möchte, Skripte gegen die gesamte Crevio-API und deine Integrationen auszuführen. Ein Server, zwei Oberflächen:

• Delegation — ask_crevio übergibt dem Crevio-Agenten eine Aufgabe in einfacher Sprache („erstatte die letzte Bestellung von jane@…", „schreibe und plane die Beiträge dieser Woche") und liefert das Ergebnis zurück. Längere Aufgaben laufen im Hintergrund; du verfolgst sie als Runs, setzt die Unterhaltung fort, beantwortest Freigabe-Gates und liest das Transkript.
• Skripte — list_integrations und list_integration_tools zeigen, was ein Skript aufrufen kann, und run_script führt JavaScript auf dem Crevio-Computer deines Kontos gegen jeden REST-Endpunkt und jede verbundene Integration aus, mit derselben Autorisierung und Validierung wie die API.

URL	https://mcp.crevio.co/mcp
Transport	Streamable HTTP (zustandslos — jede Anfrage ist eigenständig)
Authentifizierung	Authorization: Bearer <API token> — dasselbe API-Token, das du für REST verwendest — oder X-Api-Key: <API token> für Clients, die nur einen benutzerdefinierten Header setzen können. OAuth 2.1 wird ebenfalls unterstützt; siehe Verbinden.
Discovery	https://mcp.crevio.co/mcp/server-card

[!NOTE]

Neu beim agentischen Modell von Crevio? Beginne mit der Übersicht zu KI & Agenten, um zu sehen, wie MCP, Tasks und Events zusammenpassen. Unter der Haube ist eine delegierte Aufgabe ein Task mit einem Run, sodass alles hier auch in deinem Dashboard sowie über /v1/tasks und /v1/task_runs sichtbar ist.

Einrichtung

1. Erstelle ein API-Token

Gehe in Crevio zu Settings → Developers → API tokens und erstelle eines. Eine MCP-Verbindung hat genau die Berechtigungen des Tokens dahinter — alles, was das Konto tun kann.

2. Konfiguriere deinen Client

Claude Code

claude mcp add --transport http crevio https://mcp.crevio.co/mcp \
  --header "Authorization: Bearer $CREVIO_API_TOKEN"

Claude Desktop / Cursor / andere Clients — füge dies zur MCP-Konfiguration des Clients hinzu (claude_desktop_config.json, ~/.cursor/mcp.json, …):

{
  "mcpServers": {
    "crevio": {
      "url": "https://mcp.crevio.co/mcp",
      "headers": {
        "Authorization": "Bearer <CREVIO_API_TOKEN>"
      }
    }
  }
}

Client-spezifische Schritte, OAuth und rohe curl-Beispiele findest du auf der Seite Verbinden.

3. Überprüfe mit whoami

Bitte den verbundenen Agenten, whoami aufzurufen. Es gibt das Konto und den Benutzer hinter dem Token, die Anmeldedaten, den Plan, das Guthaben, das Rate-Limit, die Wartegrenzen und die Liste der Tools zurück — ohne Argumente, ohne Nebenwirkungen. Wenn whoami funktioniert, funktioniert alles andere auch.

{
  "object": "whoami",
  "account": { "id": "acct_7k2m…", "name": "Jane's Studio", "slug": "janes-studio" },
  "user": { "id": "user_9qx…", "email": "jane@example.com", "name": "Jane Doe" },
  "credential": { "type": "api_key", "id": "token_3fa…", "name": "Claude Desktop", "expires_at": null },
  "plan": "Pro",
  "credits": 1840,
  "rate_limit": { "limit": 600, "window_seconds": 60 },
  "limits": { "ask_timeout_default_seconds": 300, "ask_timeout_max_seconds": 300, "message_max_chars": 10000 },
  "tools": ["whoami", "ask_crevio", "start_chat", "wait_for_run", "get_run", "list_chats", "get_chat", "send_message", "resolve_approvals", "cancel_run", "list_runs", "list_messages", "list_integrations", "list_integration_tools", "run_script", "wait_for_script_run", "get_script_run", "cancel_script_run"]
}

Empfohlene Workflows

Einmalige Aufgaben: ask_crevio

Für Arbeit, die Urteilsvermögen oder Formulierung erfordert. Ein Aufruf startet einen Run, wartet darauf und gibt den Run mit der abschließenden Antwort des Agenten in result zurück. Jede Aufgabe ist ein vollständiger Agenten-Run, von einer halben bis zu mehreren Minuten — um Daten direkt zu lesen oder zu ändern, braucht ein Skript Sekunden.

{
  "name": "ask_crevio",
  "arguments": {
    "message": "Which three products made the most revenue this month, and how does that compare to last month?",
    "idempotency_key": "monthly-top-products-2026-08"
  }
}

{
  "object": "task_run",
  "id": "trun_8d1k…",
  "task_id": "task_2nq…",
  "task_name": "Which three products made the most revenue this month, and how does that…",
  "chat_id": "aichat_5pz…",
  "status": "completed",
  "summary": "Top three by revenue this month: …",
  "result": "Top three by revenue this month:\n1. Lightroom Presets Vol. 2 — $2,140 (+18% vs July)\n2. …",
  "error_message": null,
  "pending_approval_ids": [],
  "credits_consumed": 4,
  "started_at": "2026-08-20T09:14:02Z",
  "completed_at": "2026-08-20T09:14:31Z",
  "created_at": "2026-08-20T09:14:01Z"
}

• Die Wartezeit beträgt standardmäßig und maximal 300 Sekunden, wenn dein Client eine gestreamte Antwort akzeptiert (Accept: text/event-stream, was MCP-Clients standardmäßig senden), andernfalls 90 Sekunden. Eine gestreamte Antwort sendet während des Wartens alle 10 Sekunden eine Fortschrittsbenachrichtigung — übergib einen progressToken in _meta, um sie zu erhalten. Übergib timeout_seconds, um kürzer zu warten.
• Wenn der Run am Ende der Wartezeit noch läuft, ist die Antwort kein Fehler: Es ist der Run mit wait_timed_out: true. Rufe wait_for_run mit seiner id auf, um weiter zu warten, und rufe ask_crevio nicht erneut auf — das würde die Aufgabe ein zweites Mal starten. Nichts geht verloren; der Run läuft auf Crevios Seite weiter.
• idempotency_key macht Wiederholungen sicher: Derselbe Schlüssel gibt den Run zurück, den der erste Aufruf gestartet hat, statt einen weiteren zu starten (und zu bezahlen). Übergib immer einen.
• speed: "faster" lässt den Agenten weniger nachdenken, für einfache Aufgaben, bei denen eine schnellere Antwort wichtiger ist als Tiefe. Der Standard ist smarter.
• response_format nimmt ein JSON-Schema (oder OpenAIs {type: "json_schema", json_schema: {schema}}), wenn dein Programm ein Objekt statt Prosa benötigt. Dem Agenten wird das Schema mitgeteilt, und der abgeschlossene Run trägt den geparsten Wert in json, gegen das Schema validiert, oder den Grund des Fehlschlags in json_error. start_chat und send_message nehmen es ebenfalls an.
• Dateien, die der Agent während des Runs geliefert hat, kommen in artifacts zurück. Tausche die id eines Artefakts mit get_file_download_url gegen einen Download-Link.
• approval_mode ist standardmäßig autonomous. supervised lässt den Run in needs_input vor jedem gated Write pausieren, bis du seine pending_approval_ids beantwortest (ein Run ohne Freigabebedarf endet mit seinem Vorschlag; antworte mit send_message, um ihn auszuführen); read_only verbietet Writes.

Lang laufende Aufgaben: start_chat → wait_for_run → send_message

Für alles, worauf du nicht warten möchtest — ein Website-Build, eine Rechercheaufgabe, eine Massenmigration:

1. start_chat stellt die Arbeit in die Warteschlange und gibt den Run sofort zurück.
2. wait_for_run (begrenzt) oder get_run (sofort), bis status completed, failed oder needs_input ist.
3. send_message setzt die Unterhaltung fort — Folgeanweisungen, Korrekturen, Antworten auf eine Frage des Agenten. Der Agent behält seinen Kontext. Bei einem abgeschlossenen Run startet dies einen neuen Run in derselben Unterhaltung; bei einem needs_input-Run setzt es ihn fort. Übergib timeout_seconds, um im selben Aufruf auf die Antwort zu warten, und eine idempotency_key, damit ein wiederholter Aufruf den Run zurückgibt, den der erste gestartet hat (reused: true), statt die Nachricht zweimal zu senden.
4. resolve_approvals, wenn ein Run bei einer Integrationsaktion pausiert (needs_input mit pending_approval_ids) — genehmige oder verweigere alle ausstehenden IDs auf einmal, und der Run wird fortgesetzt.
5. cancel_run, um einen Run zu stoppen, der ausstehend, laufend oder wartend ist.

Ein Chat ist die Unterhaltung, und ein Run ist ein Arbeitsschritt darin. list_runs zeigt jeden Run im Konto (übergib chat_id für nur die Runs einer Unterhaltung) — delegierte Aufgaben und deine geplanten Tasks gleichermaßen —, während list_chats und get_chat die Unterhaltungen selbst durchsuchen und list_messages das vollständige Transkript eines Chats liest, nicht nur die abschließende Antwort.

Skripte: run_script

Wenn der verbundene Agent Crevio selbst bedienen möchte, statt zu delegieren — oder exakte Daten zurückbraucht —, schreibt er ein Skript. run_script führt JavaScript auf dem Crevio-Computer deines Kontos mit bun aus, ohne Agenten-Turn. Das Skript kann die Crevio-API und jede Integration aufrufen, die dein Konto verbunden hat, beliebig viele Aufrufe verketten und die Daten transformieren, bevor sie zurückkommen.

Entdecken

list_integrations benennt jeden Namespace, den ein Skript aufrufen kann: crevioApi (die gesamte Crevio-API, eine Funktion pro Operation), platform (Crevios eigene Tools) und einen pro verbundener Integration (pdGmail, mcpLinear, …). list_integration_tools listet die Funktionen eines Namespace auf, jeweils mit ihren Parametern als TypeScript-Typ, ob sie nur liest, ob sie eine Freigabe benötigt, und einem Snippet, das run_script akzeptiert, sobald du es ausfüllst. crevioApi hat Hunderte von Operationen, also schränke es mit search ein:

{ "namespace": "crevioApi", "search": "price variant create" }

Ausführen

tools.<namespace>.<function>(args) führt einen Aufruf aus. Top-Level-await funktioniert, jeder Aufruf gibt sein Ergebnis zurück und wirft bei einem Fehler, und der letzte Ausdruck des Skripts ist sein Ergebnis.

const product = await tools.crevioApi.createProduct({ body: { name: "My Course", slug: "my-course" } });
await tools.crevioApi.createPriceVariant({
  body: { product: product.id, name: "Standard", amount_type: "fixed", amount: 4900, currency: "usd", billing_type: "one_time" },
});
await tools.crevioApi.updateProduct({ id_or_slug: product.id, body: { status: "active" } });
product.id

Leseoperationen nehmen ihre Parameter direkt (listOrders({ status: "succeeded" })); Schreiboperationen übergeben den Request-Body unter body, mit Pfadparametern daneben.

Übergib Werte mit args (bis zu 16 Strings); das Skript liest sie aus dem globalen args. Dateien, die in das durch das globale outputDir benannte Verzeichnis geschrieben werden, kommen als artifacts am Run zurück:

const { data } = await tools.crevioApi.listOrders({ status: "succeeded", limit: Number(args[0]) });
await Bun.write(`${outputDir}/orders.csv`, data.map((o) => o.id).join("\n"));
data.length

Ein Run gibt einen Script-Run zurück (srun_…): seine status (queued → in_progress → completed, failed, cancelled oder timed_out), die result, was das Skript in output ausgegeben hat, seine error und calls — jeder Tool-Aufruf, den es gemacht hat, mit seinem HTTP-Status, sodass ein Skript, das einen Fehler abgefangen hat, trotzdem zeigt, welcher Aufruf fehlgeschlagen ist. run_script wartet so lange, wie ask_crevio kann (300 Sekunden bei einer gestreamten Antwort, sonst 90; übergib wait_seconds, um kürzer zu warten). Ein Run, der länger dauert, kommt mit wait_timed_out: true und seiner ID zurück — kein Fehler: Warte mit wait_for_script_run weiter. Ein erneuter Aufruf von run_script würde das Skript zweimal ausführen, es sei denn, du übergibst dieselbe idempotency_key.

crevioApi-Aufrufe laufen durch dieselben Controller wie api.crevio.co, sodass die API-Konventionen unverändert gelten: Assoziationen sind bloße Namen mit Präfix-IDs (product: "prod_abc", nicht product_id), Geldbeträge sind in Cent, Listen-Endpunkte geben {object: "list", data: [...]} zurück, und ein Produkt braucht eine Preisvariante, bevor es active sein kann. Kurse und andere Inhalte sind Experiences (listExperiences), keine Produkte.

Grenzen:

• Wer: nur Konto-Administratoren. Das Skript läuft als du — einschließlich deiner persönlichen Integrationen — auf einem Computer, den dein gesamtes Team teilt.
• Timeout: timeout_seconds von 1 bis 600 (Standard 300). Der Computer muss möglicherweise zuerst aufwachen, was bis zu etwa 20 Sekunden dauern kann.
• Parallelität: höchstens 4 laufende Runs pro Benutzer und 8 pro Konto.
• Freigaben: Ein Skript kann nicht anhalten und um Freigabe bitten. Ein Aufruf, der sie benötigt (requires_approval in der Auflistung), schlägt mit approval_required fehl: Stelle diese Aktion in Settings → Integrations auf automatische Ausführung ein oder delegiere die Aufgabe stattdessen mit ask_crevio.
• Abbruch: Nur ein queued-Run kann abgebrochen werden. Ein laufendes Skript läuft bis zu seinem Ende oder seinem Timeout.
• Ausgabedateien: höchstens 20 pro Run, jede höchstens 50 MB. Größere Dateien werden weggelassen.

Vollständige Tool-Referenz

Tool	Zweck	Argumente
whoami	Das Konto, den Benutzer, die Anmeldedaten, den Plan, die Credits, Limits und Tools ermitteln	—
ask_crevio	Einen Job delegieren und auf das Ergebnis warten	message (erforderlich), timeout_seconds, approval_mode, speed, response_format, idempotency_key
start_chat	Einen Job delegieren, ohne zu warten	message (erforderlich), approval_mode, speed, response_format, idempotency_key
wait_for_run	(Begrenzt) warten, bis ein Lauf abgeschlossen ist	run_id (erforderlich), timeout_seconds
get_run	Status, Zusammenfassung, ausstehende Genehmigungen und endgültige Antwort eines Laufs abrufen	run_id (erforderlich)
list_chats	Die Chats des Kontos auflisten, neueste zuerst	search, limit, starting_after, ending_before
get_chat	Titel, Art und letzten Lauf eines Chats abrufen	chat_id (erforderlich)
send_message	Einen Chat fortsetzen; optional auf die Antwort warten	chat_id, message (erforderlich), timeout_seconds, response_format, idempotency_key
resolve_approvals	Die Integrationsaktionen genehmigen/ablehnen, auf die ein Lauf wartet	run_id, approvals: [{id, approved, reason}] (erforderlich)
cancel_run	Einen ausstehenden, laufenden oder wartenden Lauf stoppen	run_id (erforderlich)
list_runs	Die Läufe des Kontos auflisten, neueste zuerst	status, task_id, chat_id, limit, starting_after, ending_before
list_messages	Die Nachrichten eines Chats lesen, älteste zuerst	chat_id (erforderlich), limit, ending_before
list_integrations	Alle Namespaces benennen, die ein Skript aufrufen kann	—
list_integration_tools	Die Funktionen eines Namespaces mit Parametern und Snippets auflisten	namespace (erforderlich), search, limit, offset
run_script	JavaScript auf dem Computer des Kontos ausführen und darauf warten	code (erforderlich), args, timeout_seconds, wait_seconds, idempotency_key
wait_for_script_run	(Begrenzt) warten, bis ein Skriptlauf abgeschlossen ist	run_id (erforderlich), wait_seconds
get_script_run	Status und Ergebnis eines Skriptlaufs lesen	run_id (erforderlich)
cancel_script_run	Einen Skriptlauf abbrechen, der noch nicht gestartet ist	run_id (erforderlich)
get_file_download_url	Eine Artefakt-ID (art_…) gegen einen 15 Minuten gültigen Download-Link tauschen	file_id (erforderlich)
list_audit_events	Die Audit-Ereignisse des Kontos auflisten, neueste zuerst. Nur Enterprise-Plan. Benötigt den Scope audit:read und einen Administrator, wenn die Anmeldedaten als Person handeln	action, actor_type, entity_type, entity_id, after, limit, starting_after, ending_before

Welche Tools eine Verbindung sieht, hängt von ihren Anmeldedaten ab:

API-Schlüssel und OAuth-Tokens teilen dieselben Scopes, und eine Verbindung sieht die Tools, die die Scopes ihrer Anmeldedaten erlauben:

• read für die Tools, die lesen, write für die übrigen, es sei denn, das Tool benötigt einen der unten genannten Scopes.
• agent:run für ask_crevio, start_chat, send_message und cancel_run, sowie resolve_approvals mit write. Ohne write läuft delegierte Arbeit schreibgeschützt.
• scripts:run für run_script, wait_for_script_run, get_script_run und cancel_script_run. Ein Team-Schlüssel sieht diese nie, und ohne write kann ein Skript nichts ändern.
• files:read für get_file_download_url und audit:read für list_audit_events.
• whoami benötigt keinen.

Ein OAuth-Token, dem read_only gewährt wurde (der Standard, wenn ein Client keinen Scope anfordert), besitzt read; eines, dem read_write gewährt wurde, besitzt jeden Scope und sieht jedes Tool. Dasselbe gilt für einen API-Schlüssel, der vor der Einführung von Scopes erstellt wurde.

Ein Tool, das das Token nicht verwenden kann, erscheint nicht in tools/list, und ein Aufruf antwortet mit „Tool not found“. Beschränken Sie über Scopes hinaus, was ein Agent tun kann, indem Sie ihm ein Token auf einem Konto geben, dessen Daten er berühren darf, und indem Sie bei delegierten Jobs approval_mode wählen.

Das Run-Objekt

Delegations-Tools geben einen Run (trun_…) zurück, dasselbe Objekt wie GET /v1/task_runs/:id plus result und chat_id:

Feld	Bedeutung
status	pending → running → completed / failed, oder needs_input, wenn der Agent auf Sie wartet
result	Die endgültige Antwort des Agenten, bis zu 24.000 Zeichen (vorhanden, sobald der Lauf abgeschlossen ist)
json, json_error	Mit einem response_format: die geparste und validierte Antwort, oder warum sie kein gültiges JSON für das Schema war
artifacts	Vom Lauf gelieferte Dateien, jeweils {id, filename, content_type, size}; herunterladen mit get_file_download_url
summary	Die ersten 500 Zeichen der Antwort — was das Dashboard und Webhooks anzeigen
pending_approval_ids	Wenn needs_input: die Integrationsgenehmigungen, die den Lauf blockieren, für resolve_approvals
error_message	Warum ein failed-Lauf fehlgeschlagen ist ("Cancelled by the caller" nach cancel_run)
wait_timed_out, next_step	Vorhanden, wenn das Warten endete, bevor der Lauf abgeschlossen war — er läuft noch; next_step sagt, wie man ihn verfolgt
credits_consumed	Was der Lauf gekostet hat, in KI-Credits
task_id, chat_id	Die zugrunde liegende Task und Konversation, für die REST-API und das Dashboard

Läufe lösen außerdem die Webhooks task_run.completed, task_run.failed und task_run.needs_input aus und können per SSE unter GET /v1/task_runs/:id/stream gestreamt werden.

MCP Tasks und Elicitation

Dies sind Protokollfunktionen Ihres MCP-Clients, getrennt von Crevios eigenen Tasks. Damit verfolgt ein Client lange Jobs und beantwortet Genehmigungen selbst, statt wait_for_run und resolve_approvals aufzurufen. Beides erfordert das Protokoll 2026-07-28, das Ihr Client wählt. Ohne sie verhält sich jedes Tool wie oben beschrieben.

Asynchrone Tool-Aufrufe

Der Server implementiert die MCP Tasks-Erweiterung (io.modelcontextprotocol/tasks), angekündigt in server/discover sowohl auf /mcp als auch auf /chatgpt. Wenn eine Anfrage sie in _meta["io.modelcontextprotocol/clientCapabilities"].extensions deklariert, warten diese Tools höchstens 5 Sekunden und geben dann ein Task-Handle ("resultType": "task") zurück, statt die Anfrage offen zu halten: ask_crevio, wait_for_run, send_message mit einem timeout_seconds, run_script und wait_for_script_run. Ein Lauf, der innerhalb dieser 5 Sekunden abgeschlossen ist, wird direkt beantwortet.

• tasks/get gibt den status der Task zurück. working bedeutet, dass der Lauf noch läuft. Sobald er completed ist, enthält result genau das, was das Tool ohne Tasks zurückgegeben hätte. Abfrageintervall bei pollIntervalMs: 3 Sekunden für Agentenläufe, 1 Sekunde für Skripte.
• tasks/update beantwortet den inputRequests der Task (siehe unten).
• tasks/cancel stoppt den Lauf, wie cancel_run oder cancel_script_run.

Eine Task ist der Lauf selbst, daher dauert sie so lange wie der Lauf (ttlMs ist null). Ein Lauf, der failed endet, schließt die Task dennoch ab: Lesen Sie status und error_message innerhalb von result. Der eigene failed-Status der Task bleibt für Protokollfehler reserviert. Eine Task-ID ist nicht erratbar, und nur das Konto und der Benutzer, die den Lauf gestartet haben, können sie lesen. Eine unbekannte oder fremde ID antwortet mit -32602, und eine Anfrage, die die Erweiterung nicht deklariert, antwortet mit -32021.

Genehmigungen und Fragen

Wenn ein Client Form-Elicitation deklariert (_meta["io.modelcontextprotocol/clientCapabilities"].elicitation), fragt ein in needs_input pausierter Lauf den Benutzer direkt:

Der Lauf wartet auf	Der Client wird gefragt	Annehmen	Ablehnen oder schließen
Genehmigung von Integrationsaktionen	Ein Formular pro Aktion, verschlüsselt nach ihrer Genehmigungs-ID (apr_…), das beschreibt, was gesendet würde	Genehmigt sie	Lehnt sie ab
Eine Antwort auf die Frage des Agenten	Ein Formular mit einem Feld reply	Sendet die Antwort und der Lauf wird fortgesetzt	Schließt den Lauf als abgeschlossen

Eine geschlossene Genehmigung ist eine Ablehnung, daher läuft nichts ohne ein ausdrückliches Ja. Sie können die Formulare in beliebiger Reihenfolge und mehrere gleichzeitig beantworten. Der Lauf wird fortgesetzt, sobald jedes eine Antwort hat, und der Agent erfährt alle Entscheidungen zusammen.

• Mit Tasks: Die Task wechselt zu input_required mit den Formularen in inputRequests. Beantworten Sie sie mit tasks/update.
• Ohne Tasks: Das Tool gibt "resultType": "input_required" mit den Formularen und einem requestState zurück. Rufen Sie dasselbe Tool erneut mit denselben Argumenten auf, plus inputResponses und genau diesem requestState. Der Zustand ist versiegelt, an das Tool und seine Argumente gebunden und läuft nach einer Stunde ab.
• Ohne Form-Elicitation: Nichts ändert sich. Der Lauf kommt needs_input mit pending_approval_ids für resolve_approvals zurück, auch als abgeschlossene Task.

Events

Der Server implementiert die Entwurfsversion der MCP Events-Erweiterung (io.modelcontextprotocol/events), sodass ein Client Dinge abonnieren kann, die im Konto geschehen, wie order.paid oder email_message.received, und ohne Polling reagieren kann. Sie wird in server/discover sowohl auf /mcp als auch auf /chatgpt angekündigt.

Die Ereignistypen sind dieselben wie bei Webhooks, und ebenso die Nutzlast: data.object ist die Ressource genau so, wie ihr API-Endpunkt sie zurückgibt. events/list listet jeden Typ mit seinem payloadSchema auf.

Abonnieren

{
  "jsonrpc": "2.0", "id": 2, "method": "events/subscribe",
  "params": {
    "name": "order.paid",
    "arguments": {},
    "delivery": { "mode": "webhook", "url": "https://hooks.example.com/crevio", "secret": "whsec_<base64 of 24–64 random bytes>" },
    "cursor": null,
    "ttlMs": 86400000
  }
}

Die Antwort enthält die Abonnement-id (mcpsub_…), stabil für dieselben Anmeldedaten, URL, dasselbe Ereignis und dieselben Argumente, sowie refreshBefore. Rufen Sie events/subscribe vor refreshBefore erneut mit denselben Werten auf, um es zu behalten; events/unsubscribe mit name, arguments und delivery.url beendet es sofort.

• Verifizierung. Vor der ersten Zustellung an eine URL sendet Crevio ein POST mit {"type":"verification","challenge":"<nonce>"} an sie. Antworten Sie innerhalb von 5 Sekunden mit einem 2xx und {"challenge":"<nonce>"}. Jede Anmeldedaten verifiziert jede URL einmal.
• Lebensdauer. Ohne ttlMs dauert ein Abonnement einen Tag. Ein vorgeschlagenes ttlMs wird zwischen einer Minute und einem Tag beibehalten. "ttlMs": null fordert kein Ablaufdatum an, und Crevio gewährt es.
• Secret rotieren. Senden Sie bei einer Aktualisierung ein neues delivery.secret. 10 Minuten lang tragen Zustellungen Signaturen von beiden Secrets.
• Limits. 100 aktive Abonnements pro Konto. Abonnieren liest nur, daher kann ein read_only-Token es ausführen.

Zustellungen

Jedes Ereignis ist ein POST von {"eventId", "name", "timestamp", "data"}, signiert gemäß Standard Webhooks mit Ihrem Secret (webhook-id, webhook-timestamp, webhook-signature) und mit X-MCP-Subscription-Id. Verifizieren Sie die Signatur, bevor Sie dem Body vertrauen, und deduplizieren Sie anhand von eventId.

Was Ihr Endpunkt tut	Was passiert
Antwortet mit 2xx	Zugestellt
Antwortet mit 410 oder 413	Verworfen, ohne erneut zu versuchen
Schlägt fehl oder läuft in ein Timeout (5 Sekunden)	Bis zu 4 weitere Versuche über etwa 12 Minuten, dann verworfen
Schlägt eine Stunde lang weiter fehl	Zustellungen stoppen, bis Ihre nächste Aktualisierung sie wieder aktiviert
Schlägt bei einem Abonnement ohne Ablaufdatum 3 Tage lang weiter fehl	Crevio sendet ein POST mit {"type":"terminated",…} und löscht das Abonnement

Wenn die Anmeldedaten den Zugriff auf das Konto verlieren (Schlüssel gelöscht oder abgelaufen, OAuth-Zugriff widerrufen, Benutzer aus dem Konto entfernt), beendet das nächste Ereignis das Abonnement mit einem terminated-Envelope, der den Fehler -32024 trägt.

Was es nicht kann

• Webhook-Zustellung als einziger Weg, vorerst by design. events/poll und events/stream beantworten -32026. Verwende die Webhooks-API oder list_runs und die REST-Endpunkte, wenn du keine POSTs empfangen kannst.
• Kein Replay. cursor ist immer null: Ereignisse, die während einer abgelaufenen Subscription auftreten, werden nicht nachträglich zugestellt. Lies den aktuellen Zustand nach einer Lücke über die Tools aus.
• Keine Filter. Ereignistypen akzeptieren kein arguments. Eine Subscription erhält jedes Ereignis ihres Typs im Konto.

Fehler verwenden die Codes der Extension: -32602 ungültige Parameter (fehlerhafte URL, Secret oder Argumente), -32023 unbekanntes Ereignis oder unbekannte Subscription, -32024 kein authentifizierter Principal oder Zugriff verloren, -32025 Subscription-Limit, -32026 Zustellmodus nicht angeboten und -32027 die Callback-Verifizierung ist fehlgeschlagen, wobei data.reason eines von connection_refused, timeout, tls_error, http_4xx, http_5xx oder challenge_failed ist.

Fehler

Authentifizierungsfehler sind HTTP 401/403 auf der Anfrage selbst (WWW-Authenticate verweist auf die OAuth-Metadaten). Tool-Fehler kommen als Tool-Ergebnis mit isError: true und einem JSON-Body zurück:

{ "error": "run_busy", "message": "Run trun_8d1k… is still in progress; wait for it to settle before sending more.", "http_status": 409 }

error	Bedeutung	Was zu tun ist
run_busy	In dieser Konversation läuft noch ein Run	Warte darauf und rufe dann send_message auf
account_at_capacity	Das Konto hat bereits 5 laufende Runs (http_status: 429)	Versuche es nach retry_after_seconds erneut
idempotency_error	Ein idempotency_key wurde mit einer anderen Nachricht wiederverwendet	Übergib einen neuen Schlüssel für eine neue Nachricht
run_not_active	cancel_run bei einem bereits abgeschlossenen Run	Nichts — lies sein result
run_not_resumable	Der Run hat keine Konversation zum Fortsetzen	Starte einen neuen Job mit ask_crevio
approvals_pending	send_message bei einem durch Genehmigungen blockierten Run	Zuerst resolve_approvals
stale_resolution	Die übermittelten Genehmigungen stimmen nicht mit der ausstehenden Menge überein	get_run, dann reiche jeden pending_approval_ids-Eintrag erneut ein
insufficient_credits	Das Konto hat keine AI-Credits mehr	Füge Credits in Crevio hinzu
resource_missing	Kein Run/keine Task mit dieser ID in diesem Konto	Prüfe die ID — Runs sind kontogebunden
validation_failed	Ein fehlerhaftes Argument (z. B. ein unbekanntes approval_mode)	Korrigiere das Argument
rate_limit_exceeded	600 Anfragen pro Minute pro Eigentümer, geteilt mit der REST-API — oder zu viele gleichzeitig laufende Skript-Runs	Warte bis X-RateLimit-Reset (Rate Limits) oder warte, bis ein Skript-Run abgeschlossen ist
forbidden	run_script durch jemanden, der kein Konto-Admin ist	Frage einen Admin oder delegiere mit ask_crevio
run_not_cancellable	cancel_script_run bei einem bereits gestarteten Run	Warte mit wait_for_script_run darauf

Ein Skript, das eine Exception wirft, kommt trotzdem als Skript-Run zurück, mit status: "failed", seinem error und dem calls, das es erzeugt hat — run_script selbst liefert nur dann einen Fehler, wenn der Run nicht gestartet werden konnte oder das Warten beendet wurde.

Sicherheit

Jedes Tool läuft innerhalb der Tenant-Grenze deines Kontos. Delegierte Jobs führen den Crevio-Agent mit den Berechtigungen aus, die dein Konto bereits hat. run_script läuft auf dem Crevio-Computer deines Kontos als der aufrufende Admin; seine tools-Aufrufe durchlaufen dieselben Genehmigungseinstellungen, denen der Agent folgt, und dieselben API-Controller wie api.crevio.co, sodass Autorisierung, Validierung und Fehlermeldungen identisch mit direkten API-Aufrufen sind. Tokens sind so mächtig wie dein Konto: Verbinde nur Agenten, denen du vertraust, und widerrufe ein Token unter Settings → Developers, um eine Verbindung sofort zu trennen.

Nächste Schritte

Verbinden

Einrichtung pro Client, OAuth und curl-Beispiele.

Tasks (deine AI-Workforce)

Das Task-/Task-Run-Modell, auf dem jeder delegierte Job aufbaut — und wie du wiederkehrende Arbeit planst.

AI & Agents – Übersicht

Wie MCP, Tasks und Events Crevios agentisches Modell bilden.

API-Konventionen

Die Formen, Präfixe und Fallstricke, die crevioApi mit REST teilt.

Diese Dokumentation wird auf Mintlify erstellt und gehostet, einer Entwickler-Dokumentationsplattform.