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. 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.
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.
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.
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.
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 — 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.

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.

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`, `idempotency_key`
`start_chat`	Delegate a job without waiting	`message` (required), `approval_mode`, `speed`, `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`
`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`, `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), `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)

Which tools a connection sees depends on its credential:

API key — every tool. API keys aren’t scoped.
OAuth token with read_only — the default when a client asks for no scope. Only the tools that read: whoami, get_run, wait_for_run, list_chats, get_chat, list_runs, list_messages, list_integrations, list_integration_tools, get_script_run, and wait_for_script_run.
OAuth token with read_write — every tool, including delegating work (ask_crevio, start_chat, send_message), resolve_approvals, cancel_run, run_script, and cancel_script_run.

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, in full (present once the run has settled)
`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.

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`
`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 token, 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

​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

Events

Subscribing

Deliveries

What it cannot do

Errors

Security

Next steps