문서
API 레퍼런스대시보드로그인시작하기
문서
대시보드로그인시작하기

도구와 운영

MCP 서버

Claude 등 AI 에이전트를 Ephemeral에 연결합니다.

Ephemeral은 Model Context Protocol(MCP) 서버를 제공합니다. Claude, ChatGPT, 편집기 안의 에이전트 같은 AI 에이전트가 실행을 시작하고, 결과를 기다리고, 워크플로를 직접 읽을 수 있습니다. REST API와 같은 API 키, 역할, 예산, 검증이 적용됩니다. 워크플로를 저장하고 삭제하며, 일정을 관리하고, 파일 목록을 조회할 수도 있어서 에이전트가 반복 작업을 처음부터 끝까지 설정할 수 있습니다.

OAuth로 로그인

MCP 인증을 지원하는 클라이언트는 URL https://app.ephemer.al/mcp만 있으면 됩니다. 클라이언트는 서버의 401 응답과 보호 리소스 메타데이터에서 Ephemeral의 로그인 위치를 찾아 스스로 등록하고, 로그인하고 조직을 고른 뒤 승인하는 페이지를 엽니다. 이후 클라이언트는 유효 기간 1시간의 액세스 토큰과 리프레시 토큰을 보관하므로, 취소하기 전까지 다시 묻지 않습니다.

  • 접근 권한은 선택한 조직에 대해, 승인한 역할(member 또는 admin)로 부여됩니다. admin은 조직의 소유자와 관리자만 부여할 수 있으며, 일정을 만들거나 바꾸거나 삭제하는 경우를 제외하면 멤버 역할로 충분하며, 일정 변경에는 admin이 필요합니다.
  • 토큰은 Ephemeral의 API(https://app.ephemer.al)에서만 작동하며 다른 서비스에는 쓸 수 없습니다.
  • 연결된 앱은 계정 페이지의 '승인된 앱'에서 언제든지 확인하고 취소할 수 있습니다.
  • 인증 서버 메타데이터는 https://ephemer.al/.well-known/oauth-authorization-server에 있습니다. 클라이언트는 PKCE(S256)를 사용해야 합니다.
셀프 호스팅 설치에서는 API 키만 사용할 수 있습니다.

API 키로 연결

대시보드의 키 메뉴에서 API 키를 만드세요. 실행, 워크플로, 파일에는 멤버 키면 충분합니다. 에이전트가 일정도 만들고 바꾸고 삭제해야 한다면 관리자 키를 사용하세요. 서버 주소는 https://app.ephemer.al/mcp이며 Streamable HTTP 전송을 사용합니다. 모든 요청에 키를 베어러 토큰으로 보냅니다.

Claude Code

서버를 한 번 추가하면 이후 모든 세션에서 사용할 수 있습니다.

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

Cursor, VS Code 등 HTTP를 지원하는 클라이언트

대부분의 클라이언트는 MCP 설정에서 헤더가 있는 원격 서버를 받습니다.

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

Claude Desktop

Claude Desktop은 설정 파일(claude_desktop_config.json)로 로컬 서버를 시작합니다. mcp-remote 브리지가 원격 서버에 연결하고 헤더를 전달합니다.

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" }
    }
  }
}
셀프 호스팅 환경에서는 같은 엔드포인트가 엔진 URL(예: https://ephemeral.example.com/mcp)에서 제공되며, 그 환경의 키를 사용합니다.

도구

각 도구에는 클라이언트가 모델에 보여 주는 입력 스키마가 있고, 결과는 텍스트와 구조화된 콘텐츠로 함께 반환됩니다. REST API가 오류로 보고하는 실패는 같은 메시지의 도구 오류로 반환됩니다.

도구기능
create_run프롬프트 또는 저장된 워크플로로 실행을 시작합니다. 입력, 모델, 파일, 연결, 웹 접근, 셸, 제한 시간, 비용 한도, 제로 데이터 보존을 지정할 수 있습니다. 대기 중인 실행을 반환합니다. idempotency_key를 쓰면 재시도해도 안전합니다.
get_run실행을 읽습니다. 상태, 출력, 오류, 비용, 청구가 아직 확정 대기 중인지 여부를 포함합니다. 청구가 대기 중인 동안 cost_micros는 잠정 금액이며 최종 비용보다 대개 높고, 결과에 cost_final: false가 표시됩니다. cost_final이 true일 때만 비용을 안내하세요.
wait_for_run실행이 끝날 때까지 최대 60초 기다린 뒤 실행을 반환합니다. 아직 진행 중이면 다시 호출하세요. 실행이 끝난 뒤에는 청구가 확정될 때까지도 기다리므로 반환된 비용이 최종 금액입니다(cost_final: true). 그 전에 시간이 다 되면 비용은 잠정 금액입니다.
list_runs실행을 최신순으로 나열합니다. 상태 필터와 커서를 쓸 수 있습니다.
cancel_run끝나지 않은 실행을 취소합니다.
list_workflows저장된 워크플로를 description, input_schema, output_schema와 함께 나열합니다. 에이전트는 프롬프트를 읽지 않고도 각 워크플로가 기대하고 반환하는 내용을 확인할 수 있습니다.
get_workflow워크플로 정의 하나를 읽습니다. 자격 증명은 포함되지 않습니다.
list_models모델을 찾습니다. 간결한 목록(ID, 이름, 컨텍스트 길이, 100만 토큰당 입력·출력 가격, 제로 데이터 보존 여부)과 전체 개수를 반환합니다. 인수: query(ID 또는 이름의 일부, 대소문자 구분 없음), limit(기본 25, 최대 100), zero_data_retention(지원하는 모델만), model(한 모델의 전체 정보).
list_connections실행에서 쓸 수 있는 저장된 연결. URL과 시크릿은 포함되지 않습니다.
save_workflow워크플로를 만들거나 같은 이름의 워크플로를 교체합니다. 프롬프트, 모델, 파일, 연결, 웹 접근, 셸, 제한 시간, 제로 데이터 보존을 지정할 수 있습니다. 연결은 저장된 연결에 대한 참조만 가능합니다. 설명과 입력·출력용 JSON Schema도 받을 수 있습니다.
delete_workflow저장된 워크플로를 삭제합니다.
list_schedules일정 목록을 조회합니다(워크플로별 필터 가능). 다음 시작 시각과 마지막 결과가 포함됩니다.
get_schedule일정 하나를 읽습니다.
create_schedule저장된 워크플로를 cron 일정과 시간대에 따라 시작합니다. 입력과 비용 한도는 선택 사항입니다. 관리자 키가 필요합니다.
update_schedule일정을 바꾸거나 enabled로 일시 중지·재개합니다. 관리자 키가 필요합니다.
delete_schedule일정을 삭제합니다. 관리자 키가 필요합니다.
preview_schedulecron 표현식을 검사하고 저장하지 않은 채 다음 시작 시각 다섯 개를 반환합니다.
run_schedule일정의 워크플로를 지금 바로 시작하고 대기 중인 실행을 반환합니다.
list_files조직에 저장된 파일 목록을 조회합니다(읽기 전용).

사용해 보기

엔드포인트는 JSON-RPC 2.0 메시지를 POST로 받습니다. 보통은 클라이언트가 처리하며, curl로 호출하면 다음과 같습니다.

터미널
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}}}'

워크플로를 저장하고 일정 잡기

에이전트는 호출 두 번으로 작업을 반복 작업으로 바꿀 수 있습니다. 먼저 다음 인자로 save_workflow를 호출합니다.

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
}

그런 다음 create_schedule(관리자 키)을 호출합니다. 여기서는 매주 월요일 마드리드 시간 09:00입니다. 먼저 preview_schedule로 다음 시작 시각을 확인할 수 있습니다.

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

역할

대부분의 도구는 멤버 키가 REST API에서 이미 할 수 있는 작업이며, 일정 도구도 REST API와 같은 규칙을 따릅니다. 일정 조회, 미리 보기, 즉시 실행은 멤버 키로 가능하지만 create_schedule, update_schedule, delete_schedule에는 관리자 또는 소유자 키가 필요하며, 그렇지 않으면 도구 오류(상태 403)가 반환됩니다. 키를 만들거나 연결을 바꾸거나 결제를 관리하는 도구는 없습니다. 키는 조직도 결정합니다. 실행은 그 조직에 청구되고 실행 내역에 표시됩니다.

안전

  • 키가 없으면 아무것도 실행되지 않습니다. 초기화와 도구 목록은 키 없이도 받을 수 있습니다(어차피 공개된 내용입니다). 도구 호출에는 항상 유효한 키가 필요하며, 키가 없으면 401을 받습니다.
  • OAuth 액세스 토큰은 1시간 후 만료되고, 조직 하나와 승인된 역할로 제한되며, 계정 페이지에서 언제든지 취소할 수 있습니다.
  • 예산이 적용됩니다. 모든 실행에는 비용 한도(max_cost_micros 또는 조직 기본값)가 있고 API와 같은 잔액 확인이 이루어집니다.
  • 연결은 저장된 참조입니다. 에이전트는 조직이 저장한 연결을 이름으로만 지정할 수 있고, allowed_methods(예: GET만)나 allowed_tools로 범위를 좁힐 수 있습니다. URL이나 자격 증명을 직접 줄 수는 없습니다.
  • 제로 데이터 보존은 실행마다 사용할 수 있습니다. 그 실행의 출력은 처음 읽을 때 해제됩니다.
  • POST만 받습니다. 세션도, 서버가 먼저 보내는 메시지도 없습니다.

프로토콜

프로토콜 버전 2025-11-25, 2025-06-18, 2025-03-26을 지원하며, 클라이언트가 요청한 버전으로 응답합니다. GET과 DELETE는 405를 반환합니다. 디스커버리 문서는 /.well-known/mcp/server-card.json에 게시됩니다.

© 2026 Ephemeral제작: erni.works
esc

“”와(과) 일치하는 항목이 없습니다.