Crevio

npx add-mcp 'https://mcp.crevio.co/mcp'

MCP 서버

Claude, Cursor 또는 MCP 호환 에이전트를 Crevio 계정에 연결하세요. ask_crevio로 Crevio 에이전트에 작업을 위임하고, 실행을 추적하고 이어가며, 전체 Crevio API와 연동에 대해 스크립트를 실행할 수 있습니다.

Crevio MCP 서버를 사용하면 모든 MCP 호환 에이전트가 Crevio에 작업을 위임할 수 있으며, 직접 제어가 필요할 때는 전체 Crevio API와 연동에 대해 스크립트를 실행할 수 있습니다. 하나의 서버, 두 가지 표면:

• 위임 — ask_crevio은 Crevio 에이전트에게 평범한 영어로 작업을 맡기고("jane@…의 마지막 주문을 환불해 줘", "이번 주 게시물을 작성하고 예약해 줘") 결과를 반환합니다. 긴 작업은 백그라운드에서 실행되며, run으로 추적하고, 대화를 이어가고, 승인 게이트에 응답하고, 트랜스크립트를 읽을 수 있습니다.
• 스크립트 — list_integrations과 list_integration_tools는 스크립트가 호출할 수 있는 항목을 보여주고, run_script은 계정의 Crevio 컴퓨터에서 모든 REST 엔드포인트와 연결된 연동에 대해 JavaScript를 실행하며, API와 동일한 권한 부여 및 검증을 적용합니다.

URL	https://mcp.crevio.co/mcp
전송	Streamable HTTP (상태 비저장 — 모든 요청은 자체 완결적)
인증	Authorization: Bearer <API token> — REST에 사용하는 것과 동일한 API 토큰 — 또는 커스텀 헤더만 설정할 수 있는 클라이언트의 경우 X-Api-Key: <API token>. OAuth 2.1도 지원됩니다. 연결을 참조하세요.
검색	https://mcp.crevio.co/mcp/server-card

[!NOTE]

Crevio의 에이전트 모델이 처음이신가요? AI & 에이전트 개요에서 MCP, Tasks, Events가 어떻게 함께 작동하는지 확인하세요. 내부적으로 위임된 작업은 하나의 run을 가진 Task이므로, 여기의 모든 내용은 대시보드와 /v1/tasks 및 /v1/task_runs을 통해서도 확인할 수 있습니다.

설정

1. API 토큰 생성

Crevio에서 Settings → Developers → API tokens로 이동하여 토큰을 생성하세요. MCP 연결은 그 뒤에 있는 토큰과 정확히 동일한 권한을 가집니다 — 계정이 할 수 있는 모든 것.

2. 클라이언트 구성

Claude Code

claude mcp add --transport http crevio https://mcp.crevio.co/mcp \
  --header "Authorization: Bearer $CREVIO_API_TOKEN"

Claude Desktop / Cursor / 기타 클라이언트 — 클라이언트의 MCP 구성(claude_desktop_config.json, ~/.cursor/mcp.json, …)에 추가하세요:

{
  "mcpServers": {
    "crevio": {
      "url": "https://mcp.crevio.co/mcp",
      "headers": {
        "Authorization": "Bearer <CREVIO_API_TOKEN>"
      }
    }
  }
}

클라이언트별 단계, OAuth, 원시 curl 예시는 연결 페이지에 있습니다.

3. whoami로 확인

연결된 에이전트에게 whoami을 호출하도록 요청하세요. 토큰 뒤의 계정과 사용자, 자격 증명, 플랜, 크레딧 잔액, 속도 제한, 대기 제한, 도구 목록을 반환합니다 — 인자도, 부작용도 없습니다. whoami이 작동하면 나머지도 모두 작동합니다.

{
  "object": "whoami",
  "account": { "id": "acct_7k2m…", "name": "Jane's Studio", "slug": "janes-studio" },
  "user": { "id": "user_9qx…", "email": "jane@example.com", "name": "Jane Doe" },
  "credential": { "type": "api_key", "id": "token_3fa…", "name": "Claude Desktop", "expires_at": null },
  "plan": "Pro",
  "credits": 1840,
  "rate_limit": { "limit": 600, "window_seconds": 60 },
  "limits": { "ask_timeout_default_seconds": 300, "ask_timeout_max_seconds": 300, "message_max_chars": 10000 },
  "tools": ["whoami", "ask_crevio", "start_chat", "wait_for_run", "get_run", "list_chats", "get_chat", "send_message", "resolve_approvals", "cancel_run", "list_runs", "list_messages", "list_integrations", "list_integration_tools", "run_script", "wait_for_script_run", "get_script_run", "cancel_script_run"]
}

권장 워크플로

일회성 작업: ask_crevio

판단이나 작성이 필요한 작업에 사용하세요. 한 번의 호출로 run을 시작하고, 대기하고, result에 에이전트의 최종 답변이 포함된 run을 반환합니다. 각 작업은 30초에서 몇 분에 이르는 전체 에이전트 run입니다 — 데이터를 직접 읽거나 변경하려면 스크립트가 몇 초면 됩니다.

{
  "name": "ask_crevio",
  "arguments": {
    "message": "Which three products made the most revenue this month, and how does that compare to last month?",
    "idempotency_key": "monthly-top-products-2026-08"
  }
}

{
  "object": "task_run",
  "id": "trun_8d1k…",
  "task_id": "task_2nq…",
  "task_name": "Which three products made the most revenue this month, and how does that…",
  "chat_id": "aichat_5pz…",
  "status": "completed",
  "summary": "Top three by revenue this month: …",
  "result": "Top three by revenue this month:\n1. Lightroom Presets Vol. 2 — $2,140 (+18% vs July)\n2. …",
  "error_message": null,
  "pending_approval_ids": [],
  "credits_consumed": 4,
  "started_at": "2026-08-20T09:14:02Z",
  "completed_at": "2026-08-20T09:14:31Z",
  "created_at": "2026-08-20T09:14:01Z"
}

• 대기 시간은 클라이언트가 스트리밍 응답을 수락할 때(MCP 클라이언트가 기본적으로 보내는 Accept: text/event-stream) 기본값이자 최대값이 300초이며, 그렇지 않으면 90초입니다. 스트리밍 응답은 대기하는 동안 10초마다 진행 알림을 보냅니다 — 이를 받으려면 _meta에 progressToken를 전달하세요. 더 적게 대기하려면 timeout_seconds을 전달하세요.
• 대기가 끝났을 때 run이 여전히 진행 중이라면, 응답은 오류가 아닙니다: wait_timed_out: true이 있는 run입니다. 계속 대기하려면 해당 id으로 wait_for_run를 호출하고, ask_crevio을 다시 호출하지 마세요 — 그러면 작업이 두 번째로 시작됩니다. 아무것도 손실되지 않으며, run은 Crevio 측에서 계속됩니다.
• idempotency_key는 재시도를 안전하게 만듭니다: 동일한 키는 다른 run을 시작(및 비용 지불)하는 대신 첫 번째 호출이 시작한 run을 반환합니다. 항상 하나를 전달하세요.
• speed: "faster"은 에이전트가 덜 생각하게 하여, 깊이보다 빠른 답변이 더 중요한 단순 작업에 적합합니다. 기본값은 smarter입니다.
• response_format는 프로그램이 산문 대신 객체를 필요로 할 때 JSON Schema(또는 OpenAI의 {type: "json_schema", json_schema: {schema}})를 받습니다. 에이전트에게 스키마가 전달되며, 완료된 run은 스키마에 대해 검증된 파싱된 값을 json에, 또는 실패 이유를 json_error에 담습니다. start_chat와 send_message도 이를 받습니다.
• run 중에 에이전트가 전달한 파일은 artifacts로 반환됩니다. 아티팩트의 id를 get_file_download_url으로 다운로드 링크로 교환하세요.
• approval_mode는 기본적으로 autonomous입니다. supervised은 각 게이트된 쓰기 전에 run을 needs_input에서 일시 중지시켜 pending_approval_ids에 응답할 때까지 기다립니다(승인할 것이 없는 run은 제안과 함께 완료되며, 이에 대해 실행하려면 send_message로 응답하세요). read_only은 쓰기를 금지합니다.

장기 실행 작업: start_chat → wait_for_run → send_message

차단하고 싶지 않은 모든 것 — 사이트 빌드, 리서치 작업, 대량 마이그레이션:

1. **start_chat**는 작업을 대기열에 넣고 즉시 run을 반환합니다.
2. wait_for_run(제한적) 또는 get_run(즉시)를 status이 completed, failed, 또는 needs_input이 될 때까지 사용하세요.
3. **send_message**은 대화를 이어갑니다 — 후속 지시, 수정, 에이전트가 한 질문에 대한 답변. 에이전트는 컨텍스트를 유지합니다. 완료된 run에서는 동일한 대화에서 새 run을 시작하고, needs_input run에서는 이를 재개합니다. 동일한 호출에서 응답을 기다리려면 timeout_seconds을, 재시도된 호출이 메시지를 두 번 보내는 대신 첫 번째 호출이 시작한 run(reused: true)을 반환하도록 idempotency_key를 전달하세요.
4. **resolve_approvals**은 run이 연동 작업(pending_approval_ids이 있는 needs_input)에서 일시 중지되었을 때 사용하세요 — 모든 대기 중인 id를 한 번에 승인하거나 거부하면 run이 재개됩니다.
5. **cancel_run**는 대기 중, 실행 중, 또는 대기 중인 run을 중지합니다.

chat은 대화이고 run은 그 안의 한 턴의 작업입니다. list_runs은 계정의 모든 run을 보여주며(하나의 대화의 run만 보려면 chat_id 전달) — 위임된 작업과 예약된 Tasks 모두 — list_chats와 get_chat은 대화 자체를 탐색하고, list_messages는 최종 답변뿐만 아니라 chat의 전체 트랜스크립트를 읽습니다.

스크립트: run_script

연결된 에이전트가 위임하는 대신 Crevio 자체를 운영하고 싶거나 정확한 데이터를 돌려받아야 할 때 스크립트를 작성합니다. run_script은 에이전트 턴 없이 bun으로 계정의 Crevio 컴퓨터에서 JavaScript를 실행합니다. 스크립트는 Crevio API와 계정이 연결한 모든 연동을 호출하고, 원하는 만큼 호출을 연결하고, 데이터가 반환되기 전에 변환할 수 있습니다.

검색

list_integrations은 스크립트가 호출할 수 있는 모든 네임스페이스의 이름을 나열합니다: crevioApi(전체 Crevio API, 작업당 하나의 함수), platform(Crevio 자체 도구), 그리고 연결된 연동당 하나(pdGmail, mcpLinear, …). list_integration_tools는 하나의 네임스페이스의 함수를 나열하며, 각각 TypeScript 타입으로 된 매개변수, 읽기 전용 여부, 승인 필요 여부, 그리고 채우면 run_script이 수락하는 스니펫을 포함합니다. crevioApi에는 수백 개의 작업이 있으므로 search로 좁히세요:

{ "namespace": "crevioApi", "search": "price variant create" }

실행

tools.<namespace>.<function>(args)은 호출을 합니다. 최상위 await이 작동하며, 모든 호출은 결과를 반환하고 실패 시 예외를 던지며, 스크립트의 마지막 표현식이 결과입니다.

const product = await tools.crevioApi.createProduct({ body: { name: "My Course", slug: "my-course" } });
await tools.crevioApi.createPriceVariant({
  body: { product: product.id, name: "Standard", amount_type: "fixed", amount: 4900, currency: "usd", billing_type: "one_time" },
});
await tools.crevioApi.updateProduct({ id_or_slug: product.id, body: { status: "active" } });
product.id

읽기는 매개변수를 직접 받고(listOrders({ status: "succeeded" })), 쓰기는 요청 본문을 body 아래에 전달하며 경로 매개변수는 그 옆에 둡니다.

값은 args(최대 16개 문자열)으로 전달하며, 스크립트는 전역 args에서 이를 읽습니다. 전역 outputDir로 명명된 디렉터리에 작성된 파일은 run에서 artifacts으로 반환됩니다:

const { data } = await tools.crevioApi.listOrders({ status: "succeeded", limit: Number(args[0]) });
await Bun.write(`${outputDir}/orders.csv`, data.map((o) => o.id).join("\n"));
data.length

run은 스크립트 run(srun_…)을 반환합니다: 그 status(queued → in_progress → completed, failed, cancelled 또는 timed_out), result, 스크립트가 output에 출력한 내용, 그 error, 그리고 calls — HTTP 상태와 함께 수행한 모든 도구 호출로, 오류를 잡은 스크립트도 어떤 호출이 실패했는지 보여줍니다. run_script은 ask_crevio이 허용하는 만큼 대기합니다(스트리밍 응답에서 300초, 그렇지 않으면 90초; 더 적게 대기하려면 wait_seconds 전달). 더 오래 걸리는 run은 wait_timed_out: true과 그 id와 함께 반환됩니다 — 오류가 아닙니다: wait_for_script_run으로 계속 대기하세요. 동일한 idempotency_key를 전달하지 않는 한 run_script을 다시 호출하면 스크립트가 두 번 실행됩니다.

crevioApi 호출은 api.crevio.co와 동일한 컨트롤러를 거치므로 API 규칙이 그대로 적용됩니다: 연관은 접두사 id가 있는 맨 이름(product_id이 아닌 product: "prod_abc"), 금액은 센트 단위, 목록 엔드포인트는 {object: "list", data: [...]}을 반환하며, 제품은 active이 되기 전에 가격 변형이 필요합니다. 코스 및 기타 콘텐츠는 제품이 아닌 경험(listExperiences)입니다.

제한:

• 대상: 계정 관리자만. 스크립트는 전체 팀이 공유하는 컴퓨터에서 귀하(개인 연동 포함)로서 실행됩니다.
• 시간 제한: timeout_seconds은 1에서 600까지(기본값 300). 컴퓨터가 먼저 깨어나야 할 수 있으며, 이는 최대 약 20초를 추가할 수 있습니다.
• 동시성: 사용자당 최대 4개의 run, 계정당 최대 8개.
• 승인: 스크립트는 중지하고 승인을 요청할 수 없습니다. 승인이 필요한 호출(목록에서 requires_approval)은 approval_required로 실패합니다: 해당 작업을 Settings → Integrations에서 자동으로 실행하도록 설정하거나, 대신 ask_crevio으로 작업을 위임하세요.
• 취소: queued run만 취소할 수 있습니다. 실행 중인 스크립트는 끝까지 또는 시간 제한까지 실행됩니다.
• 출력 파일: run당 최대 20개, 각각 최대 50 MB. 더 큰 파일은 제외됩니다.

전체 도구 참조

도구	목적	인수
whoami	계정, 사용자, 자격 증명, 플랜, 크레딧, 한도 및 도구를 식별합니다	—
ask_crevio	작업을 위임하고 결과를 기다립니다	message(필수), timeout_seconds, approval_mode, speed, response_format, idempotency_key
start_chat	기다리지 않고 작업을 위임합니다	message(필수), approval_mode, speed, response_format, idempotency_key
wait_for_run	실행이 완료될 때까지 (제한된 시간 동안) 기다립니다	run_id(필수), timeout_seconds
get_run	실행의 상태, 요약, 대기 중인 승인 및 최종 응답을 가져옵니다	run_id(필수)
list_chats	계정의 채팅을 최신순으로 나열합니다	search, limit, starting_after, ending_before
get_chat	채팅의 제목, 종류 및 최신 실행을 가져옵니다	chat_id(필수)
send_message	채팅을 계속합니다. 선택적으로 응답을 기다립니다	chat_id, message(필수), timeout_seconds, response_format, idempotency_key
resolve_approvals	실행이 일시 중지된 통합 작업을 승인/거부합니다	run_id, approvals: [{id, approved, reason}](필수)
cancel_run	대기 중, 실행 중 또는 대기 상태인 실행을 중지합니다	run_id(필수)
list_runs	계정의 실행을 최신순으로 나열합니다	status, task_id, chat_id, limit, starting_after, ending_before
list_messages	채팅의 메시지를 오래된 순으로 읽습니다	chat_id(필수), limit, ending_before
list_integrations	스크립트가 호출할 수 있는 모든 네임스페이스의 이름을 나열합니다	—
list_integration_tools	네임스페이스의 함수를 매개변수 및 스니펫과 함께 나열합니다	namespace(필수), search, limit, offset
run_script	계정의 컴퓨터에서 JavaScript를 실행하고 기다립니다	code(필수), args, timeout_seconds, wait_seconds, idempotency_key
wait_for_script_run	스크립트 실행이 완료될 때까지 (제한된 시간 동안) 기다립니다	run_id(필수), wait_seconds
get_script_run	스크립트 실행의 상태와 결과를 읽습니다	run_id(필수)
cancel_script_run	시작되지 않은 스크립트 실행을 취소합니다	run_id(필수)
get_file_download_url	아티팩트 ID(art_…)를 15분 동안 유효한 다운로드 링크로 교환합니다	file_id(필수)
list_audit_events	계정의 감사 이벤트를 최신순으로 나열합니다. 엔터프라이즈 플랜 전용입니다. audit:read 범위가 필요하며, 자격 증명이 사람으로서 작동할 때는 관리자 권한이 필요합니다	action, actor_type, entity_type, entity_id, after, limit, starting_after, ending_before

연결이 어떤 도구를 볼 수 있는지는 자격 증명에 따라 달라집니다:

API 키와 OAuth 토큰은 동일한 범위를 공유하며, 연결은 자격 증명의 범위가 허용하는 도구를 볼 수 있습니다:

• 읽기 도구에는 read, 나머지에는 write이 필요합니다. 단, 도구가 아래 범위 중 하나를 필요로 하는 경우는 예외입니다.
• ask_crevio, start_chat, send_message, cancel_run에는 agent:run이, resolve_approvals에는 write도 필요합니다. write이 없으면 위임된 작업은 읽기 전용으로 실행됩니다.
• run_script, wait_for_script_run, get_script_run, cancel_script_run에는 scripts:run가 필요합니다. 팀 키는 이들을 절대 볼 수 없으며, write이 없으면 스크립트는 아무것도 변경할 수 없습니다.
• get_file_download_url에는 files:read이, list_audit_events에는 audit:read이 필요합니다.
• whoami는 아무 범위도 필요하지 않습니다.

read_only이 부여된 OAuth 토큰(클라이언트가 범위를 요청하지 않을 때의 기본값)은 read을 보유하며, read_write이 부여된 토큰은 모든 범위를 보유하고 모든 도구를 볼 수 있습니다. 범위가 존재하기 전에 만들어진 API 키도 마찬가지입니다.

토큰이 사용할 수 없는 도구는 tools/list에 나타나지 않으며, 호출하면 "도구를 찾을 수 없음"이라고 응답합니다. 범위 외에도, 에이전트가 접근해도 괜찮은 데이터를 가진 계정의 토큰을 부여하고 위임된 작업에 approval_mode을 선택하여 에이전트가 할 수 있는 일을 제한하세요.

실행 객체

위임 도구는 실행(trun_…)을 반환합니다. 이는 GET /v1/task_runs/:id와 동일한 객체에 result과 chat_id를 더한 것입니다:

필드	의미
status	pending → running → completed / failed, 또는 에이전트가 사용자를 기다릴 때는 needs_input
result	에이전트의 최종 응답, 최대 24,000자 (실행이 완료되면 제공됨)
json, json_error	response_format이 있는 경우: 파싱되고 검증된 응답, 또는 스키마에 대해 유효한 JSON이 아닌 이유
artifacts	실행이 전달한 파일, 각각 {id, filename, content_type, size}; get_file_download_url로 다운로드
summary	응답의 처음 500자 — 대시보드와 웹훅이 표시하는 내용
pending_approval_ids	needs_input일 때: 실행을 차단하는 통합 승인, resolve_approvals용
error_message	failed 실행이 실패한 이유 (cancel_run 이후 "Cancelled by the caller")
wait_timed_out, next_step	실행이 완료되기 전에 대기가 끝났을 때 제공됨 — 여전히 실행 중이며, next_step이 추적 방법을 알려줍니다
credits_consumed	실행 비용, AI 크레딧 단위
task_id, chat_id	기반이 되는 Task와 대화, REST API 및 대시보드용

실행은 또한 task_run.completed, task_run.failed, task_run.needs_input 웹훅을 발생시키며, GET /v1/task_runs/:id/stream에서 SSE를 통해 스트리밍될 수 있습니다.

MCP Tasks 및 elicitation

이는 MCP 클라이언트의 프로토콜 기능으로, Crevio 자체의 Tasks와는 별개입니다. 이를 사용하면 클라이언트가 wait_for_run과 resolve_approvals을 호출하는 대신 긴 작업을 추적하고 승인에 직접 응답합니다. 둘 다 클라이언트가 선택하는 2026-07-28 프로토콜이 필요합니다. 이를 사용하지 않으면 모든 도구는 위에서 설명한 대로 작동합니다.

비동기 도구 호출

서버는 MCP Tasks 확장(io.modelcontextprotocol/tasks)을 구현하며, /mcp과 /chatgpt 모두에서 server/discover에 광고됩니다. 요청이 _meta["io.modelcontextprotocol/clientCapabilities"].extensions에서 이를 선언하면, 다음 도구들은 최대 5초 동안 기다린 후 요청을 열어두는 대신 작업 핸들("resultType": "task")을 반환합니다: ask_crevio, wait_for_run, timeout_seconds이 있는 send_message, run_script, wait_for_script_run. 해당 5초 이내에 완료되는 실행은 제자리에서 응답됩니다.

• **tasks/get**은 작업의 status를 반환합니다. working은 실행이 여전히 진행 중임을 의미합니다. completed이 되면 result에 작업 없이 도구가 반환했을 내용이 정확히 담깁니다. pollIntervalMs에서 폴링하세요: 에이전트 실행은 3초, 스크립트는 1초.
• **tasks/update**은 작업의 inputRequests에 응답합니다(아래 참조).
• **tasks/cancel**는 cancel_run 또는 cancel_script_run처럼 실행을 중지합니다.

작업은 실행 자체이므로 실행이 지속되는 동안 유지됩니다(ttlMs는 null). failed로 끝나는 실행도 작업을 완료합니다: result 내에서 status와 error_message을 읽으세요. 작업 자체의 failed 상태는 프로토콜 오류용으로 유지됩니다. 작업 ID는 추측할 수 없으며, 실행을 시작한 계정과 사용자만 읽을 수 있습니다. 알 수 없거나 외부의 ID는 -32602로 응답하며, 확장을 선언하지 않은 요청은 -32021으로 응답합니다.

승인 및 질문

클라이언트가 양식 elicitation(_meta["io.modelcontextprotocol/clientCapabilities"].elicitation)을 선언하면, needs_input에서 일시 중지된 실행이 사용자에게 직접 묻습니다:

실행이 기다리는 것	클라이언트가 요청받는 것	수락	거부 또는 닫기
통합 작업 승인	승인 ID(apr_…)로 키가 지정된 작업별 양식 하나, 전송될 내용 설명 포함	승인함	거부함
에이전트 질문에 대한 답변	reply 필드가 있는 양식 하나	응답을 보내고 실행이 계속됨	실행을 완료됨으로 닫음

닫힌 승인은 거부이므로, 명시적인 예 없이는 아무것도 실행되지 않습니다. 양식은 순서에 관계없이, 한 번에 몇 개씩 답할 수 있습니다. 모든 양식에 답변이 있으면 실행이 재개되며, 에이전트는 모든 결정을 함께 듣습니다.

• 작업 사용 시: 작업이 inputRequests의 양식과 함께 input_required로 이동합니다. tasks/update로 답하세요.
• 작업 미사용 시: 도구가 양식과 requestState와 함께 "resultType": "input_required"을 반환합니다. 동일한 인수에 inputResponses과 해당 정확한 requestState을 더해 같은 도구를 다시 호출하세요. 상태는 봉인되어 도구와 그 인수에 바인딩되며, 1시간 후 만료됩니다.
• 양식 elicitation 미사용 시: 변경 사항이 없습니다. 실행은 resolve_approvals용 pending_approval_ids와 함께 needs_input로 돌아오며, 완료된 작업으로도 마찬가지입니다.

이벤트

서버는 초안 MCP Events 확장(io.modelcontextprotocol/events)을 구현하므로, 클라이언트는 order.paid 또는 email_message.received과 같이 계정에서 발생하는 일을 구독하고 폴링 없이 반응할 수 있습니다. 이는 /mcp와 /chatgpt 모두에서 server/discover에 광고됩니다.

이벤트 유형은 웹훅과 동일하며, 페이로드도 마찬가지입니다: data.object은 해당 API 엔드포인트가 반환하는 그대로의 리소스입니다. events/list는 모든 유형을 payloadSchema와 함께 나열합니다.

구독

{
  "jsonrpc": "2.0", "id": 2, "method": "events/subscribe",
  "params": {
    "name": "order.paid",
    "arguments": {},
    "delivery": { "mode": "webhook", "url": "https://hooks.example.com/crevio", "secret": "whsec_<base64 of 24–64 random bytes>" },
    "cursor": null,
    "ttlMs": 86400000
  }
}

응답에는 구독 id(mcpsub_…)가 포함되며, 동일한 자격 증명, URL, 이벤트 및 인수에 대해 안정적이고, refreshBefore도 포함됩니다. 유지하려면 refreshBefore 전에 동일한 값으로 events/subscribe을 다시 호출하세요. name, arguments, delivery.url와 함께 events/unsubscribe를 호출하면 즉시 종료됩니다.

• 검증. URL로의 첫 전달 전에 Crevio는 해당 URL로 {"type":"verification","challenge":"<nonce>"}을 POST합니다. 5초 이내에 2xx와 {"challenge":"<nonce>"}로 응답하세요. 각 자격 증명은 각 URL을 한 번 검증합니다.
• 수명. ttlMs이 없으면 구독은 하루 동안 지속됩니다. 제안된 ttlMs은 1분에서 하루 사이로 유지됩니다. "ttlMs": null은 만료 없음을 요청하며, Crevio는 이를 허용합니다.
• 비밀 교체. 새로 고칠 때 새 delivery.secret를 보내세요. 10분 동안 전달에는 두 비밀의 서명이 모두 포함됩니다.
• 제한. 계정당 활성 구독 100개. 구독은 읽기만 하므로 read_only 토큰으로도 가능합니다.

전달

각 이벤트는 {"eventId", "name", "timestamp", "data"}의 POST이며, Standard Webhooks에 따라 비밀(webhook-id, webhook-timestamp, webhook-signature)로 서명되고 X-MCP-Subscription-Id를 포함합니다. 본문을 신뢰하기 전에 서명을 검증하고, eventId에서 중복을 제거하세요.

엔드포인트가 하는 일	발생하는 일
2xx로 응답	전달됨
410 또는 413로 응답	재시도 없이 삭제됨
실패 또는 시간 초과 (5초)	약 12분에 걸쳐 최대 4회 더 재시도한 후 삭제됨
한 시간 동안 계속 실패	다음 새로 고침이 다시 켤 때까지 전달 중지
만료 없는 구독에서 3일 동안 계속 실패	Crevio가 {"type":"terminated",…}을 POST하고 구독을 삭제함

자격 증명이 계정에 대한 접근 권한을 잃으면(키 삭제 또는 만료, OAuth 접근 취소, 계정에서 사용자 제거), 다음 이벤트가 오류 -32024를 담은 terminated 봉투와 함께 구독을 종료합니다.

할 수 없는 것

• 웹훅 전달만 지원하며, 현재로서는 의도된 설계입니다. events/poll와 events/stream는 -32026로 응답합니다. POST를 받을 수 없는 경우 webhooks API 또는 list_runs와 REST 엔드포인트를 사용하세요.
• 재생 없음. cursor은 항상 null입니다. 구독이 중단된 동안 발생한 이벤트는 나중에 전달되지 않습니다. 공백이 생긴 후에는 도구를 통해 현재 상태를 읽으세요.
• 필터 없음. 이벤트 유형에는 arguments가 없습니다. 구독은 계정 내 해당 유형의 모든 이벤트를 받습니다.

오류는 확장의 코드를 사용합니다: -32602 잘못된 매개변수(잘못된 URL, 시크릿 또는 인수), -32023 알 수 없는 이벤트 또는 구독, -32024 인증된 주체 없음 또는 액세스 상실, -32025 구독 한도, -32026 제공되지 않는 전달 모드, -32027 콜백 검증 실패이며, data.reason은 connection_refused, timeout, tls_error, http_4xx, http_5xx 또는 challenge_failed 중 하나입니다.

오류

인증 실패는 요청 자체에 대한 HTTP 401/403입니다(WWW-Authenticate는 OAuth 메타데이터를 가리킴). 도구 실패는 isError: true와 JSON 본문이 포함된 도구 결과로 반환됩니다:

{ "error": "run_busy", "message": "Run trun_8d1k… is still in progress; wait for it to settle before sending more.", "http_status": 409 }

error	의미	수행할 작업
run_busy	이 대화의 실행이 아직 진행 중입니다	기다린 후 send_message
account_at_capacity	계정에 이미 5개의 실행이 진행 중입니다(http_status: 429)	retry_after_seconds 후 재시도
idempotency_error	다른 메시지로 idempotency_key가 재사용되었습니다	새 메시지에는 새 키를 전달하세요
run_not_active	이미 완료된 실행에 cancel_run	아무것도 하지 마세요 — 해당 result을 읽으세요
run_not_resumable	실행에 계속할 대화가 없습니다	ask_crevio로 새 작업을 시작하세요
approvals_pending	승인으로 차단된 실행에 send_message	먼저 resolve_approvals
stale_resolution	제출한 승인이 대기 중인 집합과 일치하지 않습니다	get_run 후 모든 pending_approval_ids 항목을 다시 제출하세요
insufficient_credits	계정에 남은 AI 크레딧이 없습니다	Crevio에서 크레딧을 추가하세요
resource_missing	이 계정에 해당 id의 실행/작업이 없습니다	id를 확인하세요 — 실행은 계정 범위입니다
validation_failed	잘못된 인수(예: 알 수 없는 approval_mode)	인수를 수정하세요
rate_limit_exceeded	소유자당 분당 600회 요청으로 REST API와 공유 — 또는 진행 중인 스크립트 실행이 너무 많음	X-RateLimit-Reset까지 백오프하거나(rate limits) 스크립트 실행이 끝날 때까지 기다리세요
forbidden	계정 관리자가 아닌 사람이 run_script	관리자에게 요청하거나 ask_crevio로 위임하세요
run_not_cancellable	이미 시작된 실행에 cancel_script_run	wait_for_script_run로 기다리세요

예외를 던지는 스크립트도 여전히 스크립트 실행으로 반환되며, status: "failed", 해당 error, 그리고 생성한 calls이 포함됩니다 — run_script 자체는 실행을 시작할 수 없거나 대기가 종료된 경우에만 오류를 반환합니다.

보안

모든 도구는 계정의 테넌트 경계 내에서 실행됩니다. 위임된 작업은 계정에 이미 있는 권한으로 Crevio 에이전트를 실행합니다. run_script는 호출하는 관리자로서 계정의 Crevio 컴퓨터에서 실행되며, 해당 tools 호출은 에이전트가 따르는 동일한 승인 설정과 api.crevio.co와 동일한 API 컨트롤러를 거치므로 권한 부여, 검증, 오류 메시지가 직접 API 호출과 동일합니다. 토큰은 계정만큼 강력합니다: 신뢰하는 에이전트만 연결하고, Settings → Developers에서 토큰을 해지하여 연결을 즉시 차단하세요.

다음 단계

연결

클라이언트별 설정, OAuth, curl 예제.

작업 (AI 워크포스)

모든 위임된 작업의 기반이 되는 Task / Task Run 모델 — 그리고 반복 작업을 예약하는 방법.

AI & 에이전트 개요

MCP, Tasks, Events가 Crevio의 에이전트 모델을 구성하는 방식.

API 규칙

crevioApi가 REST와 공유하는 형태, 접두사, 주의사항.

이 문서는 개발자 문서 플랫폼인 Mintlify에서 구축 및 호스팅됩니다.