> ## 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 overview

> Let Claude, Cursor, ChatGPT, and any MCP-aware agent query your Grain workspace directly.

Grain ships a [Model Context Protocol](https://modelcontextprotocol.io/) server so AI assistants can ask questions against your analytics data the same way you would in the dashboard — no custom integration, no glue code.

<Note>
  **What is MCP?** An open protocol (created by Anthropic, now supported by OpenAI, Cursor, and others) that lets LLMs call external tools. Think of it as USB‑C for AI assistants — one plug, many tools.
</Note>

## What you get

Once connected, your assistant can:

<CardGroup cols={2}>
  <Card title="Explore your schema" icon="list-tree">
    List every event your site tracks and the dimensions you can filter by.
  </Card>

  <Card title="Run queries" icon="chart-column">
    Breakdowns, timeseries, counts, and period‑over‑period comparisons — with the same surprise‑detection Kai uses.
  </Card>

  <Card title="Investigate drops" icon="magnifying-glass-chart">
    Cluster sessions, compare segments, analyze Tracks (start → goal funnels), and correlate events.
  </Card>

  <Card title="Generate digests" icon="sparkles">
    Daily summaries of what changed across your workspace, ready to paste into Slack or Notion.
  </Card>
</CardGroup>

## Endpoint

```
https://grainql.com/api/mcp
```

This is the only URL you'll ever paste into a client. It speaks MCP over **Streamable HTTP** and auto‑discovers the OAuth flow on first connect.

## How auth works (the short version)

Grain is its own OAuth 2.1 authorization server. When an MCP client hits the endpoint without a token:

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

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

  <Step title="You approve in the browser">
    Grain opens a consent screen where you pick the workspace and review the scopes being granted. A 7‑day preview shows what the assistant will actually be able to see.
  </Step>

  <Step title="Client gets a token">
    After you click **Authorize**, the client receives a short‑lived `mcpat_…` access token and a `mcprt_…` refresh token. Both are scoped to the workspace you picked.
  </Step>
</Steps>

You can revoke any client at any time from [Settings → Connectors → MCP clients](https://grainql.com/dashboard/settings?tab=connectors\&category=mcp).

<Tip>
  Not comfortable giving an AI agent access to production data yet? Create a test workspace, connect that, and kick the tires before pointing it at real events.
</Tip>

## Scopes

Grain offers three scopes so you can hand out exactly the access an assistant needs — no more, no less.

| Scope             | Grants                                                           | Typical use                         |
| ----------------- | ---------------------------------------------------------------- | ----------------------------------- |
| `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?" |

Clients request the scopes they need at authorize time. The consent screen shows every scope in plain English before you approve.

## Pick your client

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

  <Card title="Cursor" href="/ai-tools/mcp/cursor">
    The AI‑first code editor.
  </Card>

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

  <Card title="Any MCP client" icon="code" href="/ai-tools/mcp/tools">
    Tool reference and raw endpoint details.
  </Card>
</CardGroup>

## Limits and safety

* **Workspace‑pinned.** Every token carries exactly one `tenantId`, chosen at consent. An assistant cannot cross workspaces within a session.
* **Per‑request budget.** Each MCP request is capped at 16 backend calls so a chatty agent can't accidentally DDoS your data.
* **Read‑only in v1.** No tool in the current surface writes, deletes, or mutates. You can safely hand an assistant the `mcp:investigate` scope without worrying it will change a segment definition.
* **Encrypted at rest.** Upstream tokens are AES‑GCM encrypted before they hit the database. Grain‑issued tokens are stored only as SHA‑256 hashes.

Ready to connect? Start with the [client setup page](/ai-tools/mcp/claude) for your tool of choice.