MCP server

Ephemeral runs a Model Context Protocol (MCP) server, so AI agents such as Claude, ChatGPT and the agents in your editor can start runs, wait for results and read your workflows directly. It uses the same API keys, roles, budgets and validation as the REST API. They can also save and delete workflows, manage schedules and list your files, so an agent can set up a recurring job end to end.

Sign in with OAuth

Clients that support MCP authorization need only the URL https://app.ephemer.al/mcp. The client finds Ephemeral’s sign-in from the server’s 401 answer and its protected resource metadata, registers itself, and opens a page where you sign in, choose an organization and approve. It then holds an access token valid for one hour and a refresh token, so you are not asked again until you revoke it.

• Access is for the organization you pick, with the role you approve: member or admin. Only organization owners and admins can grant admin, and member is enough for everything except creating, changing or deleting schedules, which needs admin.
• Tokens work only for Ephemeral’s API (https://app.ephemer.al), never for other services.
• Review or revoke every connected app under Authorized apps on your account page.
• The authorization server’s metadata is at https://ephemer.al/.well-known/oauth-authorization-server. Clients must use PKCE (S256).

Connect with an API key

Create an API key under Keys in the dashboard. A member key covers runs, workflows and files; use an admin key if the agent should also create, change or delete schedules. The server is at https://app.ephemer.al/mcp and speaks the Streamable HTTP transport; every request carries the key as a bearer token.

Claude Code

Add the server once; it is then available in every session.

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

Cursor, VS Code and other clients with HTTP support

Most clients accept a remote server with headers, in their MCP settings:

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

Claude Desktop

Claude Desktop starts local servers from its configuration file (claude_desktop_config.json). The mcp-remote bridge connects it to a remote server and passes the header:

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

Tools

Each tool has an input schema, which clients show to the model, and a result with both text and structured content. Failures that the REST API reports as errors come back as tool errors with the same message.

Try it

The endpoint takes JSON-RPC 2.0 messages by POST. A client does this for you; with curl, one call looks like this:

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}}}'

Save a workflow and schedule it

An agent can turn a task into a recurring job with two calls. First save_workflow, with these arguments:

{
  "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
}

Then create_schedule (admin key), here every Monday at 09:00 in Madrid; preview_schedule shows the next start times first:

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

Roles

Most tools are operations that a member key can already perform in the REST API, and the schedule tools follow the same rule as the REST API: reading, previewing and running a schedule now need only a member key, while create_schedule, update_schedule and delete_schedule need an admin or owner key and answer with a tool error (status 403) otherwise. There is no tool to create keys, change connections or manage billing. The key also decides the organization; runs are billed to it and appear in its run history.

Safety

• Nothing runs without a key. Anyone can initialize and list the tools, which are public anyway; every tool call needs a valid key, and gets 401 without one.
• OAuth access tokens expire after an hour, are limited to one organization and the approved role, and can be revoked at any time on your account page.
• Budgets apply. Every run has a cost cap, from max_cost_micros or the organization default, and the same balance checks as the API.
• Connections are saved references. An agent can only name a connection that your organization saved, and can narrow it with allowed_methods (for example GET only) or allowed_tools. It can never supply a URL or a credential.
• Zero data retention is available per run. The output of such a run is released on its first read.
• Only POST is accepted. There are no sessions and no server-initiated messages.

Protocol

Protocol versions 2025-11-25, 2025-06-18 and 2025-03-26 are supported; the server answers with the version the client asks for. GET and DELETE return 405. A discovery document is published at /.well-known/mcp/server-card.json.