> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> The Grain MCP server lets Claude, Cursor, ChatGPT, and any MCP client query your analytics data.

Grain runs a [Model Context Protocol](https://modelcontextprotocol.io/) server. An AI assistant
that connects to it can ask questions of your analytics data, the same questions you ask in the
dashboard. No custom integration is required. MCP is an open protocol that lets a language model
call external tools.

## What an assistant can do

| Task | What the assistant does | Scope |
| - | - | - |
| Explore the schema | Lists every event your site tracks and the dimensions you can filter by. | `mcp:read` |
| Run queries | Breakdowns, time series, counts, and period-over-period comparisons, with the same surprise detection that Kai uses in the dashboard. | `mcp:query` |
| Investigate a drop | Clusters sessions, compares segments, analyzes Tracks (start to goal funnels), and correlates events. | `mcp:investigate` |
| Write a digest | Summarizes what changed in your tenant for a day or a week, ready to paste into Slack or Notion. | `mcp:query` |

Read [Tools](/ai-tools/mcp/tools) for every tool and its inputs.

## Endpoint

<Card title="MCP endpoint" icon="plug" horizontal>
  `https://www.grainql.com/api/mcp`
</Card>

This is the only URL you paste into a client. The server speaks MCP over Streamable HTTP. A client
discovers the OAuth flow on its first connection.

<Warning>
  Include `www`. The `grainql.com` address without `www` redirects, and MCP clients drop the
  sign-in token on that redirect. The client then connects but shows no tools.
</Warning>

## The OAuth flow

Grain is its own OAuth 2.1 authorization server. When an MCP client calls the endpoint without a
token, this happens:

<Steps>
  <Step title="The client asks Grain what it needs">
    Grain responds `401` with a `WWW-Authenticate` header that points at
    `/.well-known/oauth-protected-resource`.
  </Step>

  <Step title="The client registers itself">
    The client calls `/oauth/register` (RFC 7591 Dynamic Client Registration) and receives a
    public, PKCE-only `client_id`. There are no shared secrets.
  </Step>

  <Step title="You approve in the browser">
    Grain opens a consent screen. You choose **All workspaces in my account**, or
    **Select workspaces** and tick the ones the assistant will see. You read the scopes that the
    client asks for. A workspace on the consent screen is a tenant.
  </Step>

  <Step title="The client receives a token">
    After you click **Authorize**, the client receives a short-lived `mcpat_…` access token and
    an `mcprt_…` refresh token. Both are scoped to the workspaces you chose.
  </Step>
</Steps>

You can revoke any client at
[Settings → Connectors → MCP clients](https://grainql.com/dashboard/settings?tab=connectors\&category=mcp).
If you do not want to give an assistant access to production data yet, create a test tenant and
connect the assistant to that tenant first.

## Scopes

Grain has three scopes. A client asks for the scopes it needs at authorize time. The consent
screen shows every scope in plain English before you approve.

| Scope | Grants | Example question |
| - | - | - |
| `mcp:read` | Event list, dimension discovery, integration health | "Is tracking wired up?" |
| `mcp:query` | Query, count, compare, digest | "Signups by country last week?" |
| `mcp:investigate` | Segment compare, session cluster, track analyze, correlate event | "Why did checkout drop on Tuesday?" |

Read [Security and scopes](/ai-tools/mcp/security) for what each scope unlocks and how tokens
are stored.

## Clients

<CardGroup cols={2}>
  <Card title="Claude" href="/ai-tools/mcp/claude">
    Claude.ai on the web, Claude Desktop, and Claude Code.
  </Card>

  <Card title="Cursor" href="/ai-tools/mcp/cursor">
    The Cursor editor and its agent.
  </Card>

  <Card title="ChatGPT" href="/ai-tools/mcp/chatgpt">
    Developer Mode on the Pro, Team, Enterprise, and Edu plans.
  </Card>

  <Card title="Tools" href="/ai-tools/mcp/tools">
    The tool reference for any other MCP client.
  </Card>
</CardGroup>

## Limits

| Limit | Value | Where |
| - | - | - |
| Backend calls | 16 per MCP request | Every tool call. `grain_query_compare` counts as 2. |
| Tenants per token | 1 | Every `mcpat_…` token. Chosen at consent. |
| Preview window | 7 days | The consent screen. |

If an agent reaches the budget, it receives a structured error. The agent then asks you to
narrow the question.

## Safety

* Every token carries exactly one `tenantId`, chosen at consent. An assistant cannot cross
  tenants in a session.
* Version 1 is read-only. No tool writes, deletes, or changes data. You can grant
  `mcp:investigate` without a risk that the assistant changes a segment definition.
* Grain encrypts upstream tokens with AES-GCM before it writes them to the database. Grain
  stores its own tokens only as SHA-256 hashes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.