연결 · Ephemeral 문서

HTTP 연결과 MCP 연결을 저장하고, OAuth 연결을 인가하고, 실행이 사용할 수 있는 연결을 조회합니다. 연결을 설정하려면 admin 키나 로그인한 소유자 또는 관리자가 필요하며, 멤버는 카탈로그를 읽을 수 있습니다. 호출이 중개되는 방식은 연결을 참고하세요.

연결 저장

PUT/v1/connections/{name}

연결을 만들거나, 같은 이름이 있으면 교체합니다. 이름 규칙은 워크플로 이름과 같습니다. 소유자 또는 관리자만 가능합니다.

본문

typestring필수

http 또는 mcp.

urlstring필수

API의 HTTPS 기본 URL 또는 MCP 서버의 Streamable HTTP 엔드포인트. 공용 주소로 해석되어야 합니다.

authobject

인증 방법. 생략하면 인증 없음.

allowed_methodsstring[]

HTTP 연결: 실행이 사용할 수 있는 메서드. 예: ["GET"]. 비어 있으면 모두 허용합니다.

allowed_toolsstring[]

MCP 연결: 실행이 호출할 수 있는 도구 이름. 비어 있으면 모두 허용합니다.

instructionsstring

에이전트가 API를 사용하는 방법: 엔드포인트, 요청 형식, 관례. 에이전트에게 표시되므로 비밀 값을 넣지 마세요. 최대 4,000자.

auth 객체

typestring

none, bearer, header, basic, oauth2 중 하나.

tokenstring

bearer와 header용.

headerstring

header용: X-API-Key 같은 헤더 이름.

username, passwordstring

basic용. username에는 콜론을 넣을 수 없습니다.

client_idstring

oauth2용. authorization_url, token_url과 함께 필수입니다.

client_secretstring

시크릿이 있는 oauth2 클라이언트용.

authorization_url, token_urlstring

공급자의 OAuth 엔드포인트. HTTPS.

token_auth_methodstring

client_secret_basic, client_secret_post, none 중 하나.

scopesstring[]

요청할 스코프.

resourcestring

인가 요청과 함께 보내는 선택적 리소스 지시자.

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

응답은 {"name": "...", "type": "..."}입니다. Ephemeral은 저장하기 전에 URL과 자격 증명 형식을 검증합니다.

비밀 값을 다시 보내지 않고 연결을 수정하려면, 비밀 필드를 뺀 채 같은 auth.type으로 저장하세요. 저장된 토큰, 비밀번호, 클라이언트 시크릿, OAuth 토큰은 유지됩니다. auth.type을 바꾸면 인증이 완전히 교체됩니다.

연결 목록

GET/v1/connections

소유자 또는 관리자만 가능합니다. 모든 연결을 name, type, url, allowed_methods, allowed_tools, authenticated, 그리고 auth의 비밀이 아닌 부분과 함께 반환합니다.

연결 조회

GET/v1/connections/{name}

소유자 또는 관리자만 가능합니다. 자격 증명을 제거하고 URL의 쿼리 값을 가린 설정을 반환합니다.

연결 삭제

DELETE/v1/connections/{name}

소유자 또는 관리자만 가능합니다. 204 No Content를 반환합니다.

삭제된 연결을 직접 또는 워크플로를 통해 참조하는 실행은 생성할 때 거부됩니다. 이미 진행 중인 실행은 다음에 그 연결을 호출할 때 접근 권한을 잃습니다.

OAuth 연결 인가

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

소유자 또는 관리자만 가능합니다. 공급자의 인가 페이지인 {"url": "..."}를 반환합니다.

브라우저에서 URL을 열어 접근을 승인하세요. 공급자가 엔진의 /oauth/callback으로 리디렉션하면 Ephemeral이 코드를 교환해 토큰을 저장하고, 브라우저는 대시보드로 돌아갑니다. URL은 한 번만 사용할 수 있습니다. 공급자에 리디렉션 URI로 https://app.ephemer.al/oauth/callback을 등록하세요. 셀프 호스팅 설치본에서는 자체 도메인을 등록합니다.

인가가 진행되는 동안 연결의 클라이언트 ID나 OAuth 엔드포인트가 바뀌면 콜백이 409로 거부되므로 처음부터 다시 시작하세요. CLI에서는 ephemeral oauth connect NAME으로 이 과정을 한 번에 처리합니다.

연결 카탈로그

GET/v1/catalog/connections

모든 역할이 사용할 수 있습니다. URL과 인증 설정 없이 실행이 참조할 수 있는 연결을 나열합니다.

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

저장된 연결에 대한 접근은 조직 전체에 적용됩니다. 모든 멤버가 저장된 모든 연결을 이름으로 사용할 수 있으며, 멤버별 권한 부여는 없습니다.