Conexiones

Una conexión permite que un agente llame a una API HTTP o a un servidor MCP durante una ejecución. Ephemeral guarda las credenciales y hace la llamada. El worker nunca ve un token, una contraseña ni un secreto de URL.

Cómo funciona una llamada

Cada conexión que concedes a una ejecución da al agente herramientas a las que llamar. Cuando llama a una, el worker envía la solicitud a Ephemeral con un token de corta duración que solo funciona para esa ejecución. Ephemeral comprueba que a la ejecución se le concedió la conexión y que el método o la herramienta están permitidos, añade las credenciales, envía la solicitud, elimina los valores de credenciales de la respuesta y se la devuelve. Cada llamada se registra como un evento connection.

En una conexión HTTP, el agente indica un método, una ruta relativa a la URL de la conexión y un cuerpo opcional. Los cuerpos se envían como JSON salvo que el agente indique otro tipo de contenido, como un formulario o XML, y envíe el cuerpo como texto. En una conexión MCP, el agente ve las herramientas del servidor y las llama directamente.

Indicar al agente cómo usarla

Una conexión HTTP da al agente una URL base y nada más, así que describe la API en instructions: los endpoints que necesita la tarea, el formato de las solicitudes, el aspecto de los IDs y las reglas que debe seguir. El agente las ve junto con la herramienta de la conexión y en sus instrucciones permanentes. Una ejecución puede sustituir las instrucciones de una conexión guardada por las suyas.

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

Conexiones guardadas y en línea

Una conexión guardada se almacena una vez para la organización y se referencia por su nombre. Los propietarios y administradores las crean en el panel, en Conexiones, o con PUT /v1/connections/{name}. Las ejecuciones y los flujos de trabajo hacen referencia a ellas con ref:

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

La clave, como payments, es el nombre que ve el agente en esta ejecución. También puedes definir una conexión en línea en la solicitud de ejecución, con su URL y credenciales. Las credenciales en línea se almacenan cifradas con esa ejecución y se eliminan de su definición cuando la vuelves a leer, así que para repetirla hay que volver a proporcionarlas. Las conexiones guardadas evitan esto.

Restringir el acceso

allowed_methods limita qué métodos HTTP acepta una conexión HTTP. allowed_tools limita a qué herramientas de un servidor MCP se puede llamar. Una lista vacía o ausente lo permite todo.

Una ejecución puede restringir aún más una conexión guardada. La ejecución recibe solo los métodos o herramientas que aparecen en ambas listas. Si las dos listas no tienen nada en común, la solicitud de ejecución se rechaza, de modo que una ejecución nunca acaba con más acceso del que concede la conexión guardada.

Autenticación

Para OAuth, un propietario o administrador guarda la conexión con el ID de cliente, la URL de autorización y la URL de token del proveedor, y la autoriza una vez en el navegador. Ephemeral almacena los tokens y renueva el token de acceso antes de que caduque, siempre que el proveedor haya emitido un token de actualización. Registra https://app.ephemer.al/oauth/callback como URI de redirección en tu proveedor; en una instalación autoalojada, usa tu propio dominio.

Reglas de red

• Las URL de las conexiones deben usar HTTPS y resolverse a direcciones públicas de internet.
• No se siguen las redirecciones.
• Una conexión HTTP acepta GET, POST, PUT, PATCH, DELETE y HEAD, y devuelve como máximo 1 MiB por respuesta. El agente recibe la respuesta completa; el registro de la ejecución conserva hasta 256 KiB y marca dónde se acortó.
• Se accede a los servidores MCP mediante Streamable HTTP. Los agentes pueden listar y llamar herramientas; las demás funciones de MCP se rechazan.
• En el servicio alojado, la red de un worker solo llega a Ephemeral. Toda solicitud externa pasa por una conexión o, cuando la ejecución lo tiene, por el acceso web.