MCP

Connect Claude, Codex, or any MCP client to Rills to read workspace data, query metrics, start workflows, and request or decide approvals.

The Rills MCP server lets an AI client read your workspace, answer questions with live metrics, start workflows, and route proposals into the approval queue. It uses the same credentials, scopes, and data rules as the REST API, so an agent never sees more than you granted.

#Server URL

Rills serves MCP over Streamable HTTP:

https://rills.ai/api/mcp/mcp

Settings → API & MCP access shows the exact URL and ready-to-copy setup for common clients.

#Connect

Clients that support MCP OAuth, such as Claude, only need the server URL. The client opens Rills, you sign in, choose the workspace, and approve the requested scopes. The connection then appears under Connected apps, where you can revoke it. This is the only way to let an agent approve or reject proposals, and it never exceeds your workspace role. See Authentication.

#Use an API key

For headless or shared agents, create a scoped key and pass it as a bearer header. Keep the key in an environment variable.

Claude Code:

claude mcp add --transport http rills https://rills.ai/api/mcp/mcp \
  --header "Authorization: Bearer $RILLS_MCP_KEY"

Codex (~/.codex/config.toml):

[mcp_servers.rills]
url = "https://rills.ai/api/mcp/mcp"
bearer_token_env_var = "RILLS_MCP_KEY"

Other clients:

{
  "mcpServers": {
    "rills": {
      "url": "https://rills.ai/api/mcp/mcp",
      "headers": { "Authorization": "Bearer ${RILLS_MCP_KEY}" }
    }
  }
}

#Tools

A client only sees the tools its scopes allow. Tools marked with payloads:read also need the domain scope in the same row.

Group	Example tools	Scopes
Workspace	`get_workspace`	`workspace:read`
Workflows and runs	`list_workflows`, `get_workflow`, `list_executions`, `get_execution`	`workflows:read`
Workflow payloads	`get_workflow_definition`, `get_execution_payloads`	`workflows:read`, `payloads:read`
Tables and forms	`list_tables`, `get_table`, `list_forms`, `get_form`, `list_form_submissions`	`tables:read` or `forms:read`
Table and form values	`query_table_rows`, `list_form_submission_payloads`	add `payloads:read`
Approvals	`list_approval_requests`, `get_decision`	`approvals:read`
Approval payloads	`get_approval_payload`	`approvals:read`, `payloads:read`
Decision records	`query_decision_records`, `get_decision_record_payload`	`records:read` (payload tool adds `payloads:read`)
Agents	`list_agents`, `get_agent`	`agents:read`
Agent payloads	`get_agent_payload`, `list_agent_conversation_events`	`agents:read`, `payloads:read`
Integrations	`list_integration_connections`, `get_integration_connection`	`integrations:read`
Files	`list_files`; `get_file_download_url`	`files:read`; download adds `payloads:read`
Metrics	`aggregate_workflow_executions`, `aggregate_approvals`, `aggregate_decision_records`, `aggregate_agent_conversations`, `aggregate_files`, `aggregate_table_rows`, `aggregate_form_submissions`	Same as the matching query dataset
Actions	`trigger_workflow`, `request_approval`	`workflows:execute`, `approvals:request`
Authoring	`author_workflow`, `revise_workflow`, `get_authoring_result`	`workflows:create`, `workflows:update`, `workflows:read`
Optimization suggestions	`list_optimization_suggestions`	`optimization:read` (values add `payloads:read`)
Decisions	`approve`, `reject`, `undo_approval_decision`	`approvals:decide`, OAuth only
Suggestion decisions	`decide_optimization_suggestion`, `revert_optimization_suggestion`, `restore_optimization_suggestion`	`optimization:decide`, OAuth only

The client’s tool list is the source of truth for exact names and inputs.

#Metrics tools

Aggregate tools take the same request as POST /query without the dataset key, follow the same rules, return at most 100 rows per call, and draw from the same rate-limit budget. Ask an agent “How many outbound runs failed each day last week?” and it can answer from live data.

#Approving from an agent

approve and reject exist only on OAuth connections and never on API keys. The agent must show you the proposal and get your agreement before it can confirm the decision. Every decision is recorded the same way as one made in the app or on mobile. Rejection feedback helps calibrate confidence scoring.

Suggestion tools follow the same rule. Accepting a suggestion changes the workflow at once, so the agent must show you the change and get your agreement first. revert_optimization_suggestion undoes an accept and restore_optimization_suggestion undoes a dismissal, at any time.

#Limits

Each tool result is capped at 256 KiB. If a result is too large, the tool asks for a smaller page; lower limit or narrow filters.
MCP requests are rate limited per client IP and per connection. Metrics tools also count against the query budget.
Reading data doesn’t use action credits. Workflows started through trigger_workflow are billed like any other run, and approvals are free.