Conexiones · Documentación de Ephemeral

Guarda conexiones HTTP y MCP, autoriza conexiones OAuth y consulta lo que pueden usar las ejecuciones. Configurar conexiones requiere una clave de administrador o un propietario o administrador con la sesión iniciada; los miembros pueden leer el catálogo. Consulta conexiones para saber cómo se intermedian las llamadas.

Guardar una conexión

PUT/v1/connections/{name}

Crea la conexión, o la reemplaza si el nombre ya existe. Los nombres siguen las mismas reglas que los nombres de flujos de trabajo. Solo propietario o administrador.

Cuerpo

typestringobligatorio

http o mcp.

urlstringobligatorio

URL base HTTPS de la API, o el endpoint Streamable HTTP del servidor MCP. Debe resolverse a una dirección pública.

authobject

Cómo autenticarse. Omítelo para no usar autenticación.

allowed_methodsstring[]

Conexiones HTTP: métodos que pueden usar las ejecuciones, como ["GET"]. Vacío permite todos.

allowed_toolsstring[]

Conexiones MCP: nombres de herramientas a las que pueden llamar las ejecuciones. Vacío permite todas.

instructionsstring

Cómo debe usar la API el agente: endpoints, formatos de solicitud, convenciones. Se muestran al agente, así que no incluyas secretos. Hasta 4000 caracteres.

El objeto auth

typestring

none, bearer, header, basic u oauth2.

tokenstring

Para bearer y header.

headerstring

Para header: el nombre de la cabecera, como X-API-Key.

username, passwordstring

Para basic. El nombre de usuario no puede contener dos puntos.

client_idstring

Para oauth2. Obligatorio, junto con authorization_url y token_url.

client_secretstring

Para clientes oauth2 que lo tengan.

authorization_url, token_urlstring

Los endpoints OAuth del proveedor. HTTPS.

token_auth_methodstring

client_secret_basic, client_secret_post o none.

scopesstring[]

Ámbitos (scopes) que se solicitan.

resourcestring

Indicador de recurso opcional que se envía con la solicitud de autorización.

{
  "type": "http",
  "url": "https://api.example.com/v2",
  "auth": { "type": "header", "header": "X-API-Key", "token": "sk_live_…" },
  "allowed_methods": ["GET"],
  "instructions": "Look up a payment with GET /v1/payments/{id}. Amounts are in cents."
}

La respuesta es {"name": "...", "type": "..."}. Ephemeral valida la URL y el formato de las credenciales antes de guardar.

Para actualizar una conexión sin volver a enviar sus secretos, guárdala sin los campos secretos y con el mismo auth.type. Se conservan el token, la contraseña, el secreto de cliente y los tokens OAuth almacenados. Cambiar auth.type reemplaza por completo la autenticación.

Listar conexiones

GET/v1/connections

Solo propietario o administrador. Devuelve todas las conexiones con name, type, url, allowed_methods, allowed_tools, authenticated y las partes no secretas de auth.

Obtener una conexión

GET/v1/connections/{name}

Solo propietario o administrador. Devuelve la configuración sin las credenciales y con los valores de consulta de las URL ocultos.

Eliminar una conexión

DELETE/v1/connections/{name}

Solo propietario o administrador. Devuelve 204 No Content.

Una ejecución que haga referencia a una conexión eliminada, directamente o a través de un flujo de trabajo, se rechaza al crearla. Una ejecución que ya está en curso pierde el acceso la próxima vez que llame a la conexión.

Autorizar una conexión OAuth

POST/v1/connections/{name}/oauth/start

Solo propietario o administrador. Devuelve {"url": "..."}, la página de autorización del proveedor.

Abre la URL en un navegador y aprueba el acceso. El proveedor redirige a /oauth/callback en el motor, Ephemeral intercambia el código y guarda los tokens, y el navegador vuelve al panel. Cada URL funciona una sola vez. Registra https://app.ephemer.al/oauth/callback como URI de redirección en tu proveedor, o tu propio dominio en una instalación autoalojada.

Si el ID de cliente o los endpoints OAuth de la conexión cambian mientras la autorización está en curso, el callback se rechaza con 409; empieza de nuevo. La CLI lo hace en un solo paso con ephemeral oauth connect NAME.

Catálogo de conexiones

GET/v1/catalog/connections

Disponible para todos los roles. Lista las conexiones a las que pueden hacer referencia las ejecuciones, sin URL ni ajustes de autenticación.

JSON

[
  { "name": "docs-mcp", "type": "mcp", "allowed_methods": [], "allowed_tools": ["search", "get_document"], "authenticated": true },
  { "name": "payments-api", "type": "http", "allowed_methods": ["GET"], "allowed_tools": null, "authenticated": true }
]

El acceso a las conexiones guardadas es de toda la organización. Cualquier miembro puede usar cualquier conexión guardada por su nombre; no hay permisos por miembro.