Connections

A connection lets an agent call an HTTP API or an MCP server during a run. Ephemeral keeps the credentials and makes the call. The worker never sees a token, password or URL secret.

How a call works

Each connection you grant to a run gives the agent tools to call. When it calls one, the worker sends the request to Ephemeral with a short-lived token that only works for that run. Ephemeral checks that the run was granted the connection and that the method or tool is allowed, adds the credentials, sends the request, removes credential values from the response and hands it back. Each call is recorded as a connection event.

For an HTTP connection, the agent supplies a method, a path relative to the connection's URL and an optional body. Bodies are sent as JSON unless the agent names another content type, such as a form or XML, and sends the body as text. For an MCP connection, the agent sees the server's tools and calls them directly.

Telling the agent how to use it

An HTTP connection gives the agent a base URL and nothing else, so describe the API in instructions: the endpoints the task needs, the request format, what IDs look like and any rules to follow. The agent sees them with the connection's tool and in its standing instructions. A run can replace a saved connection's instructions with its own.

"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."

Saved and inline connections

A saved connection is stored once for the organization and referenced by name. Owners and admins create them in the dashboard under Connections or with PUT /v1/connections/{name}. Runs and workflows refer to them with ref:

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

The key, such as payments, is the name the agent sees in this run. You can also define a connection inline in the run request, with its URL and credentials. Inline credentials are stored encrypted with that run and removed from its definition when you read it back, so a rerun needs them supplied again. Saved connections avoid that.

Narrowing access

allowed_methods limits which HTTP methods an HTTP connection accepts. allowed_tools limits which tools of an MCP server can be called. An empty or missing list allows everything.

A run can narrow a saved connection further. The run gets only the methods or tools that appear in both lists. If the two lists have nothing in common, the run request is rejected, so a run never ends up with more access than the saved connection grants.

Authentication

For OAuth, an owner or admin saves the connection with the provider's client ID, authorization URL and token URL, then authorizes it once in the browser. Ephemeral stores the tokens and refreshes the access token before it expires, as long as the provider issued a refresh token. Register https://app.ephemer.al/oauth/callback as the redirect URI with your provider; on a self-hosted installation, use your own domain.

Network rules

• Connection URLs must use HTTPS and resolve to public internet addresses.
• Redirects are not followed.
• An HTTP connection accepts GET, POST, PUT, PATCH, DELETE and HEAD, and returns at most 1 MiB per response. The agent receives the whole response; the run record keeps up to 256 KiB of it and marks where it was shortened.
• MCP servers are reached over Streamable HTTP. Agents can list and call tools; other MCP features are refused.
• On the hosted service, a worker's network reaches only Ephemeral. Every outside request goes through a connection or, when the run has it, web access.