Skip to content

MCP server

Rig exposes a Model Context Protocol server. An MCP client or AI agent connected to it can read the workspace's context layer, search tables, columns and metrics, and run governed, read-only SQL against the warehouse.

The full tool list is in the MCP tools reference.

Endpoint

https://app.rig.so/mcp/{client_id}/
Item Value
Transport Streamable HTTP, stateless
Required request header Accept: application/json, text/event-stream
Authentication OAuth 2.1 or an API token
Alternative URL form https://app.rig.so/{client_id}/mcp/, for clients that discover OAuth metadata from the server's path

The server offers tools. It does not offer MCP resources or prompts.

Connecting a client

Claude Code

claude mcp add --transport http --callback-port 19876 rig https://app.rig.so/mcp/jaffleshop/

Cursor (mcp.json)

{
  "mcpServers": {
    "rig": {
      "type": "http",
      "url": "https://app.rig.so/mcp/jaffleshop/",
      "oauth": { "callbackPort": 19876 }
    }
  }
}

Codex

codex mcp add rig --url https://app.rig.so/mcp/jaffleshop/
codex mcp login rig

Claude (web and desktop)

Add a custom connector with the URL https://app.rig.so/jaffleshop/mcp/.

Each of these signs you in through your browser the first time it connects.

Connecting with a token

Unattended clients send an API token with the mcp scope instead of signing in.

curl -X POST https://app.rig.so/mcp/jaffleshop/ \
  -H "Authorization: Bearer rig_mcp_jaffleshop_EXAMPLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

A token is bound to one workspace and acts with its owner's role. For an agent, create a dedicated agent identity so that it has its own role, tool profile and call limit. See Authentication.

Working with more than one workspace

Every tool accepts an optional client_id argument. A user who signs in with OAuth and belongs to more than one workspace passes it to choose the workspace; each call is authorised against that workspace. A token only ever reaches the workspace it was created in.

SQL behaviour

  • Read-only. execute_sql accepts a single read-only statement. Statements that modify data or schema, and multi-statement requests, are rejected before they reach the warehouse. The separate tool call_procedure runs a stored procedure, and only one that the workspace has explicitly allow-listed.
  • Permissions. Your role's schema, table, column and row permissions are applied to every query.
  • Row limit. execute_sql returns 100 rows by default and at most 500. A truncated result is flagged with truncated: true.
  • Cost guard. On BigQuery a workspace can set a scan budget; execute_sql rejects a query whose estimated scan is over it. No other warehouse enforces a budget. dry_run_sql returns the scan estimate, on warehouses that can report one, without running the query.

Changing the context layer

Tools such as manage_metric, manage_business_term, manage_usage_rule and update_description write to the context layer. They follow the same permissions as the application: if your role may only propose changes, the change is queued for a reviewer to approve instead of being applied.

Limits

Requests are rate limited per credential (60 per minute by default). A request over the limit receives 429 with a Retry-After header.