Skip to main content
Grain ships a Model Context Protocol 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.
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.

​
What you get

Once connected, your assistant can:

Explore your schema

List every event your site tracks and the dimensions you can filter by.

Run queries

Breakdowns, timeseries, counts, and period‑over‑period comparisons — with the same surprise‑detection Kai uses.

Investigate drops

Cluster sessions, compare segments, analyze Tracks (start → goal funnels), and correlate events.

Generate digests

Daily summaries of what changed across your workspace, ready to paste into Slack or Notion.

​
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:
1

Client asks Grain what it needs

Grain responds 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource.
2

Client registers itself

The client calls /oauth/register (RFC 7591 Dynamic Client Registration) and gets a public, PKCE‑only client_id. No shared secrets.
3

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.
4

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.
You can revoke any client at any time from Settings → Connectors → MCP clients.
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.

​
Scopes

Grain offers three scopes so you can hand out exactly the access an assistant needs — no more, no less.
ScopeGrantsTypical use
mcp:readEvent list, dimension discovery, integration health”Is tracking wired up?”
mcp:queryQuery, count, compare, digest”Signups by country last week?”
mcp:investigateSegment 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

Claude

Claude.ai (web), Claude Desktop, and Claude Code.

Cursor

The AI‑first code editor.

ChatGPT

Via Developer Mode on Pro, Team, Enterprise, and Edu plans.

Any MCP client

Tool reference and raw endpoint details.

​
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 for your tool of choice.