Crevio

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

MCP Server

Connect Claude, Cursor, or any MCP-compatible agent to your Crevio account: delegate work to the Crevio agent with ask_crevio, follow and continue runs, and run scripts against the whole Crevio API and your integrations.

The Crevio MCP server lets any MCP-compatible agent delegate work to Crevio — and, when it wants the controls itself, run scripts against the entire Crevio API and your integrations. One server, two surfaces:

• Delegation — ask_crevio hands the Crevio agent a job in plain English ("refund the last order from jane@…", "write and schedule this week's posts") and returns the result. Longer jobs run in the background; you follow them as runs, continue the conversation, answer approval gates, and read the transcript.
• Scripts — list_integrations and list_integration_tools show what a script can call, and run_script runs JavaScript on your account's Crevio computer against every REST endpoint and connected integration, with the same authorization and validation as the API.

URL	https://mcp.crevio.co/mcp
Transport	Streamable HTTP (stateless — every request is self-contained)
Authentication	Authorization: Bearer <API token> — the same API token you use for REST — or X-Api-Key: <API token> for clients that can only set a custom header. OAuth 2.1 is also supported; see Connecting.
Discovery	https://mcp.crevio.co/mcp/server-card

[!NOTE]

New to Crevio's agentic model? Start with the AI & Agents overview to see how MCP, Tasks, and Events fit together. Under the hood a delegated job is a Task with one run, so everything here is also visible in your dashboard and through /v1/tasks and /v1/task_runs.

Setup

1. Create an API token

In Crevio go to Settings → Developers → API tokens and create one. An MCP connection has exactly the permissions of the token behind it — everything the account can do.

2. Configure your client

Claude Code

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

Claude Desktop / Cursor / other clients — add to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, …):

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

Client-specific steps, OAuth, and raw curl examples are on the Connecting page.

3. Verify with whoami

Ask the connected agent to call whoami. It returns the account and user behind the token, the credential, plan, credit balance, rate limit, wait limits, and the list of tools — no arguments, no side effects. If whoami works, everything else will.

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

Recommended workflows

One-off jobs: ask_crevio

For work that needs judgement or writing. One call starts a run, waits for it, and returns the run with the agent's final reply in result. Each job is a full agent run, from half a minute to several minutes — to read or change data directly, a script takes seconds.

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

• The wait defaults to, and is capped at, 300 seconds when your client accepts a streamed reply (Accept: text/event-stream, which MCP clients send by default), and 90 seconds otherwise. A streamed reply sends a progress notification every 10 seconds while it waits — pass a progressToken in _meta to receive them. Pass timeout_seconds to wait less.
• If the run is still going when the wait ends, the reply is not an error: it is the run with wait_timed_out: true. Call wait_for_run with its id to keep waiting, and don't call ask_crevio again — that would start the job a second time. Nothing is lost; the run continues on Crevio's side.
• idempotency_key makes retries safe: the same key returns the run the first call started instead of starting (and paying for) another. Always pass one.
• speed: "faster" has the agent think less, for simple jobs where a quicker answer matters more than depth. The default is smarter.
• response_format takes a JSON Schema (or OpenAI's {type: "json_schema", json_schema: {schema}}) when your program needs an object rather than prose. The agent is told the schema, and the settled run carries the parsed value in json, validated against it, or the reason it failed in json_error. start_chat and send_message take it too.
• Files the agent delivered during the run come back in artifacts. Exchange an artifact's id for a download link with get_file_download_url.
• approval_mode is autonomous by default. supervised makes the run pause in needs_input before each gated write until you answer its pending_approval_ids (a run with nothing to approve finishes with its proposal; reply with send_message to act on it); read_only forbids writes.

Long-running jobs: start_chat → wait_for_run → send_message

For anything you don't want to block on — a site build, a research task, a bulk migration:

1. start_chat queues the work and returns the run immediately.
2. wait_for_run (bounded) or get_run (instant) until status is completed, failed, or needs_input.
3. send_message continues the conversation — follow-up instructions, corrections, answers to a question the agent asked. The agent keeps its context. On a finished run this starts a new run in the same conversation; on a needs_input run it resumes it. Pass timeout_seconds to wait for the reply in the same call, and an idempotency_key so a retried call returns the run the first one started (reused: true) instead of sending the message twice.
4. resolve_approvals when a run is paused on an integration action (needs_input with pending_approval_ids) — approve or deny every pending id at once and the run resumes.
5. cancel_run to stop a run that is pending, running, or waiting.

A chat is the conversation and a run is one turn of work inside it. list_runs shows every run on the account (pass chat_id for just one conversation's runs) — delegated jobs and your scheduled Tasks alike — while list_chats and get_chat browse the conversations themselves, and list_messages reads a chat's full transcript, not just the final reply.

Scripts: run_script

When the connected agent wants to operate Crevio itself rather than delegate — or needs exact data back — it writes a script. run_script runs JavaScript on your account's Crevio computer with bun, with no agent turn. The script can call the Crevio API and every integration your account has connected, chain as many calls as it likes, and transform the data before it comes back.

Discover

list_integrations names every namespace a script can call: crevioApi (the whole Crevio API, one function per operation), platform (Crevio's own tools), and one per connected integration (pdGmail, mcpLinear, …). list_integration_tools lists one namespace's functions, each with its parameters as a TypeScript type, whether it only reads, whether it needs approval, and a snippet run_script accepts once you fill it in. crevioApi has hundreds of operations, so narrow it with search:

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

Run

tools.<namespace>.<function>(args) makes a call. Top-level await works, every call returns its result and throws on failure, and the script's last expression is its result.

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

Reads take their parameters directly (listOrders({ status: "succeeded" })); writes pass the request body under body, with path parameters beside it.

Pass values with args (up to 16 strings); the script reads them from the global args. Files written into the directory named by the global outputDir come back as artifacts on the 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

A run returns a script run (srun_…): its status (queued → in_progress → completed, failed, cancelled or timed_out), the result, what the script printed in output, its error, and calls — every tool call it made with its HTTP status, so a script that caught an error still shows which call failed. run_script waits as long as ask_crevio can (300 seconds on a streamed reply, 90 otherwise; pass wait_seconds to wait less). A run that takes longer comes back with wait_timed_out: true and its id — not an error: keep waiting with wait_for_script_run. Calling run_script again would run the script twice, unless you pass the same idempotency_key.

crevioApi calls go through the same controllers as api.crevio.co, so the API conventions apply unchanged: associations are bare names with prefix ids (product: "prod_abc", not product_id), money is in cents, list endpoints return {object: "list", data: [...]}, and a product needs a price variant before it can go active. Courses and other content are experiences (listExperiences), not products.

Limits:

• Who: account admins only. The script runs as you — your personal integrations included — on a computer your whole team shares.
• Timeout: timeout_seconds from 1 to 600 (default 300). The computer may need to wake first, which can add up to about 20 seconds.
• Concurrency: at most 4 runs in flight per user and 8 per account.
• Approvals: a script cannot stop and ask for approval. A call that needs it (requires_approval in the listing) fails with approval_required: set that action to run automatically in Settings → Integrations, or delegate the job with ask_crevio instead.
• Cancellation: only a queued run can be cancelled. A running script runs to its end or its timeout.
• Output files: at most 20 per run, each at most 50 MB. Larger files are left out.

Complete tool reference

Tool	Purpose	Arguments
whoami	Identify the account, user, credential, plan, credits, limits, and tools	—
ask_crevio	Delegate a job and wait for the result	message (required), timeout_seconds, approval_mode, speed, response_format, idempotency_key
start_chat	Delegate a job without waiting	message (required), approval_mode, speed, response_format, idempotency_key
wait_for_run	Wait (bounded) for a run to settle	run_id (required), timeout_seconds
get_run	Fetch a run's status, summary, pending approvals, and final reply	run_id (required)
list_chats	List the account's chats, newest first	search, limit, starting_after, ending_before
get_chat	Fetch a chat's title, kind, and latest run	chat_id (required)
send_message	Continue a chat; optionally wait for the reply	chat_id, message (required), timeout_seconds, response_format, idempotency_key
resolve_approvals	Approve/deny the integration actions a run is paused on	run_id, approvals: [{id, approved, reason}] (required)
cancel_run	Stop a pending, running, or waiting run	run_id (required)
list_runs	List the account's runs, newest first	status, task_id, chat_id, limit, starting_after, ending_before
list_messages	Read a chat's messages, oldest first	chat_id (required), limit, ending_before
list_integrations	Name every namespace a script can call	—
list_integration_tools	List a namespace's functions with parameters and snippets	namespace (required), search, limit, offset
run_script	Run JavaScript on the account's computer and wait for it	code (required), args, timeout_seconds, wait_seconds, idempotency_key
wait_for_script_run	Wait (bounded) for a script run to finish	run_id (required), wait_seconds
get_script_run	Read a script run's status and result	run_id (required)
cancel_script_run	Cancel a script run that has not started	run_id (required)
get_file_download_url	Exchange an artifact id (art_…) for a download link valid 15 minutes	file_id (required)
list_audit_events	List the account's audit events, newest first. Enterprise plan only. Needs the audit:read scope, and an admin when the credential acts as a person	action, actor_type, entity_type, entity_id, after, limit, starting_after, ending_before

Which tools a connection sees depends on its credential:

API keys and OAuth tokens share the same scopes, and a connection sees the tools its credential's scopes allow:

• read for the tools that read, write for the rest, unless the tool needs one of the scopes below.
• agent:run for ask_crevio, start_chat, send_message and cancel_run, and resolve_approvals with write too. Without write, delegated work runs read-only.
• scripts:run for run_script, wait_for_script_run, get_script_run and cancel_script_run. A team key never sees these, and without write a script cannot change anything.
• files:read for get_file_download_url, and audit:read for list_audit_events.
• whoami needs none.

An OAuth token granted read_only (the default when a client asks for no scope) holds read; one granted read_write holds every scope and sees every tool. So does an API key made before scopes existed.

A tool the token can't use doesn't appear in tools/list, and calling it answers "Tool not found". Beyond scopes, limit what an agent can do by giving it a token on an account whose data you're happy for it to touch, and by choosing approval_mode on delegated jobs.

The run object

Delegation tools return a run (trun_…), the same object as GET /v1/task_runs/:id plus result and chat_id:

Field	Meaning
status	pending → running → completed / failed, or needs_input when the agent is waiting on you
result	The agent's final reply, up to 24,000 characters (present once the run has settled)
json, json_error	With a response_format: the reply parsed and validated, or why it was not valid JSON for the schema
artifacts	Files the run delivered, each {id, filename, content_type, size}; download with get_file_download_url
summary	The first 500 characters of the reply — what the dashboard and webhooks show
pending_approval_ids	When needs_input: the integration approvals blocking the run, for resolve_approvals
error_message	Why a failed run failed ("Cancelled by the caller" after cancel_run)
wait_timed_out, next_step	Present when the wait ended before the run settled — it is still running; next_step says how to follow it
credits_consumed	What the run cost, in AI credits
task_id, chat_id	The underlying Task and conversation, for the REST API and the dashboard

Runs also fire the task_run.completed, task_run.failed, and task_run.needs_input webhooks, and can be streamed over SSE at GET /v1/task_runs/:id/stream.

MCP Tasks and elicitation

These are protocol features of your MCP client, separate from Crevio's own Tasks. With them, a client follows long jobs and answers approvals itself instead of calling wait_for_run and resolve_approvals. Both need the 2026-07-28 protocol, which your client chooses. Without them, every tool behaves as described above.

Async tool calls

The server implements the MCP Tasks extension (io.modelcontextprotocol/tasks), advertised in server/discover on both /mcp and /chatgpt. When a request declares it in _meta["io.modelcontextprotocol/clientCapabilities"].extensions, these tools wait at most 5 seconds and then return a task handle ("resultType": "task") instead of holding the request open: ask_crevio, wait_for_run, send_message with a timeout_seconds, run_script, and wait_for_script_run. A run that finishes inside those 5 seconds is answered in place.

• tasks/get returns the task's status. working means the run is still going. Once it is completed, result holds exactly what the tool would have returned without tasks. Poll at pollIntervalMs: 3 seconds for agent runs, 1 second for scripts.
• tasks/update answers the task's inputRequests (see below).
• tasks/cancel stops the run, like cancel_run or cancel_script_run.

A task is the run itself, so it lasts as long as the run (ttlMs is null). A run that ends failed still completes the task: read its status and error_message inside result. The task's own failed status is kept for protocol errors. A task ID is unguessable, and only the account and user who started the run can read it. An unknown or foreign ID answers -32602, and a request that does not declare the extension answers -32021.

Approvals and questions

When a client declares form elicitation (_meta["io.modelcontextprotocol/clientCapabilities"].elicitation), a run paused in needs_input asks the user directly:

The run is waiting for	The client is asked	Accept	Decline or dismiss
Approval of integration actions	One form per action, keyed by its approval ID (apr_…), describing what would be sent	Approves it	Denies it
An answer to the agent's question	One form with a reply field	Sends the reply and the run continues	Closes the run as completed

A dismissed approval is a denial, so nothing runs without an explicit yes. You can answer the forms in any order and a few at a time. The run resumes once every one has an answer, and the agent hears all the decisions together.

• With tasks: the task moves to input_required with the forms in inputRequests. Answer them with tasks/update.
• Without tasks: the tool returns "resultType": "input_required" with the forms and a requestState. Call the same tool again with the same arguments, plus inputResponses and that exact requestState. The state is sealed, bound to the tool and its arguments, and expires after an hour.
• Without form elicitation: nothing changes. The run comes back needs_input with pending_approval_ids for resolve_approvals, including as a completed task.

Events

The server implements the draft MCP Events extension (io.modelcontextprotocol/events), so a client can subscribe to things that happen in the account, such as order.paid or email_message.received, and react without polling. It is advertised in server/discover on both /mcp and /chatgpt.

The event types are the same ones as webhooks, and so is the payload: data.object is the resource exactly as its API endpoint returns it. events/list lists every type with its payloadSchema.

Subscribing

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

The response carries the subscription id (mcpsub_…), stable for the same credential, URL, event and arguments, and refreshBefore. Call events/subscribe again with the same values before refreshBefore to keep it; events/unsubscribe with name, arguments and delivery.url ends it at once.

• Verification. Before the first delivery to a URL, Crevio POSTs {"type":"verification","challenge":"<nonce>"} to it. Answer with a 2xx and {"challenge":"<nonce>"} within 5 seconds. Each credential verifies each URL once.
• Lifetime. Without ttlMs a subscription lasts a day. A suggested ttlMs is kept between one minute and one day. "ttlMs": null asks for no expiry, and Crevio grants it.
• Rotating the secret. Send a new delivery.secret on a refresh. For 10 minutes, deliveries carry signatures from both secrets.
• Limits. 100 live subscriptions per account. Subscribing only reads, so a read_only token can do it.

Deliveries

Each event is a POST of {"eventId", "name", "timestamp", "data"}, signed per Standard Webhooks with your secret (webhook-id, webhook-timestamp, webhook-signature) and carrying X-MCP-Subscription-Id. Verify the signature before you trust the body, and deduplicate on eventId.

What your endpoint does	What happens
Answers 2xx	Delivered
Answers 410 or 413	Dropped without retrying
Fails or times out (5 seconds)	Retried up to 4 more times over about 12 minutes, then dropped
Keeps failing for an hour	Deliveries stop until your next refresh turns them back on
Keeps failing for 3 days on a no-expiry subscription	Crevio POSTs {"type":"terminated",…} and deletes the subscription

If the credential loses access to the account (key deleted or expired, OAuth access revoked, user removed from the account), the next event ends the subscription with a terminated envelope carrying error -32024.

What it cannot do

• Webhook delivery only, by design for now. events/poll and events/stream answer -32026. Use the webhooks API or list_runs and the REST endpoints when you cannot receive POSTs.
• No replay. cursor is always null: events that happen while a subscription has lapsed are not delivered later. Read current state through the tools after a gap.
• No filters. Event types take no arguments. A subscription gets every event of its type in the account.

Errors use the extension's codes: -32602 invalid parameters (bad URL, secret or arguments), -32023 unknown event or subscription, -32024 no authenticated principal or access lost, -32025 subscription limit, -32026 delivery mode not offered, and -32027 the callback failed verification, with data.reason one of connection_refused, timeout, tls_error, http_4xx, http_5xx or challenge_failed.

Errors

Authentication failures are HTTP 401/403 on the request itself (WWW-Authenticate points at the OAuth metadata). Tool failures come back as a tool result with isError: true and a JSON body:

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

error	Meaning	What to do
run_busy	A run in this conversation is still in progress	Wait for it, then send_message
account_at_capacity	The account already has 5 runs going (http_status: 429)	Retry after retry_after_seconds
idempotency_error	An idempotency_key reused with a different message	Pass a new key for a new message
run_not_active	cancel_run on a run that already finished	Nothing — read its result
run_not_resumable	The run has no conversation to continue	Start a new job with ask_crevio
approvals_pending	send_message on a run blocked by approvals	resolve_approvals first
stale_resolution	The approvals you submitted don't match the pending set	get_run, then resubmit every pending_approval_ids entry
insufficient_credits	The account has no AI credits left	Add credits in Crevio
resource_missing	No run/task with that id on this account	Check the id — runs are account-scoped
validation_failed	A bad argument (e.g. an unknown approval_mode)	Fix the argument
rate_limit_exceeded	600 requests per minute per owner, shared with the REST API — or too many script runs in flight	Back off until X-RateLimit-Reset (rate limits), or wait for a script run to finish
forbidden	run_script by someone who isn't an account admin	Ask an admin, or delegate with ask_crevio
run_not_cancellable	cancel_script_run on a run that already started	Wait for it with wait_for_script_run

A script that throws still comes back as a script run, with status: "failed", its error, and the calls it made — run_script itself only errors when the run could not start or the wait ended.

Security

Every tool runs inside your account's tenant boundary. Delegated jobs run the Crevio agent with the permissions your account already has. run_script runs on your account's Crevio computer as the calling admin; its tools calls go through the same approval settings the agent obeys and the same API controllers as api.crevio.co, so authorization, validation, and error messages are identical to direct API calls. Tokens are as powerful as your account: only connect agents you trust, and revoke a token from Settings → Developers to cut a connection off instantly.

Next steps

Connecting

Client-by-client setup, OAuth, and curl examples.

Tasks (your AI workforce)

The Task / Task Run model every delegated job is built on — and how to schedule recurring work.

AI & Agents overview

How MCP, Tasks, and Events form Crevio's agentic model.

API conventions

The shapes, prefixes, and gotchas crevioApi shares with REST.

This documentation is built and hosted on Mintlify, a developer documentation platform.