연결

연결을 사용하면 에이전트가 실행 중에 HTTP API나 MCP 서버를 호출할 수 있습니다. 자격 증명은 Ephemeral이 보관하고 호출도 Ephemeral이 수행합니다. 워커는 토큰, 비밀번호, URL 비밀 값을 보지 못합니다.

호출이 동작하는 방식

실행에 허용한 연결마다 에이전트가 호출할 수 있는 도구가 생깁니다. 에이전트가 도구를 호출하면 워커는 해당 실행에서만 유효한, 수명이 짧은 토큰과 함께 요청을 Ephemeral로 보냅니다. Ephemeral은 실행에 그 연결이 허용되었는지, 메서드나 도구가 허용되었는지 확인한 뒤 자격 증명을 추가해 요청을 보내고, 응답에서 자격 증명 값을 제거한 다음 돌려줍니다. 호출은 모두 connection 이벤트로 기록됩니다.

HTTP 연결에서 에이전트는 메서드, 연결 URL 기준의 상대 경로, 선택적 본문을 제공합니다. 에이전트가 폼이나 XML 같은 다른 콘텐츠 유형을 지정하고 본문을 텍스트로 보내지 않는 한 본문은 JSON으로 전송됩니다. MCP 연결에서는 에이전트가 서버의 도구를 확인하고 직접 호출합니다.

에이전트에게 사용법 알려 주기

HTTP 연결은 에이전트에게 기본 URL만 제공하므로, instructions에 API를 설명해 주세요. 작업에 필요한 엔드포인트, 요청 형식, ID의 모양, 따라야 할 규칙 등입니다. 에이전트는 이 내용을 연결의 도구와 상시 지침에서 볼 수 있습니다. 실행에서는 저장된 연결의 instructions를 자체 내용으로 바꿀 수 있습니다.

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

저장된 연결과 인라인 연결

저장된 연결은 조직에 한 번 저장해 두고 이름으로 참조합니다. 소유자와 관리자가 대시보드의 연결에서 또는 PUT /v1/connections/{name}로 만듭니다. 실행과 워크플로는 ref로 참조합니다.

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

payments 같은 키는 이 실행에서 에이전트에게 보이는 이름입니다. 실행 요청에 URL과 자격 증명을 포함해 연결을 인라인으로 정의할 수도 있습니다. 인라인 자격 증명은 해당 실행과 함께 암호화되어 저장되고, 다시 읽을 때 정의에서 제거되므로 다시 실행하려면 자격 증명을 다시 제공해야 합니다. 저장된 연결을 쓰면 이런 번거로움이 없습니다.

접근 범위 좁히기

allowed_methods는 HTTP 연결이 허용하는 HTTP 메서드를 제한합니다. allowed_tools는 MCP 서버에서 호출할 수 있는 도구를 제한합니다. 목록이 비어 있거나 없으면 모두 허용합니다.

실행에서 저장된 연결의 범위를 더 좁힐 수 있습니다. 실행에는 두 목록에 모두 있는 메서드나 도구만 주어집니다. 두 목록에 겹치는 항목이 없으면 실행 요청이 거부되므로, 실행이 저장된 연결이 허용하는 것보다 더 많은 접근 권한을 갖는 일은 없습니다.

인증

OAuth의 경우 소유자나 관리자가 공급자의 클라이언트 ID, 인증 URL, 토큰 URL로 연결을 저장한 다음 브라우저에서 한 번 인가합니다. Ephemeral은 토큰을 저장하고, 공급자가 리프레시 토큰을 발급했다면 액세스 토큰이 만료되기 전에 갱신합니다. 공급자에 리디렉션 URI로 https://app.ephemer.al/oauth/callback을 등록하세요. 셀프 호스팅 설치본에서는 자체 도메인을 사용합니다.

네트워크 규칙

• 연결 URL은 HTTPS를 사용해야 하며 공용 인터넷 주소로 해석되어야 합니다.
• 리디렉션은 따라가지 않습니다.
• HTTP 연결은 GET, POST, PUT, PATCH, DELETE, HEAD를 허용하며 응답은 최대 1 MiB까지 반환합니다. 에이전트는 응답 전체를 받고, 실행 기록에는 최대 256 KiB까지 보관하며 줄인 위치를 표시합니다.
• MCP 서버에는 Streamable HTTP로 접속합니다. 에이전트는 도구를 조회하고 호출할 수 있으며, 그 밖의 MCP 기능은 거부됩니다.
• 호스팅 서비스에서 워커의 네트워크는 Ephemeral에만 닿습니다. 외부로 나가는 모든 요청은 연결을 거치며, 실행에 웹 액세스가 있다면 그것을 거칩니다.