Claude - GrainQL

The GrainQL MCP server works with every Claude surface: the web app, the desktop app, and the Claude Code CLI. The OAuth flow is the same on each one. You need an active GrainQL tenant and a Claude plan that supports custom connectors. Custom connectors are available on Claude Free, Pro, Max, Team, and Enterprise. A Free account is limited to one custom connector.

1. Open the connector settings

In Claude, click your profile, then Settings → Connectors. On the Team and Enterprise plans, an owner adds the connector for the organization under Organization settings → Connectors. Members then connect one by one.

2. Add a custom connector

Click + Add connector, then Add custom connector. On Team and Enterprise the path is Add → Custom → Web.

3. Paste the GrainQL endpoint

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

Do not change Advanced settings. GrainQL registers the client with RFC 7591 Dynamic Client Registration. You do not enter a client ID or a secret.

4. Authorize in the browser

Claude opens the GrainQL consent screen. Choose All workspaces in my account, or Select workspaces and tick the ones that Claude will see. Read the scopes, and click Allow access. A workspace on the consent screen is a tenant. With all workspaces, name the workspace in your prompt, or Claude asks which one you mean. Then you return to Claude with the connector enabled.

5. Turn it on in a chat

In a conversation, click the + button, open Connectors, and switch GrainQL on. Then ask a question, for example “What were my top 5 traffic sources last week?”. Claude calls grain_query, describes the result, and cites the rows it used.

The first tool call of a new session is the slowest. Claude discovers the tool surface on that call. Later calls are faster.

Claude Code

Claude Code has a CLI for MCP servers. One command adds the GrainQL server.

Install Claude Code. If you have it, make sure that you have a recent version. Remote HTTP transport is a recent addition.
npm install -g @anthropic-ai/claude-code
Add the GrainQL server.
claude mcp add --transport http grain https://www.grainql.com/api/mcp
Add --scope user to make GrainQL available in every project. Add --scope project to write the connection to .mcp.json for your team.
Authenticate. Inside Claude Code, run /mcp, select grain, then Authenticate. The CLI opens the GrainQL consent screen in your browser. Approve the tenant. Then control returns to the terminal.
Ask Claude Code a question that needs GrainQL data, for example “Which pages had the biggest drop in conversions this week versus last?”. Claude Code picks the tool (grain_query_compare or grain_segment_compare), runs it, and summarizes the result.

These commands manage the server:

claude mcp list
claude mcp get grain
claude mcp remove grain

list shows every server. get grain shows the GrainQL server. remove grain deletes it. The Claude Code documentation on MCP is at code.claude.com/docs/en/mcp.

What the assistant can do

With all three scopes granted, Claude has twelve tools. These prompts are a good start:

Prompt	Tools
”What events do I track, and which dimensions can I break them down by?”	`grain_events_list`, `grain_dimensions_discover`
”Give me a digest of what changed this week: metrics, sources, and anything that looks surprising.”	`grain_query_digest`
”Checkout conversions fell Tuesday. Compare the users who dropped against those who converted and tell me what is different.”	`grain_segment_compare`, `grain_sessions_cluster`
”Is my analytics tag firing correctly?”	`grain_integration_status`

The digest result includes the GrainQL surprise hints (concentration, volatility, rank changes), so the summary names anomalies, not only numbers. Run the tracking audit before an investigation, so that you know the data is complete. Read Tools for every tool.

Troubleshooting

Symptom	Cause	What to do
The Connect button does nothing, or the OAuth window does not open.	Claude Desktop has no default browser, or the web app cannot open a popup.	On macOS, set System Settings → Desktop & Dock → Default web browser. On the web, allow popups for `claude.ai`.
”Invalid tenant” or `403` after you authorize.	You picked a workspace that you do not belong to.	Revoke the connection at Settings, MCP clients and connect again. The consent screen shows only the workspaces you belong to.
The connector says “This connector has no tools available.”	The connector URL is `https://grainql.com/api/mcp`, without `www`. That address redirects, and Claude drops the sign-in token on the redirect.	Remove the connector and add it again with `https://www.grainql.com/api/mcp`.
Tools are missing from the list.	GrainQL filters tools by the granted scopes.	Connect again and approve the `mcp:investigate` scope.
”Server disconnected” during a Claude Code session.	The connection dropped. Claude Code reconnects with exponential backoff, up to 5 attempts.	If Claude Code stops, run `/mcp`, select grain, then Reconnect.

​1. Open the connector settings

​2. Add a custom connector

​3. Paste the GrainQL endpoint

​4. Authorize in the browser

​5. Turn it on in a chat

​Claude Code

​What the assistant can do

​Troubleshooting

1. Open the connector settings

2. Add a custom connector

3. Paste the GrainQL endpoint

4. Authorize in the browser

5. Turn it on in a chat

Claude Code

What the assistant can do

Troubleshooting