Servidor MCP · Documentación de Ephemeral

Ephemeral ofrece un servidor del Model Context Protocol (MCP), de modo que agentes de IA como Claude, ChatGPT y los agentes de tu editor pueden iniciar ejecuciones, esperar resultados y leer tus flujos de trabajo directamente. Usa las mismas claves de API, roles, presupuestos y validaciones que la API REST. También pueden guardar y borrar flujos de trabajo, gestionar programaciones y listar tus archivos, de modo que un agente puede configurar una tarea recurrente de principio a fin.

Iniciar sesión con OAuth

Los clientes que admiten la autorización de MCP solo necesitan la URL https://app.ephemer.al/mcp. El cliente descubre el inicio de sesión de Ephemeral a partir de la respuesta 401 del servidor y de sus metadatos del recurso protegido, se registra y abre una página donde inicias sesión, eliges una organización y apruebas. Después conserva un token de acceso válido durante una hora y un token de actualización, así que no se te vuelve a preguntar hasta que lo revoques.

El acceso es para la organización que elijas, con el rol que apruebes: member o admin. Solo los propietarios y administradores de la organización pueden conceder admin, y el de miembro basta para todo salvo crear, cambiar o borrar programaciones, que requiere admin.
Los tokens solo funcionan con la API de Ephemeral (https://app.ephemer.al), nunca con otros servicios.
Revisa o revoca cada aplicación conectada en «Aplicaciones autorizadas», en la página de tu cuenta.
Los metadatos del servidor de autorización están en https://ephemer.al/.well-known/oauth-authorization-server. Los clientes deben usar PKCE (S256).

Una instalación autoalojada solo acepta claves de API.

Conectar con una clave de API

Crea una clave de API en Claves, en el panel. Una clave de miembro cubre ejecuciones, flujos de trabajo y archivos; usa una clave de administrador si el agente también debe crear, cambiar o borrar programaciones. El servidor está en https://app.ephemer.al/mcp y usa el transporte Streamable HTTP; cada solicitud lleva la clave como token de portador.

Claude Code

Añade el servidor una vez; después estará disponible en todas las sesiones.

Terminal

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

Cursor, VS Code y otros clientes con soporte HTTP

La mayoría de los clientes aceptan un servidor remoto con cabeceras en su configuración de MCP:

JSON

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

Claude Desktop

Claude Desktop inicia servidores locales desde su archivo de configuración (claude_desktop_config.json). El puente mcp-remote lo conecta con un servidor remoto y pasa la cabecera:

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

Una instalación autoalojada ofrece el mismo endpoint en la URL de su motor, por ejemplo https://ephemeral.example.com/mcp, con una clave de esa instalación.

Herramientas

Cada herramienta tiene un esquema de entrada, que los clientes muestran al modelo, y devuelve texto y contenido estructurado. Los fallos que la API REST informa como errores vuelven como errores de herramienta con el mismo mensaje.

Herramienta	Qué hace
`create_run`	Inicia una ejecución a partir de un prompt o de un flujo de trabajo guardado, con entrada, modelo, archivos, conexiones, acceso a la web, shell, tiempo límite, tope de coste y retención cero de datos opcionales. Devuelve la ejecución en cola. Con idempotency_key, reintentar es seguro.
`get_run`	Lee una ejecución: estado, salida, error, coste y si la facturación sigue pendiente. Mientras la facturación está pendiente, cost_micros es provisional y suele ser mayor que el coste final, y el resultado indica cost_final: false; cite el coste solo cuando cost_final sea true.
`wait_for_run`	Espera hasta 60 segundos a que termine una ejecución y la devuelve. Vuelve a llamarla si la ejecución sigue en curso. Cuando la ejecución ha terminado, espera además a que la facturación se liquide, de modo que el coste devuelto sea final (cost_final: true); si se agota el tiempo antes, el coste es provisional.
`list_runs`	Lista las ejecuciones, las más recientes primero, con filtro de estado y cursor.
`cancel_run`	Cancela una ejecución que no ha terminado.
`list_workflows`	Lista los flujos de trabajo guardados con su description, input_schema y output_schema, para que un agente vea qué espera y qué devuelve cada uno sin leer su prompt.
`get_workflow`	Lee la definición de un flujo de trabajo, sin credenciales.
`list_models`	Busca modelos. Devuelve una lista compacta (id, nombre, longitud de contexto, precio de entrada y de salida por millón de tokens, retención cero de datos) y el total. Argumentos: query (parte del id o del nombre, sin distinguir mayúsculas), limit (25 por defecto, como máximo 100), zero_data_retention (solo los modelos que la admiten) y model (todos los detalles de un modelo).
`list_connections`	Las conexiones guardadas que puede usar una ejecución, sin URL ni secretos.
`save_workflow`	Crea un flujo de trabajo o reemplaza el que tiene ese nombre: prompt, modelo, archivos, conexiones, acceso a la web, shell, tiempo límite y retención cero de datos. Las conexiones son solo referencias a conexiones guardadas. También acepta una descripción y JSON Schemas para la entrada y la salida.
`delete_workflow`	Borra un flujo de trabajo guardado.
`list_schedules`	Lista las programaciones, opcionalmente de un flujo de trabajo, con el próximo inicio y el último resultado.
`get_schedule`	Lee una programación.
`create_schedule`	Inicia un flujo de trabajo guardado según un calendario cron y una zona horaria, con entrada y tope de coste opcionales. Requiere una clave de administrador.
`update_schedule`	Cambia una programación, o la pausa y la reanuda con enabled. Requiere una clave de administrador.
`delete_schedule`	Borra una programación. Requiere una clave de administrador.
`preview_schedule`	Comprueba una expresión cron y devuelve los cinco próximos inicios, sin guardar nada.
`run_schedule`	Inicia ahora el flujo de trabajo de una programación y devuelve la ejecución en cola.
`list_files`	Lista los archivos guardados en la organización (solo lectura).

Pruébalo

El endpoint recibe mensajes JSON-RPC 2.0 por POST. Normalmente lo hace el cliente; con curl, una llamada se ve así:

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

Guardar un flujo de trabajo y programarlo

Un agente puede convertir una tarea en un trabajo recurrente con dos llamadas. Primero save_workflow, con estos argumentos:

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
}

Después create_schedule (clave de administrador), aquí cada lunes a las 09:00 en Madrid; antes, preview_schedule muestra los próximos inicios:

JSON

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

Roles

La mayoría de las herramientas son operaciones que una clave de miembro ya puede hacer en la API REST, y las de programaciones siguen la misma regla que la API REST: leer, previsualizar y ejecutar ahora una programación solo requiere una clave de miembro, mientras que create_schedule, update_schedule y delete_schedule requieren una clave de administrador o propietario y, si no, responden con un error de herramienta (estado 403). No hay herramientas para crear claves, cambiar conexiones ni gestionar la facturación. La clave también decide la organización: las ejecuciones se le facturan y aparecen en su historial.

Seguridad

Nada se ejecuta sin clave. Cualquiera puede inicializar y listar las herramientas, que ya son públicas; cada llamada a una herramienta necesita una clave válida y sin ella recibe 401.
Los tokens de acceso OAuth caducan al cabo de una hora, se limitan a una organización y al rol aprobado, y se pueden revocar en cualquier momento desde la página de tu cuenta.
Los presupuestos se aplican. Cada ejecución tiene un tope de coste, de max_cost_micros o el valor predeterminado de la organización, y las mismas comprobaciones de saldo que la API.
Las conexiones son referencias guardadas. Un agente solo puede nombrar una conexión que tu organización haya guardado y puede restringirla con allowed_methods (por ejemplo, solo GET) o allowed_tools. Nunca puede aportar una URL ni una credencial.
La retención cero de datos está disponible por ejecución. La salida de esa ejecución se libera en su primera lectura.
Solo se acepta POST. No hay sesiones ni mensajes iniciados por el servidor.

Protocolo

Se admiten las versiones de protocolo 2025-11-25, 2025-06-18 y 2025-03-26; el servidor responde con la versión que pide el cliente. GET y DELETE devuelven 405. Hay un documento de descubrimiento en /.well-known/mcp/server-card.json.