Crevio

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

MCP Server

Kết nối Claude, Cursor hoặc bất kỳ agent tương thích MCP nào với tài khoản Crevio của bạn: giao việc cho agent Crevio bằng ask_crevio, theo dõi và tiếp tục các lượt chạy, và chạy script trên toàn bộ API Crevio cùng các tích hợp của bạn.

MCP server của Crevio cho phép bất kỳ agent tương thích MCP nào giao việc cho Crevio — và khi muốn tự mình điều khiển, chạy script trên toàn bộ API Crevio cùng các tích hợp của bạn. Một server, hai bề mặt:

• Ủy thác (Delegation) — ask_crevio giao cho agent Crevio một công việc bằng ngôn ngữ tự nhiên ("hoàn tiền đơn hàng gần nhất từ jane@…", "viết và lên lịch các bài đăng tuần này") và trả về kết quả. Các công việc dài hơn chạy nền; bạn theo dõi chúng dưới dạng runs, tiếp tục cuộc hội thoại, trả lời các cổng phê duyệt và đọc bản ghi.
• Scripts — list_integrations và list_integration_tools cho biết một script có thể gọi những gì, và run_script chạy JavaScript trên máy tính Crevio của tài khoản bạn, gọi mọi endpoint REST và tích hợp đã kết nối, với cùng cơ chế phân quyền và kiểm tra như API.

URL	https://mcp.crevio.co/mcp
Transport	Streamable HTTP (không trạng thái — mỗi request tự chứa đầy đủ)
Xác thực	Authorization: Bearer <API token> — cùng API token bạn dùng cho REST — hoặc X-Api-Key: <API token> cho các client chỉ có thể đặt custom header. OAuth 2.1 cũng được hỗ trợ; xem Connecting.
Discovery	https://mcp.crevio.co/mcp/server-card

[!NOTE]

Mới làm quen với mô hình agentic của Crevio? Hãy bắt đầu với tổng quan AI & Agents để hiểu cách MCP, Tasks và Events kết nối với nhau. Về bản chất, một công việc được ủy thác chính là một Task với một run, nên mọi thứ ở đây cũng hiển thị trong dashboard của bạn và qua /v1/tasks và /v1/task_runs.

Thiết lập

1. Tạo API token

Trong Crevio, vào Settings → Developers → API tokens và tạo một token. Một kết nối MCP có đúng các quyền của token đứng sau nó — tức mọi thứ mà tài khoản có thể làm.

2. Cấu hình client của bạn

Claude Code

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

Claude Desktop / Cursor / các client khác — thêm vào cấu hình MCP của client (claude_desktop_config.json, ~/.cursor/mcp.json, …):

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

Các bước riêng cho từng client, OAuth và ví dụ curl thô có trên trang Connecting.

3. Kiểm tra với whoami

Yêu cầu agent đã kết nối gọi whoami. Nó trả về tài khoản và người dùng đứng sau token, thông tin xác thực, gói, số dư credit, giới hạn tốc độ, giới hạn chờ và danh sách công cụ — không cần tham số, không có tác dụng phụ. Nếu whoami hoạt động, mọi thứ khác cũng sẽ hoạt động.

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

Quy trình làm việc được khuyến nghị

Công việc một lần: ask_crevio

Dành cho công việc cần phán đoán hoặc viết lách. Một lần gọi sẽ khởi động một run, chờ nó và trả về run kèm câu trả lời cuối cùng của agent trong result. Mỗi công việc là một lượt chạy agent đầy đủ, từ nửa phút đến vài phút — để đọc hoặc thay đổi dữ liệu trực tiếp, một script chỉ mất vài giây.

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

• Thời gian chờ mặc định và tối đa là 300 giây khi client của bạn chấp nhận phản hồi dạng stream (Accept: text/event-stream, mà các client MCP gửi theo mặc định), và 90 giây nếu không. Phản hồi dạng stream gửi thông báo tiến độ mỗi 10 giây trong lúc chờ — truyền một progressToken trong _meta để nhận chúng. Truyền timeout_seconds để chờ ít hơn.
• Nếu run vẫn đang chạy khi hết thời gian chờ, phản hồi không phải là lỗi: đó là run với wait_timed_out: true. Gọi wait_for_run với id của nó để tiếp tục chờ, và đừng gọi ask_crevio lần nữa — điều đó sẽ khởi động công việc lần thứ hai. Không có gì bị mất; run vẫn tiếp tục ở phía Crevio.
• idempotency_key giúp việc thử lại an toàn: cùng một key sẽ trả về run mà lần gọi đầu đã khởi động thay vì khởi động (và tính phí) thêm một lần nữa. Luôn truyền một key.
• speed: "faster" khiến agent suy nghĩ ít hơn, dành cho các công việc đơn giản nơi câu trả lời nhanh quan trọng hơn độ sâu. Mặc định là smarter.
• response_format nhận một JSON Schema (hoặc {type: "json_schema", json_schema: {schema}} của OpenAI) khi chương trình của bạn cần một object thay vì văn xuôi. Agent được cho biết schema, và run đã kết thúc mang giá trị đã phân tích trong json, được kiểm tra theo schema, hoặc lý do thất bại trong json_error. start_chat và send_message cũng nhận nó.
• Các tệp agent đã giao trong run được trả về trong artifacts. Đổi id của một artifact lấy liên kết tải xuống bằng get_file_download_url.
• approval_mode mặc định là autonomous. supervised khiến run tạm dừng ở needs_input trước mỗi thao tác ghi có kiểm soát cho đến khi bạn trả lời pending_approval_ids của nó (một run không có gì cần phê duyệt sẽ kết thúc với đề xuất của nó; trả lời bằng send_message để thực hiện); read_only cấm mọi thao tác ghi.

Công việc chạy dài: start_chat → wait_for_run → send_message

Dành cho bất cứ việc gì bạn không muốn bị chặn chờ — xây dựng site, một nhiệm vụ nghiên cứu, một cuộc di chuyển dữ liệu hàng loạt:

1. start_chat đưa công việc vào hàng đợi và trả về run ngay lập tức.
2. wait_for_run (có giới hạn) hoặc get_run (tức thì) cho đến khi status là completed, failed hoặc needs_input.
3. send_message tiếp tục cuộc hội thoại — hướng dẫn tiếp theo, chỉnh sửa, trả lời câu hỏi mà agent đã hỏi. Agent giữ nguyên ngữ cảnh. Trên một run đã kết thúc, thao tác này khởi động một run mới trong cùng cuộc hội thoại; trên một run needs_input, nó tiếp tục run đó. Truyền timeout_seconds để chờ câu trả lời trong cùng lần gọi, và một idempotency_key để lần gọi thử lại trả về run mà lần đầu đã khởi động (reused: true) thay vì gửi tin nhắn hai lần.
4. resolve_approvals khi một run bị tạm dừng ở một thao tác tích hợp (needs_input với pending_approval_ids) — phê duyệt hoặc từ chối mọi id đang chờ cùng lúc và run sẽ tiếp tục.
5. cancel_run để dừng một run đang chờ, đang chạy hoặc đang đợi.

Một chat là cuộc hội thoại và một run là một lượt làm việc bên trong nó. list_runs hiển thị mọi run trên tài khoản (truyền chat_id để chỉ xem run của một cuộc hội thoại) — cả công việc được ủy thác lẫn Tasks đã lên lịch của bạn — trong khi list_chats và get_chat duyệt chính các cuộc hội thoại, và list_messages đọc toàn bộ bản ghi của một chat, không chỉ câu trả lời cuối cùng.

Scripts: run_script

Khi agent đã kết nối muốn tự vận hành Crevio thay vì ủy thác — hoặc cần dữ liệu chính xác trả về — nó viết một script. run_script chạy JavaScript trên máy tính Crevio của tài khoản bạn với bun, không cần lượt agent. Script có thể gọi API Crevio và mọi tích hợp mà tài khoản bạn đã kết nối, nối chuỗi bao nhiêu lần gọi tùy thích, và biến đổi dữ liệu trước khi trả về.

Khám phá

list_integrations liệt kê mọi namespace mà một script có thể gọi: crevioApi (toàn bộ API Crevio, mỗi thao tác một hàm), platform (các công cụ riêng của Crevio), và mỗi tích hợp đã kết nối một namespace (pdGmail, mcpLinear, …). list_integration_tools liệt kê các hàm của một namespace, mỗi hàm kèm tham số dưới dạng kiểu TypeScript, cho biết nó chỉ đọc hay không, có cần phê duyệt hay không, và một đoạn mã mà run_script chấp nhận sau khi bạn điền vào. crevioApi có hàng trăm thao tác, nên hãy thu hẹp bằng search:

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

Chạy

tools.<namespace>.<function>(args) thực hiện một lần gọi. await ở cấp cao nhất hoạt động được, mọi lần gọi trả về kết quả và ném lỗi khi thất bại, và biểu thức cuối cùng của script là kết quả của nó.

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

Các thao tác đọc nhận tham số trực tiếp (listOrders({ status: "succeeded" })); các thao tác ghi truyền body của request dưới body, với tham số đường dẫn bên cạnh.

Truyền giá trị bằng args (tối đa 16 chuỗi); script đọc chúng từ biến toàn cục args. Các tệp được ghi vào thư mục có tên trong biến toàn cục outputDir sẽ được trả về dưới dạng artifacts trên run:

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

Một run trả về một script run (srun_…): status của nó (queued → in_progress → completed, failed, cancelled hoặc timed_out), result, những gì script in ra trong output, error của nó, và calls — mọi lần gọi công cụ mà nó đã thực hiện kèm trạng thái HTTP, nên một script đã bắt lỗi vẫn cho thấy lần gọi nào thất bại. run_script chờ lâu nhất có thể theo ask_crevio (300 giây với phản hồi dạng stream, 90 giây nếu không; truyền wait_seconds để chờ ít hơn). Một run mất nhiều thời gian hơn sẽ trả về với wait_timed_out: true và id của nó — không phải lỗi: hãy tiếp tục chờ bằng wait_for_script_run. Gọi run_script lần nữa sẽ chạy script hai lần, trừ khi bạn truyền cùng idempotency_key.

Các lần gọi crevioApi đi qua cùng các controller như api.crevio.co, nên các quy ước API áp dụng không đổi: các liên kết là tên trần với id có tiền tố (product: "prod_abc", không phải product_id), tiền tính bằng cent, các endpoint danh sách trả về {object: "list", data: [...]}, và một sản phẩm cần một biến thể giá trước khi có thể active. Khóa học và nội dung khác là experiences (listExperiences), không phải sản phẩm.

Giới hạn:

• Ai: chỉ admin tài khoản. Script chạy với tư cách bạn — bao gồm các tích hợp cá nhân của bạn — trên một máy tính mà cả nhóm bạn dùng chung.
• Timeout: timeout_seconds từ 1 đến 600 (mặc định 300). Máy tính có thể cần đánh thức trước, điều này có thể cộng thêm khoảng 20 giây.
• Đồng thời: tối đa 4 run đang chạy mỗi người dùng và 8 mỗi tài khoản.
• Phê duyệt: một script không thể dừng lại và yêu cầu phê duyệt. Một lần gọi cần phê duyệt (requires_approval trong danh sách) sẽ thất bại với approval_required: hãy đặt thao tác đó chạy tự động trong Settings → Integrations, hoặc ủy thác công việc bằng ask_crevio thay vào đó.
• Hủy: chỉ một run queued mới có thể bị hủy. Một script đang chạy sẽ chạy đến hết hoặc đến timeout.
• Tệp đầu ra: tối đa 20 tệp mỗi run, mỗi tệp tối đa 50 MB. Các tệp lớn hơn sẽ bị bỏ qua.

Tham chiếu công cụ đầy đủ

Công cụ	Mục đích	Tham số
whoami	Xác định tài khoản, người dùng, thông tin xác thực, gói, tín dụng, giới hạn và công cụ	—
ask_crevio	Ủy thác một tác vụ và chờ kết quả	message (bắt buộc), timeout_seconds, approval_mode, speed, response_format, idempotency_key
start_chat	Ủy thác một tác vụ mà không chờ	message (bắt buộc), approval_mode, speed, response_format, idempotency_key
wait_for_run	Chờ (có giới hạn) để một lượt chạy hoàn tất	run_id (bắt buộc), timeout_seconds
get_run	Lấy trạng thái, tóm tắt, các phê duyệt đang chờ và câu trả lời cuối cùng của một lượt chạy	run_id (bắt buộc)
list_chats	Liệt kê các cuộc trò chuyện của tài khoản, mới nhất trước	search, limit, starting_after, ending_before
get_chat	Lấy tiêu đề, loại và lượt chạy mới nhất của một cuộc trò chuyện	chat_id (bắt buộc)
send_message	Tiếp tục một cuộc trò chuyện; tùy chọn chờ câu trả lời	chat_id, message (bắt buộc), timeout_seconds, response_format, idempotency_key
resolve_approvals	Phê duyệt/từ chối các hành động tích hợp mà một lượt chạy đang tạm dừng chờ	run_id, approvals: [{id, approved, reason}] (bắt buộc)
cancel_run	Dừng một lượt chạy đang chờ, đang chạy hoặc đang đợi	run_id (bắt buộc)
list_runs	Liệt kê các lượt chạy của tài khoản, mới nhất trước	status, task_id, chat_id, limit, starting_after, ending_before
list_messages	Đọc tin nhắn của một cuộc trò chuyện, cũ nhất trước	chat_id (bắt buộc), limit, ending_before
list_integrations	Nêu tên mọi không gian tên mà một script có thể gọi	—
list_integration_tools	Liệt kê các hàm của một không gian tên kèm tham số và đoạn mã mẫu	namespace (bắt buộc), search, limit, offset
run_script	Chạy JavaScript trên máy tính của tài khoản và chờ kết quả	code (bắt buộc), args, timeout_seconds, wait_seconds, idempotency_key
wait_for_script_run	Chờ (có giới hạn) để một lượt chạy script hoàn tất	run_id (bắt buộc), wait_seconds
get_script_run	Đọc trạng thái và kết quả của một lượt chạy script	run_id (bắt buộc)
cancel_script_run	Hủy một lượt chạy script chưa bắt đầu	run_id (bắt buộc)
get_file_download_url	Đổi một id tạo tác (art_…) lấy liên kết tải xuống có hiệu lực 15 phút	file_id (bắt buộc)
list_audit_events	Liệt kê các sự kiện kiểm toán của tài khoản, mới nhất trước. Chỉ gói Enterprise. Cần phạm vi audit:read, và cần quyền quản trị viên khi thông tin xác thực hoạt động với tư cách một người	action, actor_type, entity_type, entity_id, after, limit, starting_after, ending_before

Công cụ mà một kết nối nhìn thấy phụ thuộc vào thông tin xác thực của nó:

Khóa API và token OAuth dùng chung phạm vi, và một kết nối nhìn thấy các công cụ mà phạm vi của thông tin xác thực cho phép:

• read cho các công cụ đọc, write cho phần còn lại, trừ khi công cụ cần một trong các phạm vi bên dưới.
• agent:run cho ask_crevio, start_chat, send_message và cancel_run, và resolve_approvals cùng với write. Không có write, công việc được ủy thác sẽ chạy ở chế độ chỉ đọc.
• scripts:run cho run_script, wait_for_script_run, get_script_run và cancel_script_run. Khóa nhóm không bao giờ nhìn thấy các công cụ này, và không có write thì một script không thể thay đổi bất cứ điều gì.
• files:read cho get_file_download_url, và audit:read cho list_audit_events.
• whoami không cần phạm vi nào.

Một token OAuth được cấp read_only (mặc định khi một client không yêu cầu phạm vi nào) có read; một token được cấp read_write có mọi phạm vi và nhìn thấy mọi công cụ. Khóa API được tạo trước khi có phạm vi cũng vậy.

Một công cụ mà token không thể dùng sẽ không xuất hiện trong tools/list, và khi gọi nó sẽ trả lời "Tool not found". Ngoài phạm vi, hãy giới hạn những gì một agent có thể làm bằng cách cấp cho nó một token trên một tài khoản mà bạn sẵn lòng cho nó chạm vào dữ liệu, và bằng cách chọn approval_mode trên các tác vụ được ủy thác.

Đối tượng run

Các công cụ ủy thác trả về một run (trun_…), cùng đối tượng như GET /v1/task_runs/:id cộng thêm result và chat_id:

Trường	Ý nghĩa
status	pending → running → completed / failed, hoặc needs_input khi agent đang đợi bạn
result	Câu trả lời cuối cùng của agent, tối đa 24.000 ký tự (có mặt khi lượt chạy đã hoàn tất)
json, json_error	Với một response_format: câu trả lời đã được phân tích và xác thực, hoặc lý do nó không phải JSON hợp lệ theo schema
artifacts	Các tệp mà lượt chạy đã giao, mỗi tệp là một {id, filename, content_type, size}; tải xuống bằng get_file_download_url
summary	500 ký tự đầu tiên của câu trả lời — những gì dashboard và webhook hiển thị
pending_approval_ids	Khi needs_input: các phê duyệt tích hợp đang chặn lượt chạy, cho resolve_approvals
error_message	Lý do một lượt chạy failed thất bại ("Cancelled by the caller" sau cancel_run)
wait_timed_out, next_step	Có mặt khi thời gian chờ kết thúc trước khi lượt chạy hoàn tất — nó vẫn đang chạy; next_step cho biết cách theo dõi nó
credits_consumed	Chi phí của lượt chạy, tính bằng tín dụng AI
task_id, chat_id	Task và cuộc trò chuyện bên dưới, dành cho REST API và dashboard

Các lượt chạy cũng kích hoạt webhook task_run.completed, task_run.failed và task_run.needs_input, và có thể được truyền trực tuyến qua SSE tại GET /v1/task_runs/:id/stream.

MCP Tasks và elicitation

Đây là các tính năng giao thức của client MCP của bạn, tách biệt với Tasks của chính Crevio. Với chúng, client tự theo dõi các tác vụ dài và tự trả lời phê duyệt thay vì gọi wait_for_run và resolve_approvals. Cả hai đều cần giao thức 2026-07-28, do client của bạn chọn. Không có chúng, mọi công cụ hoạt động như mô tả ở trên.

Gọi công cụ bất đồng bộ

Máy chủ triển khai tiện ích mở rộng MCP Tasks (io.modelcontextprotocol/tasks), được quảng bá trong server/discover trên cả /mcp và /chatgpt. Khi một yêu cầu khai báo nó trong _meta["io.modelcontextprotocol/clientCapabilities"].extensions, các công cụ này chờ tối đa 5 giây rồi trả về một handle tác vụ ("resultType": "task") thay vì giữ yêu cầu mở: ask_crevio, wait_for_run, send_message với một timeout_seconds, run_script và wait_for_script_run. Một lượt chạy hoàn tất trong 5 giây đó sẽ được trả lời ngay tại chỗ.

• tasks/get trả về status của tác vụ. working nghĩa là lượt chạy vẫn đang tiếp diễn. Khi nó đã completed, result chứa đúng những gì công cụ sẽ trả về nếu không có tasks. Thăm dò tại pollIntervalMs: 3 giây cho lượt chạy agent, 1 giây cho script.
• tasks/update trả lời inputRequests của tác vụ (xem bên dưới).
• tasks/cancel dừng lượt chạy, giống như cancel_run hoặc cancel_script_run.

Một tác vụ chính là lượt chạy, nên nó tồn tại chừng nào lượt chạy còn (ttlMs là null). Một lượt chạy kết thúc failed vẫn hoàn tất tác vụ: đọc status và error_message của nó bên trong result. Trạng thái failed của chính tác vụ được giữ cho các lỗi giao thức. ID tác vụ không thể đoán được, và chỉ tài khoản và người dùng đã khởi tạo lượt chạy mới đọc được nó. Một ID không xác định hoặc của người khác trả lời -32602, và một yêu cầu không khai báo tiện ích mở rộng trả lời -32021.

Phê duyệt và câu hỏi

Khi một client khai báo form elicitation (_meta["io.modelcontextprotocol/clientCapabilities"].elicitation), một lượt chạy đang tạm dừng ở needs_input sẽ hỏi người dùng trực tiếp:

Lượt chạy đang chờ	Client được hỏi	Chấp nhận	Từ chối hoặc đóng
Phê duyệt các hành động tích hợp	Một biểu mẫu cho mỗi hành động, khóa theo ID phê duyệt của nó (apr_…), mô tả những gì sẽ được gửi	Phê duyệt nó	Từ chối nó
Câu trả lời cho câu hỏi của agent	Một biểu mẫu với trường reply	Gửi câu trả lời và lượt chạy tiếp tục	Đóng lượt chạy là đã hoàn thành

Một phê duyệt bị đóng là một sự từ chối, nên không có gì chạy mà không có sự đồng ý rõ ràng. Bạn có thể trả lời các biểu mẫu theo bất kỳ thứ tự nào và vài cái cùng lúc. Lượt chạy tiếp tục khi mọi biểu mẫu đều có câu trả lời, và agent nhận được tất cả các quyết định cùng nhau.

• Có tasks: tác vụ chuyển sang input_required với các biểu mẫu trong inputRequests. Trả lời chúng bằng tasks/update.
• Không có tasks: công cụ trả về "resultType": "input_required" với các biểu mẫu và một requestState. Gọi lại cùng công cụ đó với cùng tham số, cộng thêm inputResponses và đúng requestState đó. Trạng thái được niêm phong, gắn với công cụ và tham số của nó, và hết hạn sau một giờ.
• Không có form elicitation: không có gì thay đổi. Lượt chạy trả về needs_input với pending_approval_ids cho resolve_approvals, kể cả dưới dạng một tác vụ đã hoàn thành.

Sự kiện

Máy chủ triển khai bản nháp tiện ích mở rộng MCP Events (io.modelcontextprotocol/events), để client có thể đăng ký theo dõi những gì xảy ra trong tài khoản, chẳng hạn order.paid hoặc email_message.received, và phản ứng mà không cần thăm dò. Nó được quảng bá trong server/discover trên cả /mcp và /chatgpt.

Các loại sự kiện giống như webhook, và payload cũng vậy: data.object là tài nguyên đúng như endpoint API của nó trả về. events/list liệt kê mọi loại cùng với payloadSchema của nó.

Đăng ký

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

Phản hồi mang id của đăng ký (mcpsub_…), ổn định cho cùng thông tin xác thực, URL, sự kiện và tham số, và refreshBefore. Gọi lại events/subscribe với cùng các giá trị trước refreshBefore để giữ nó; events/unsubscribe với name, arguments và delivery.url kết thúc nó ngay lập tức.

• Xác minh. Trước lần giao đầu tiên đến một URL, Crevio POST {"type":"verification","challenge":"<nonce>"} đến đó. Trả lời bằng 2xx và {"challenge":"<nonce>"} trong vòng 5 giây. Mỗi thông tin xác thực xác minh mỗi URL một lần.
• Thời hạn. Không có ttlMs, một đăng ký kéo dài một ngày. ttlMs được đề xuất được giữ trong khoảng từ một phút đến một ngày. "ttlMs": null yêu cầu không hết hạn, và Crevio chấp thuận.
• Xoay bí mật. Gửi một delivery.secret mới khi làm mới. Trong 10 phút, các lần giao mang chữ ký từ cả hai bí mật.
• Giới hạn. 100 đăng ký đang hoạt động mỗi tài khoản. Đăng ký chỉ đọc, nên một token read_only có thể làm việc này.

Giao nhận

Mỗi sự kiện là một POST của {"eventId", "name", "timestamp", "data"}, được ký theo Standard Webhooks bằng bí mật của bạn (webhook-id, webhook-timestamp, webhook-signature) và mang X-MCP-Subscription-Id. Hãy xác minh chữ ký trước khi tin vào nội dung, và loại trùng theo eventId.

Endpoint của bạn làm gì	Điều gì xảy ra
Trả lời 2xx	Đã giao
Trả lời 410 hoặc 413	Bị bỏ mà không thử lại
Thất bại hoặc hết thời gian chờ (5 giây)	Thử lại tối đa 4 lần nữa trong khoảng 12 phút, rồi bị bỏ
Tiếp tục thất bại trong một giờ	Việc giao dừng cho đến khi lần làm mới tiếp theo của bạn bật lại
Tiếp tục thất bại trong 3 ngày trên một đăng ký không hết hạn	Crevio POST {"type":"terminated",…} và xóa đăng ký

Nếu thông tin xác thực mất quyền truy cập vào tài khoản (khóa bị xóa hoặc hết hạn, quyền truy cập OAuth bị thu hồi, người dùng bị xóa khỏi tài khoản), sự kiện tiếp theo sẽ kết thúc đăng ký bằng một phong bì terminated mang lỗi -32024.

Những gì nó không thể làm

• Chỉ giao hàng qua webhook, theo thiết kế hiện tại. events/poll và events/stream trả lời -32026. Dùng API webhooks hoặc list_runs và các endpoint REST khi bạn không thể nhận POST.
• Không phát lại. cursor luôn là null: các sự kiện xảy ra trong lúc một đăng ký bị gián đoạn sẽ không được gửi sau đó. Hãy đọc trạng thái hiện tại qua các công cụ sau khi có khoảng trống.
• Không có bộ lọc. Các loại sự kiện không nhận arguments. Một đăng ký nhận mọi sự kiện thuộc loại của nó trong tài khoản.

Lỗi dùng mã của tiện ích mở rộng: -32602 tham số không hợp lệ (URL, secret hoặc đối số sai), -32023 sự kiện hoặc đăng ký không xác định, -32024 không có chủ thể đã xác thực hoặc mất quyền truy cập, -32025 đạt giới hạn đăng ký, -32026 chế độ giao hàng không được cung cấp, và -32027 callback xác minh thất bại, với data.reason là một trong connection_refused, timeout, tls_error, http_4xx, http_5xx hoặc challenge_failed.

Lỗi

Lỗi xác thực là HTTP 401/403 trên chính yêu cầu (WWW-Authenticate trỏ đến metadata OAuth). Lỗi công cụ trả về dưới dạng kết quả công cụ với isError: true và một body JSON:

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

error	Ý nghĩa	Cần làm gì
run_busy	Một lượt chạy trong cuộc hội thoại này vẫn đang diễn ra	Chờ nó, rồi send_message
account_at_capacity	Tài khoản đã có 5 lượt chạy đang diễn ra (http_status: 429)	Thử lại sau retry_after_seconds
idempotency_error	Một idempotency_key được dùng lại với thông điệp khác	Truyền khóa mới cho thông điệp mới
run_not_active	cancel_run trên một lượt chạy đã kết thúc	Không cần làm gì — đọc result của nó
run_not_resumable	Lượt chạy không có cuộc hội thoại để tiếp tục	Bắt đầu một job mới với ask_crevio
approvals_pending	send_message trên một lượt chạy bị chặn bởi phê duyệt	resolve_approvals trước
stale_resolution	Các phê duyệt bạn gửi không khớp với tập đang chờ	get_run, rồi gửi lại mọi mục pending_approval_ids
insufficient_credits	Tài khoản không còn tín dụng AI	Thêm tín dụng trong Crevio
resource_missing	Không có lượt chạy/tác vụ nào với id đó trên tài khoản này	Kiểm tra id — lượt chạy gắn với phạm vi tài khoản
validation_failed	Đối số sai (ví dụ: approval_mode không xác định)	Sửa đối số
rate_limit_exceeded	600 yêu cầu mỗi phút cho mỗi chủ sở hữu, dùng chung với API REST — hoặc quá nhiều lượt chạy script đang diễn ra	Lùi lại cho đến X-RateLimit-Reset (giới hạn tốc độ), hoặc chờ một lượt chạy script kết thúc
forbidden	run_script bởi người không phải quản trị viên tài khoản	Hỏi quản trị viên, hoặc ủy quyền với ask_crevio
run_not_cancellable	cancel_script_run trên một lượt chạy đã bắt đầu	Chờ nó với wait_for_script_run

Một script ném lỗi vẫn trả về dưới dạng một lượt chạy script, với status: "failed", error của nó, và calls mà nó đã tạo — bản thân run_script chỉ báo lỗi khi lượt chạy không thể bắt đầu hoặc thời gian chờ kết thúc.

Bảo mật

Mọi công cụ chạy trong ranh giới tenant của tài khoản bạn. Các job được ủy quyền chạy agent Crevio với các quyền mà tài khoản bạn đã có. run_script chạy trên máy tính Crevio của tài khoản bạn với tư cách quản trị viên đang gọi; các lệnh gọi tools của nó đi qua cùng cài đặt phê duyệt mà agent tuân theo và cùng các controller API như api.crevio.co, nên việc phân quyền, xác thực và thông báo lỗi giống hệt các lệnh gọi API trực tiếp. Token có sức mạnh ngang với tài khoản của bạn: chỉ kết nối những agent bạn tin tưởng, và thu hồi token từ Settings → Developers để ngắt kết nối ngay lập tức.

Bước tiếp theo

Kết nối

Thiết lập theo từng client, OAuth, và các ví dụ curl.

Tác vụ (lực lượng AI của bạn)

Mô hình Task / Task Run mà mọi job được ủy quyền dựa trên — và cách lên lịch công việc định kỳ.

Tổng quan về AI & Agent

Cách MCP, Tác vụ và Sự kiện tạo nên mô hình agentic của Crevio.

Quy ước API

Các hình dạng, tiền tố và những điều cần lưu ý mà crevioApi chia sẻ với REST.

Tài liệu này được xây dựng và lưu trữ trên Mintlify, một nền tảng tài liệu dành cho nhà phát triển.