> ## Documentation Index > Fetch the complete documentation index at: https://crevio.co/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 call the whole Crevio API in code. **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](/docs/developer/guides/api-overview). | | | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL** | `https://mcp.crevio.co/mcp` | | **Transport** | Streamable HTTP (stateless — every request is self-contained) | | **Authentication** | `Authorization: Bearer ` — the same [API token](/docs/developer/guides/api-overview#creating-api-tokens) you use for REST. OAuth 2.1 is also supported; see [Connecting](/docs/developer/mcp/connection). | | **Discovery** | `https://mcp.crevio.co/mcp/server-card` | New to Crevio's agentic model? Start with the [AI & Agents overview](/docs/developer/guides/agents-overview) to see how MCP, [Tasks](/docs/developer/guides/tasks), and [Events](/docs/developer/guides/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 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. **Claude Code** ```bash theme={null} 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`, …): ```json theme={null} { "mcpServers": { "crevio": { "url": "https://mcp.crevio.co/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Client-specific steps, OAuth, and raw `curl` examples are on the [Connecting](/docs/developer/mcp/connection) page. 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. ```json theme={null} { "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`. ```json theme={null} { "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" } } ``` ```json theme={null} { "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: 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. 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 — delegated jobs and your scheduled [Tasks](/docs/developer/guides/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](https://blog.cloudflare.com/code-mode-mcp/): the agent writes code against two tools and chains as many calls as it likes in one round-trip. Read-only, idempotent discovery. A `tools` method returns every operation as a hash with `"method"`, `"path"`, `"summary"`, `"description"`, `"tags"`, `"parameters"`, `"request_body"`. ```ruby theme={null} 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. ```ruby theme={null} 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](/docs/developer/guides/api-overview#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`](/docs/developer/guides/tasks) 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](/docs/developer/guides/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: ```json theme={null} { "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](/docs/developer/guides/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 Client-by-client setup, OAuth, and curl examples. The Task / Task Run model every delegated job is built on — and how to schedule recurring work. How MCP, Tasks, and Events form Crevio's agentic model. The shapes, prefixes, and gotchas `api_execute` shares with REST.