MCP-Server · Ephemeral Docs

Ephemeral betreibt einen Model-Context-Protocol-Server (MCP). KI-Agenten wie Claude, ChatGPT und die Agenten in Ihrem Editor können damit direkt Läufe starten, auf Ergebnisse warten und Ihre Workflows lesen. Es gelten dieselben API-Schlüssel, Rollen, Budgets und Prüfungen wie bei der REST-API. Außerdem können sie Workflows speichern und löschen, Zeitpläne verwalten und Ihre Dateien auflisten – ein Agent kann so einen wiederkehrenden Auftrag von Anfang bis Ende einrichten.

Mit OAuth anmelden

Clients, die die MCP-Autorisierung unterstützen, brauchen nur die URL https://app.ephemer.al/mcp. Der Client findet die Anmeldung von Ephemeral über die 401-Antwort des Servers und dessen Metadaten der geschützten Ressource, registriert sich selbst und öffnet eine Seite, auf der Sie sich anmelden, eine Organisation wählen und zustimmen. Danach hält er ein Zugriffstoken, das eine Stunde gültig ist, und ein Refresh-Token; Sie werden nicht erneut gefragt, bis Sie den Zugriff widerrufen.

Der Zugriff gilt für die gewählte Organisation und die Rolle, der Sie zustimmen: member oder admin. admin können nur Inhaber und Admins der Organisation erteilen; die Mitgliedsrolle genügt für alles außer dem Erstellen, Ändern und Löschen von Zeitplänen; dafür ist admin nötig.
Tokens funktionieren nur für die API von Ephemeral (https://app.ephemer.al), nie für andere Dienste.
Verbundene Apps sehen und widerrufen Sie unter „Autorisierte Apps“ auf Ihrer Kontoseite.
Die Metadaten des Autorisierungsservers liegen unter https://ephemer.al/.well-known/oauth-authorization-server. Clients müssen PKCE (S256) verwenden.

Eine selbst gehostete Installation akzeptiert nur API-Schlüssel.

Mit einem API-Schlüssel verbinden

Erstellen Sie im Dashboard unter Schlüssel einen API-Schlüssel. Ein Mitglieds-Schlüssel genügt für Läufe, Workflows und Dateien; nehmen Sie einen Admin-Schlüssel, wenn der Agent auch Zeitpläne erstellen, ändern oder löschen soll. Der Server liegt unter https://app.ephemer.al/mcp und nutzt den Streamable-HTTP-Transport; jede Anfrage trägt den Schlüssel als Bearer-Token.

Claude Code

Fügen Sie den Server einmal hinzu; danach steht er in jeder Sitzung zur Verfügung.

Terminal

claude mcp add --transport http ephemeral https://app.ephemer.al/mcp \
  --header "Authorization: Bearer $EPHEMERAL_API_KEY"

Cursor, VS Code und andere Clients mit HTTP-Unterstützung

Die meisten Clients akzeptieren in ihren MCP-Einstellungen einen Remote-Server mit Headern:

JSON

{
  "mcpServers": {
    "ephemeral": {
      "url": "https://app.ephemer.al/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop

Claude Desktop startet lokale Server aus seiner Konfigurationsdatei (claude_desktop_config.json). Die Brücke mcp-remote verbindet es mit einem Remote-Server und reicht den Header weiter:

JSON

{
  "mcpServers": {
    "ephemeral": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.ephemer.al/mcp", "--header", "Authorization:${EPHEMERAL_AUTH}"],
      "env": { "EPHEMERAL_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

Eine selbst gehostete Installation stellt denselben Endpunkt unter der URL ihrer Engine bereit, zum Beispiel https://ephemeral.example.com/mcp, mit einem Schlüssel dieser Installation.

Werkzeuge

Jedes Werkzeug hat ein Eingabeschema, das Clients dem Modell zeigen, und liefert Text und strukturierten Inhalt. Fehler, die die REST-API als Fehler meldet, kommen als Werkzeugfehler mit derselben Meldung zurück.

Werkzeug	Funktion
`create_run`	Startet einen Lauf aus einem Prompt oder einem gespeicherten Workflow, optional mit Eingabe, Modell, Dateien, Verbindungen, Webzugriff, Shell, Zeitlimit, Kostenlimit und Zero Data Retention. Gibt den eingereihten Lauf zurück. Mit idempotency_key ist eine Wiederholung sicher.
`get_run`	Liest einen Lauf: Status, Ausgabe, Fehler, Kosten und ob die Abrechnung noch aussteht. Solange die Abrechnung aussteht, ist cost_micros vorläufig und meist höher als die endgültigen Kosten; das Ergebnis enthält dann cost_final: false. Nennen Sie die Kosten erst, wenn cost_final true ist.
`wait_for_run`	Wartet bis zu 60 Sekunden, bis ein Lauf beendet ist, und gibt ihn zurück. Rufen Sie es erneut auf, wenn der Lauf noch aktiv ist. Nach dem Ende des Laufs wartet es zusätzlich, bis die Abrechnung abgeschlossen ist, sodass die Kosten endgültig sind (cost_final: true); läuft die Zeit vorher ab, sind sie vorläufig.
`list_runs`	Listet Läufe, neueste zuerst, mit Statusfilter und Cursor.
`cancel_run`	Bricht einen noch nicht beendeten Lauf ab.
`list_workflows`	Listet die gespeicherten Workflows mit description, input_schema und output_schema, damit ein Agent sieht, was jeder erwartet und liefert, ohne den Prompt zu lesen.
`get_workflow`	Liest eine Workflow-Definition, ohne Zugangsdaten.
`list_models`	Sucht Modelle. Gibt eine kompakte Liste (ID, Name, Kontextlänge, Eingabe- und Ausgabepreis pro Million Token, Zero Data Retention) und die Gesamtzahl zurück. Argumente: query (Teil der ID oder des Namens, ohne Beachtung der Groß-/Kleinschreibung), limit (standardmäßig 25, höchstens 100), zero_data_retention (nur Modelle, die es unterstützen) und model (alle Details eines Modells).
`list_connections`	Die gespeicherten Verbindungen, die ein Lauf nutzen kann, ohne URLs und Geheimnisse.
`save_workflow`	Erstellt einen Workflow oder ersetzt den gleichnamigen: Prompt, Modell, Dateien, Verbindungen, Webzugriff, Shell, Zeitlimit und Zero Data Retention. Verbindungen sind nur Verweise auf gespeicherte. Nimmt außerdem eine Beschreibung und JSON Schemas für Eingabe und Ausgabe an.
`delete_workflow`	Löscht einen gespeicherten Workflow.
`list_schedules`	Listet die Zeitpläne, optional für einen Workflow, mit nächstem Start und letztem Ergebnis.
`get_schedule`	Liest einen Zeitplan.
`create_schedule`	Startet einen gespeicherten Workflow nach einem Cron-Zeitplan in einer Zeitzone, optional mit Eingabe und Kostenlimit. Erfordert einen Admin-Schlüssel.
`update_schedule`	Ändert einen Zeitplan oder pausiert und setzt ihn mit enabled fort. Erfordert einen Admin-Schlüssel.
`delete_schedule`	Löscht einen Zeitplan. Erfordert einen Admin-Schlüssel.
`preview_schedule`	Prüft einen Cron-Ausdruck und gibt die nächsten fünf Startzeiten zurück, ohne zu speichern.
`run_schedule`	Startet den Workflow eines Zeitplans sofort und gibt den eingereihten Lauf zurück.
`list_files`	Listet die in der Organisation gespeicherten Dateien (nur lesend).

Ausprobieren

Der Endpunkt nimmt JSON-RPC-2.0-Nachrichten per POST entgegen. Normalerweise übernimmt das der Client; mit curl sieht ein Aufruf so aus:

Terminal

curl -sS https://app.ephemer.al/mcp \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_run","arguments":{"prompt":"Summarize https://example.com","web":true,"max_cost_micros":200000}}}'

Workflow speichern und planen

Ein Agent macht aus einer Aufgabe mit zwei Aufrufen einen wiederkehrenden Auftrag. Zuerst save_workflow mit diesen Argumenten:

JSON

{
  "name": "weekly-report",
  "prompt": "Summarize last week's support tickets from the helpdesk connection and list the three biggest themes.",
  "connections": { "helpdesk": { "ref": "helpdesk", "allowed_methods": ["GET"] } },
  "timeout_seconds": 600
}

Dann create_schedule (Admin-Schlüssel), hier jeden Montag um 09:00 Uhr in Madrid; preview_schedule zeigt vorher die nächsten Startzeiten:

JSON

{
  "workflow": "weekly-report",
  "cron": "0 9 * * 1",
  "timezone": "Europe/Madrid",
  "max_cost_micros": 500000
}

Rollen

Die meisten Werkzeuge sind Operationen, die ein Mitglieds-Schlüssel in der REST-API ohnehin ausführen darf; für die Zeitplan-Werkzeuge gilt dieselbe Regel wie in der REST-API: Zeitpläne lesen, in der Vorschau prüfen und sofort ausführen geht mit einem Mitglieds-Schlüssel, create_schedule, update_schedule und delete_schedule brauchen dagegen einen Admin- oder Owner-Schlüssel und antworten sonst mit einem Werkzeugfehler (Status 403). Es gibt kein Werkzeug, um Schlüssel zu erstellen, Verbindungen zu ändern oder die Abrechnung zu verwalten. Der Schlüssel bestimmt auch die Organisation: Läufe werden ihr berechnet und erscheinen in ihrem Laufverlauf.

Sicherheit

Ohne Schlüssel läuft nichts. Initialisieren und die Werkzeugliste abrufen kann jeder, sie ist ohnehin öffentlich; jeder Werkzeugaufruf braucht einen gültigen Schlüssel und erhält ohne ihn 401.
OAuth-Zugriffstokens laufen nach einer Stunde ab, sind auf eine Organisation und die genehmigte Rolle beschränkt und lassen sich jederzeit auf Ihrer Kontoseite widerrufen.
Budgets gelten. Jeder Lauf hat ein Kostenlimit, aus max_cost_micros oder dem Standard der Organisation, und es gelten dieselben Guthabenprüfungen wie bei der API.
Verbindungen sind gespeicherte Referenzen. Ein Agent kann nur eine von Ihrer Organisation gespeicherte Verbindung benennen und sie mit allowed_methods (zum Beispiel nur GET) oder allowed_tools einschränken. Eine URL oder Zugangsdaten kann er nie angeben.
Zero Data Retention ist pro Lauf möglich. Die Ausgabe eines solchen Laufs wird beim ersten Lesen freigegeben.
Nur POST wird akzeptiert. Es gibt keine Sitzungen und keine Nachrichten vom Server.

Protokoll

Unterstützt werden die Protokollversionen 2025-11-25, 2025-06-18 und 2025-03-26; der Server antwortet mit der Version, die der Client anfragt. GET und DELETE liefern 405. Ein Discovery-Dokument liegt unter /.well-known/mcp/server-card.json.