Verbindungen

Eine Verbindung lässt einen Agenten während einer Ausführung eine HTTP-API oder einen MCP-Server aufrufen. Ephemeral verwahrt die Zugangsdaten und führt den Aufruf aus. Der Worker sieht nie ein Token, Passwort oder URL-Geheimnis.

So funktioniert ein Aufruf

Jede Verbindung, die Sie einer Ausführung freigeben, gibt dem Agenten Tools zum Aufrufen. Ruft er eines auf, sendet der Worker die Anfrage mit einem kurzlebigen Token, das nur für diese Ausführung gilt, an Ephemeral. Ephemeral prüft, ob der Ausführung die Verbindung freigegeben wurde und ob die Methode oder das Tool zulässig ist, fügt die Zugangsdaten hinzu, sendet die Anfrage, entfernt Zugangsdaten aus der Antwort und reicht sie zurück. Jeder Aufruf wird als connection-Ereignis aufgezeichnet.

Bei einer HTTP-Verbindung liefert der Agent eine Methode, einen Pfad relativ zur URL der Verbindung und optional einen Body. Bodys werden als JSON gesendet, es sei denn, der Agent nennt einen anderen Content-Type, etwa ein Formular oder XML, und sendet den Body als Text. Bei einer MCP-Verbindung sieht der Agent die Tools des Servers und ruft sie direkt auf.

Dem Agenten erklären, wie er sie nutzt

Eine HTTP-Verbindung gibt dem Agenten eine Basis-URL und sonst nichts. Beschreiben Sie die API daher in instructions: die Endpunkte, die die Aufgabe braucht, das Anfrageformat, wie IDs aussehen und welche Regeln gelten. Der Agent sieht sie beim Tool der Verbindung und in seinen dauerhaften Anweisungen. Eine Ausführung kann die Anweisungen einer gespeicherten Verbindung durch eigene ersetzen.

"instructions": "Find a customer with GET /v1/customers?email=... Create a refund with POST /v1/refunds as a form body (payment, amount in cents). Never refund more than the payment amount."

Gespeicherte und Inline-Verbindungen

Eine gespeicherte Verbindung wird einmal für die Organisation abgelegt und über ihren Namen referenziert. Inhaber und Admins erstellen sie im Dashboard unter Verbindungen oder mit PUT /v1/connections/{name}. Ausführungen und Workflows verweisen mit ref darauf:

"connections": {
  "payments": { "ref": "payments-api", "allowed_methods": ["GET"] },
  "docs": { "ref": "docs-mcp", "allowed_tools": ["search"] }
}

Der Schlüssel, etwa payments, ist der Name, den der Agent in dieser Ausführung sieht. Sie können eine Verbindung auch inline in der Ausführungsanfrage definieren, mit ihrer URL und ihren Zugangsdaten. Inline-Zugangsdaten werden verschlüsselt mit dieser Ausführung gespeichert und beim Zurücklesen aus ihrer Definition entfernt, sodass sie bei einer erneuten Ausführung wieder mitgegeben werden müssen. Gespeicherte Verbindungen vermeiden das.

Zugriff einschränken

allowed_methods begrenzt, welche HTTP-Methoden eine HTTP-Verbindung akzeptiert. allowed_tools begrenzt, welche Tools eines MCP-Servers aufgerufen werden dürfen. Eine leere oder fehlende Liste erlaubt alles.

Eine Ausführung kann eine gespeicherte Verbindung weiter einschränken. Sie erhält nur die Methoden oder Tools, die in beiden Listen vorkommen. Haben die beiden Listen nichts gemeinsam, wird die Ausführungsanfrage abgelehnt, sodass eine Ausführung nie mehr Zugriff erhält, als die gespeicherte Verbindung gewährt.

Authentifizierung

Für OAuth speichert ein Inhaber oder Admin die Verbindung mit Client-ID, Autorisierungs-URL und Token-URL des Anbieters und autorisiert sie dann einmal im Browser. Ephemeral speichert die Tokens und erneuert das Zugriffstoken, bevor es abläuft, sofern der Anbieter ein Refresh-Token ausgestellt hat. Registrieren Sie https://app.ephemer.al/oauth/callback bei Ihrem Anbieter als Redirect-URI; bei einer selbst gehosteten Installation verwenden Sie Ihre eigene Domain.

Netzwerkregeln

• Verbindungs-URLs müssen HTTPS verwenden und auf öffentliche Internetadressen auflösen.
• Weiterleitungen werden nicht verfolgt.
• Eine HTTP-Verbindung akzeptiert GET, POST, PUT, PATCH, DELETE und HEAD und liefert höchstens 1 MiB pro Antwort. Der Agent erhält die gesamte Antwort; die Aufzeichnung der Ausführung behält bis zu 256 KiB davon und markiert, wo gekürzt wurde.
• MCP-Server werden über Streamable HTTP erreicht. Agenten können Tools auflisten und aufrufen; andere MCP-Funktionen werden abgelehnt.
• Beim gehosteten Dienst erreicht das Netzwerk eines Workers nur Ephemeral. Jede Anfrage nach außen läuft über eine Verbindung oder, sofern die Ausführung ihn hat, über den Webzugriff.