MCP Integration

List my open tasks
Show the Website Redesign project
Create a task to review the PR

Authentication

Rollout uses OAuth 2.1 with PKCE. This means:

• No passwords stored in your Claude Code config
• Access tokens expire after 1 hour and are refreshed automatically; refresh tokens expire after 30 days
• Scopes limit what the assistant can do
• Everything runs as you — an MCP client can never see or change more than your own membership allows

OAuth scopes

When authorizing, you see which scopes are requested:

Revoking access

There is no in-app page for managing authorized MCP clients yet. To stop an assistant's access:

• Remove the Rollout server from the client's MCP configuration — without a refreshed token, access ends when the current access token expires (at most 1 hour)
• MCP clients can revoke their own tokens at the standard /oauth/revoke endpoint

Available tools

Reading and discovery

These tools work with the read scope and never change data:

Querying Record by a schema's own fields: the filter key is the bare field name (company:acme, not data.company), and those keys are only in scope when the same filter pins exactly one object with a positive object: or object_id: term. workspace_context(include:["query_sources"]) lists only the static Record filters; read the per-schema field names, types, position and display_config from include:["objects"].

text, number, date, boolean, select and user_ref fields are filterable out of the box. rich_text and formula fields are filterable only where display_config.filterable was turned on — their default is false — and a formula must return a number. datetime, json and list fields expose no filter key at all, even though display_config reports filterable: true for all three. Filtering on one of those names rejects the entire query in either strict setting.

Rich text reads as Markdown: a description, a Document's content, an Activity's body and a record's rich-text values in data. Pass format: "json" for the editor's document JSON instead. A list row carries a plain-text summary (at most 160 characters) in place of the body; name the body in fields, or read one record by ref, to get it. Writes take the same Markdown back: a string is always Markdown and a map is document JSON, so you can read, edit and write back without converting.

Custom values come back inside the record's data object, not as top-level keys. A fields name may be a dotted path, so fields:["data.company"] returns that one value and drops its siblings, while fields:["data"] returns all of them. A shared field whose name matches one of the record's own serialized keys (id, ref, slug, title, number, primary_status, primary_date, object_id, object, data, created_at, updated_at, display) is shadowed at the top level, and which of those a read emits varies (object and display need a read that pins one object, and a schema-pinned list read drops ref and slug), so name the custom value as data.<field_name> to reach it. A requested name that resolves in no returned row is dropped: a list read reports it in warnings, a ref read hands back the record alone and cannot.

Shared write tools

These tools work across resources. Each lists the sources it supports in its source field, and each source keeps its own authority rules.

Tasks and planning

Write tools require the write scope:

Cycles and Cycle Schedules belong to exactly one Team, so query on Cycle or CycleSchedule needs a team: filter; there is no workspace-wide current Cycle. Cycle takes state:current (the default: opening, open, or finalizing), state:next (the Team's earliest scheduled Cycle), or state:completed; a ref read returns the same row and adds the Team-lane progress report with preloads:["report"]. Only members of the Team can read its Cycles. A CycleSchedule row carries the lock_version, effective cadence, and the activation/deactivation previews cycle_schedule works from.

Workflows

Each workflow tool's description names a guide topic that carries its full contract: workflow.settings, workflow.edit, workflow.inspect, workflow.release and workflow.run.

A new workflow is two calls: upsert creates it with no graph, then workflow_edit gives it one. A workflow without a graph needs no guard for its first edit. For a whole graph, send one replace_flow operation so the complete nodes-and-edges document is validated and written under one optimistic lock. Any edit that changes the graph's structure ends with a full layout of the Draft; nodes locked with locked: true (or data.locked) keep their positions and the rest is laid out around them. A node or edge the canonical shape would have to drop is refused by name rather than silently repaired. update_node supports merge or replacement modes for both config and execution settings, plus explicit top-level key removal. set_schedule updates a schedule's cron, timezone, and description without rebuilding the graph. workflow_inspect and node_types accept read-scoped tokens and survive read-only mode; every other workflow tool requires write.

workflow_inspect tells a caller what a workflow takes and returns before it starts one. action: "status" (the Current release) and action: "release" (the release asked for) return contract: {entry_node_id, inputs, outputs, digest}. inputs is a JSON Schema of the inputs the Manual start declares (required lists what must be sent, default what an absent key becomes, enum the allowed values, and any other key is refused), or null when it declares none and takes any object. outputs is a JSON Schema of what the workflow's return steps declare, or null when they declare nothing. digest changes whenever either does. Build workflow_run start's input_data from contract.inputs: a start missing a required input or sending a key no input declares is refused with every field named, and no run is created. A workflow the caller cannot read returns not found and no contract. A Tool on Run workflow declares the same inputs as typed arguments. It starts its workflow only when an AI agent step calls it inside a workflow run, so invoke refuses it and says so; start the workflow with workflow_run.

workflow_inspect with action: "branches" names this workflow's live authoring branches as identity only — id, name, revision (the branch's lock version), has_draft, timestamps — plus main_draft_revision for the main Draft, which is the workflow row and is never listed as a branch. It is how a branch id is obtained without opening the editor: action: "releases" names only branches that already published something. The graphs are neither returned nor read. Read one exact source with action: "source".

create_branch cuts a new branch from the source its selector names, using the same grammar as a source inspection's selector ({"kind":"release","id"|"name"} with "current" accepted as the name, {"kind":"branch","id"}, or {"kind":"main_draft"}, which is the default). It is the only operation in its call. A release is named by id and re-resolved server-side, so the branch's baseline is that release exactly as published. Nothing else moves: no existing Draft, no other branch, no published pin. It switches nothing and runs nothing.

The response's source is the RESOLVED selector, not the one that was sent: ask for {"kind":"release","name":"current"} and it comes back as that release's exact id, because Current is an alias that moves on the next publish. source_revision carries the baseline's lock version (null for a release). Sending source_revision pins the cut: a Draft that moved since the revision you inspected is refused with stale_source rather than seeding a graph you never read.

Graph edits carry expected: the expected_source object of the exact Draft the caller inspected. It also decides which Draft the batch writes:

{"source": {"kind": "main_draft"}, "source_revision": 7, "source_digest": "sha256:..."}
{"source": {"kind": "branch", "id": "<branch id>"}, "source_revision": 3, "source_digest": "sha256:..."}

guide(topic:"tool.templates",args:{"connection_id":"<uuid>"})
guide(topic:"tool.template",args:{"connection_id":"<uuid>","remote_tool":"<name>"})

Read the complete editable list and its write guards:

tool(action:"read",consumer:{"consumer_kind":"app","consumer_id":"<uuid>"})

consumer_kind is app, agent or workflow; a Workflow selector also requires node_id. tool action:"configure" replaces the complete tools list using the returned expected and expected_version values. Recipes contain a local name and label, plus either node_type and settings, or connection_id, remote_tool and settings.

tool action:"remove" takes those same guards and an action_ref containing id, name and path. To repair an unavailable action, edit its recipe and Save the complete owning list. Healthy siblings remain callable. Local and nested actions exist only for rollout.ai with tool_mode:"replace"; under inherit or none the list must be [], and a non-empty list is refused. Switching a node out of replace clears its list.

Save validates configuration and target consent together. MCP-authored configuration using per-call never requires an exact human review under workspace policy. Pending replacements remain unavailable until approval. tool action:"readiness" reports draft validation, not a promise that a later dispatch will succeed.

tool action:"grants" inspects an exact attachment address and attachment_id. delegate additionally takes the observed action digest as expected and a stable request_key; it requests human consent rather than granting access immediately. review_status and review_cancel take approval_id. revoke_delegation takes the exact delegation UUID. Revocation closes affected undispatched calls and their pending reviews; running, unknown and completed evidence remains intact.

Direct calls and large payloads

invoke action:"run" selects exactly one target:

• attachment: {consumer_kind,consumer_id,node_id?,path?,name};
• node_type with settings;
• connection_id with the discovered remote_tool;
• app: an App id or slug for a source update.

An attachment selector requires configuration access—App/Agent management or Workflow authoring write—plus invoke permission. It selects App live, Workflow published or Agent default configuration and executes as the current authenticated caller. It does not run that consumer or borrow its grants, accounts or installations. A caller-selected run ID cannot supply execution authority. Actual App and admitted Workflow execution use their own server-owned consumer context.

Every new call requires a stable idempotency_key. Selecting an exact, accepted consumer attachment preserves its configured per-call policy: always requires a human decision; never can run without a fresh ask. The caller must independently retain configuration access, invoke permission and current target and resource rights. Selecting configuration never transfers the consumer's authority, identity, grants or installations.

Raw one-off node_type, connection_id/remote_tool and App-source requests require one exact human review, including read-only recipes. Configuration, target and call review are combined into that decision. No saved action or reusable target grant is created. An Agent caller remains an Agent.

For example:

invoke(action:"run",
  node_type:"rollout.query",
  settings:{"presets":{"source":"Team"},"slots":{"query":{}}},
  arguments:{"query":"name:Operations"},
  idempotency_key:"operations-query-001")

Reuse the key only for the exact same selector, settings and arguments. Changed requests conflict. An intentional new business call uses a new key. An outcome_unknown call requires reconciliation; do not submit it again under a new key.

For the App source shortcut, arguments is {"source":{"entry":"index.tsx","files":{...}},"expected_version":...}. Keep the version you observed. An approved successful native source update goes through Save and becomes live without a separate Publish step.

Results up to 16 KiB are returned inline. Larger results expose result_bytes; retrieve them with invoke action:"result".

For a large request:

1. Write the exact JSON object bytes to body.json and compute their SHA-256, including whitespace and key order.
2. Call invoke action:"run" with the target, idempotency_key, presign:true and body_sha256:"sha256:<64 lowercase hex>". Omit arguments.
3. Use the returned request.curl to POST those bytes. The reply includes invocation_id; 202 means approval is pending or execution continues. When review is required, match it using the returned binding_code.

status, result and cancel take that existing invocation_id. status reports state, approval details and bounded results. cancel withdraws your undispatched call. After a transport timeout, inspect the existing call before retrying.

result returns a single-use GET receipt and download command for /api/tenants/<tenant_id>/tool-results. It reads the immutable succeeded result. Detaching the original configuration does not erase that history. Current principal and original source authorization remain required. Use the same API key, or a current OAuth token in the original family; another API key owned by the same user is a different source.

Admission and result bearers expire within ten minutes and are single-use. Accepted calls and human reviews have their own lifetime. Bearer expiry does not erase an accepted call: follow that admitted call with its invocation_id. A consumed admission bearer cannot be reused. If a result bearer expires or has been consumed, invoke action:"result" can issue a fresh receipt while the original source remains authorized. run and cancel require MCP write; status and result require read.

Private transport accepts at most 2 MiB of request bytes and 4 MiB of result bytes. App/model execution keeps its separate 200,000-byte result ceiling and App source constraints. Outbound MCP responses retain their 2,000,000-byte cap. An uncertain external effect is recorded as outcome_unknown, never silently replayed.

See guide(topic:"tool.lifecycle") and guide(topic:"invoke.transport") for the current contracts.

Documents and records

Collaboration and organization

Dashboards

Dashboards are Pages with immutable applied widget revisions. Saved Views are reusable query presentations that a Table widget may reference; they are not dashboard layouts.

Recommended flow: guide(topic:"dashboard.authoring") for the widget catalog, guide(topic:"dashboard.viz") for chart and stat widgets, dashboard(action:"create", dry_run:true), then dashboard(action:"create"). Re-read with query(source:"Dashboard", ref) before a guarded update or edit.

For a Metric chart, select a metric_definitions entry from guide(topic:"dashboard.viz") and persist its recommended_bucket_fn; workspace_context(include:["query_sources"]) also exposes tenant-scoped Metric name values. For custom-record aggregates, copy the selected Record source's canonical required_query so the executor loads that schema's shared fields.

Dashboard replies no longer carry policy.can_read (a dashboard you can read is one you were returned), the list-level policy.can_create and owner_id_for_new_dashboard, or next_offset (page with limit/offset and has_more). Widget catalog entries no longer carry catalog_zones, page_zones or picker_enabled (use pickable; every Page widget lives in the main zone). Whether you may create a dashboard, and the owner id a new one gets, are in guide(topic:"dashboard.authoring") under caller.

MCP can create, revise, share, assign, archive, and restore dashboards. Publishing a Page to a public URL remains an owner/admin action in the web UI because public data/form bindings require a separate security review. Dashboard authoring is capped at 100 widgets and a 1 MiB encoded composition document.

Administration

These require the admin scope:

Configuration

Read-only mode

For safer AI access, self-hosted deployments can enable read-only mode, which removes all write tools from the server:

export ROLLOUT_MCP_READ_ONLY=true