MCP Server - Crevio

The Crevio MCP server lets any MCP-compatible agent delegate work to Crevio — and, when it wants the controls itself, drive the entire Crevio API in code. 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.
Direct API — api_search and api_execute let the connected agent discover and call every REST endpoint through code execution, 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": 60, "ask_timeout_max_seconds": 90, "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", "api_search", "api_execute"]
}

Recommended workflows

One-off jobs: `ask_crevio`

The default. One call starts a run, waits up to timeout_seconds, and returns the run with the agent’s final reply in result.

{
  "name": "ask_crevio",
  "arguments": {
    "message": "Which three products made the most revenue this month, and how does that compare to last month?",
    "timeout_seconds": 60,
    "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"
}

timeout_seconds defaults to 60 and is capped at 90. If the run is still going when it passes, the tool returns wait_timed_out with the run — call wait_for_run with its id to keep waiting. 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.
approval_mode is autonomous by default. supervised makes the run pause in needs_input for your review before it finishes (finish it with send_message, or let it stand); 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.

Direct API access: `api_search` + `api_execute`

When the connected agent wants to operate Crevio itself rather than delegate — or needs exact data shapes back — it drives the REST API in code. Rather than one tool per endpoint (403 operations across 280 paths would burn ~170k tokens of context before the agent did anything), Crevio uses Code Mode, inspired by Cloudflare’s approach: the agent writes code against two tools and chains as many calls as it likes in one round-trip.

api_search
api_execute

Read-only, idempotent discovery. A tools method returns every operation as a hash with "method", "path", "summary", "description", "tags", "parameters", "request_body".

tools.select { |t| t["tags"]&.include?("Discounts") }
     .map { |t| "#{t["method"]} #{t["path"]} — #{t["summary"]}" }

Runs Ruby in a sandboxed VM with get, post, patch, delete (paths auto-prefixed with /v1) and api_search("query"). The last expression is the result.

product = post("/products", name: "My Course", slug: "my-course", status: "draft")
post("/price_variants",
  product: product["id"],     # bare association name + prefix-id string
  name: "Standard", amount_type: "fixed",
  amount: 4900, currency: "usd", billing_type: "one_time")
patch("/products/#{product["id"]}", status: "active")

Every run returns {result, calls, output} — calls is an audit of each REST call with its status, so a nil in result is traceable to the call that failed.

api_execute dispatches through the same controllers as api.crevio.co, so the API conventions apply unchanged: params are unwrapped (no {product: {...}} wrapper), 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. A 404 resource_missing on a POST/PATCH is almost always a bad association id. Courses and other content live under /experiences, not /products.

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`, `idempotency_key`
`start_chat`	Delegate a job without waiting	`message` (required), `approval_mode`, `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`
`api_search`	Discover API endpoints by writing code over the catalog	`code` (required)
`api_execute`	Call the API by writing code (`get`/`post`/`patch`/`delete`)	`code` (required)

Every MCP connection has the full permissions of its token, so every tool is available on every connection — there are no per-tool scopes to grant. 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`)
`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.

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
`wait_timed_out`	The run hasn’t settled within `timeout_seconds`; the `run` is included	Call `wait_for_run` with `run.id`
`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	Back off until `X-RateLimit-Reset` (rate limits)

api_execute failures use the same envelope shape (error and no result) — a sandbox timeout, an exception in your Ruby, or an API error surfaced in calls.

Security

Every tool runs inside your account’s tenant boundary. Delegated jobs run the Crevio agent with the permissions your account already has; api_execute runs in a sandboxed Ruby VM (mruby — no filesystem, network, environment, or host primitives; 10-second timeout, 10 MB memory) and dispatches requests through the same API controllers as api.crevio.co, so authorization, validation, rate limiting, 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 api_execute shares with REST.

​Setup

​Recommended workflows

​One-off jobs: ask_crevio

​Long-running jobs: start_chat → wait_for_run → send_message

​Direct API access: api_search + api_execute

​Complete tool reference

​The run object

​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`

Direct API access: `api_search` + `api_execute`

Complete tool reference

The run object

Errors

Security

Next steps