MCP server - Grain Analytics

Grain runs a Model Context Protocol 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 for every tool and its inputs.

Endpoint

MCP endpoint

https://grainql.com/api/mcp

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.

The OAuth flow

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

The client asks Grain what it needs

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

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.

You approve in the browser

Grain opens a consent screen. You pick the workspace and read the scopes that the client asks for. A workspace on the consent screen is a tenant. A 7-day preview shows what the assistant will see.

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 tenant you picked.

You can revoke any client at Settings → Connectors → MCP clients. 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 for what each scope unlocks and how tokens are stored.

Clients

Claude

Claude.ai on the web, Claude Desktop, and Claude Code.

Cursor

The Cursor editor and its agent.

ChatGPT

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

Tools

The tool reference for any other MCP client.

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.

​What an assistant can do

​Endpoint