MCP Server - Crevio

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`

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

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.

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.

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:

start_chat queues the work and returns the run immediately. Its chat_id stays null until the run starts; send_message takes the run id in its place.
wait_for_run (bounded) or get_run (instant) until status is completed, failed, or needs_input.
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.
resolve_approvals when a run is paused on an integration action (needs_input with pending_approval_ids). Pass the run_id and approve or deny every pending id at once, and the run resumes.
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
Run

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

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. approvals lists what its gated calls froze, each with its current status, and pending_approval_ids the ones still waiting. 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 call that needs approval (requires_approval in the listing) does not run. It resolves to {pending: true, draft_id, approval} and the script carries on, so check result.pending before you use a write’s result. Answer it with resolve_approvals (no run_id), in Crevio, or in the reply itself (see Approvals and questions). Approving runs that one frozen call, never the script again, and the approval then holds its result or error. An approval nobody answers is denied after 7 days.
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 actions a run is paused on, or a script run’s approvals	`approvals: [{id, approved, reason}]` (required), `run_id` for a paused run
`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 elicitation (_meta["io.modelcontextprotocol/clientCapabilities"].elicitation), a run paused in needs_input, and a finished script run whose calls wait for approval, ask the user directly:

Waiting for	The client is asked	Accept	Decline	Dismiss (cancel)
Approval of an action	One form per action, keyed by its approval ID (`apr_…`), describing what would be sent	Approves it	Denies it	Leaves it pending
Approval of a login or card fill, or an app form that asks for a secret	A link (URL mode) to Crevio, where the user signs in as themselves to answer	Opens Crevio	Leaves it pending	Leaves it pending
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	Leaves it waiting

Nothing runs without an explicit yes, and a dismissed question is asked again later rather than answered for you. A client that cannot show links is not asked about logins and card fills: answer those in Crevio. A Crevio link opens only for the user it was made for. You can answer the forms in any order and a few at a time. A paused run resumes once every one has an answer, and the agent hears all the decisions together. A script run’s approvals stand alone: each runs as soon as it is approved.

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, its arguments and the user it asked, and expires after an hour. Answers sent with another user’s credential are refused.
Without form elicitation: nothing changes. The run comes back 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, `approval_mode` or `speed`	Pass a new key for a new request
`run_not_active`	`cancel_run` on a run that already settled, cancelled included	Nothing — read its `result`
`resource_missing`	A `starting_after` or `ending_before` that matches nothing in the list (`param` names which)	Page again from the first page
`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
`approval_not_pending`	`resolve_approvals` on an approval already answered or expired	Read it with `get_script_run`; make the call again for a new approval
`input_required`	`resolve_approvals` approving a connected app’s form nobody filled in	Fill it in and answer it in Crevio
`permission_denied`	`resolve_approvals` on an approval you may not answer (a card fill is an admin’s)	Ask an account admin
`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.

​Setup

​Recommended workflows

​One-off jobs: ask_crevio

​Long-running jobs: start_chat → wait_for_run → send_message

​Scripts: run_script

​Complete tool reference

​The run object

​MCP Tasks and elicitation

​Async tool calls

​Approvals and questions

​Events

​Subscribing

​Deliveries

​What it cannot do

​Errors

​Security

​Next steps

Connecting

Tasks (your AI workforce)

AI & Agents overview

API conventions

Setup

Recommended workflows

One-off jobs: `ask_crevio`

Long-running jobs: `start_chat` → `wait_for_run` → `send_message`

Scripts: `run_script`

Complete tool reference

The run object

MCP Tasks and elicitation

Async tool calls

Approvals and questions

Events

Subscribing

Deliveries

What it cannot do

Errors

Security

Next steps