Cursor - GrainQL

Cursor supports remote MCP servers. After you add GrainQL, the Cursor agent and Composer can list events, run queries, and analyze funnels inside the editor. This puts the data next to the code when you fix a conversion drop. Cursor reads MCP servers from a JSON file. There are two locations:

Location	Path	Scope
Global	`~/.cursor/mcp.json`	Every project you open.
Project	`.cursor/mcp.json` in the repository root	This repository. Commit the file so that every teammate gets the same servers.

1. Create the configuration file

mkdir -p ~/.cursor
touch ~/.cursor/mcp.json

mkdir -p .cursor
touch .cursor/mcp.json

2. Add the GrainQL server

Paste this into mcp.json:

{
  "mcpServers": {
    "grain": {
      "url": "https://www.grainql.com/api/mcp"
    }
  }
}

This is the whole configuration. GrainQL does client registration and PKCE itself. You do not add a client_id, a secret, or an Authorization header.

3. Reload and authorize

Open Cursor Settings → MCP (or Settings → Tools & MCP, depending on the version). The list shows grain with an Authorize button. Click it. Cursor opens the GrainQL consent screen in your browser. Choose All workspaces in my account, or Select workspaces and tick the ones that Cursor will see. Read the scopes, and click Allow access. A workspace on the consent screen is a tenant. Back in Cursor, the grain server shows a green “Connected” state and a tool count. The count is 12 tools when you grant all scopes.

4. Ask the agent a question

Open the Cursor chat or Composer and ask, for example, “@grain What is my top traffic source for the landing page I am editing?”. Cursor calls grain_query. Because Cursor knows the file you are in, it can filter by the correct page property. The @grain prefix tells Cursor that you want the GrainQL tools. Cursor picks the tool on its own in most cases. The prefix reduces round trips on an ambiguous question. The Cursor documentation on MCP is at cursor.com/docs/context/mcp.

Project rule

A short project rule routes analytics questions to GrainQL without the tool names in every prompt. The rule is optional. Create .cursor/rules.md:

# GrainQL rule

When the user asks about traffic, conversions, events, funnels, visitor
behavior, or anything analytics-related:

1. Prefer GrainQL MCP tools over web search or assumptions.
2. Call `grain_events_list` first on unfamiliar workspaces to learn what
   events exist.
3. For "why did X change" questions, use `grain_query_compare` (period over
   period) before jumping to investigation tools.
4. For drop-offs in a Track (start -> goal funnel), call
   `grain_track_analyze`, then `grain_sessions_cluster` on the biggest
   drop to find representative sessions.
5. Cite the GrainQL dashboard URL returned in the tool's `citations` field
   so the user can verify.

What the assistant can do

Prompt	Tool
”Before I refactor this checkout page, show me the Track for `checkout_started` to `checkout_completed` over the last 30 days and flag the biggest drop-off step.”	`grain_track_analyze`
”Did my last deploy break any events? Compare event volumes this week to last week and list anything that dropped more than 50%.”	`grain_query_compare`
”A user says signup is broken on Safari. Count `signup_failed` events in the last 24h, grouped by browser, and tell me if Safari is an outlier.”	`grain_query` with a `browser` group-by

Read Tools for every tool.

Troubleshooting

Symptom	Cause	What to do
”Server failed to start” in the MCP panel.	A JSON syntax error in `mcp.json`. A trailing comma is the usual cause.	Run a JSON linter on `mcp.json`. Then click Reload in the MCP panel.
No Authorize button appears.	Cursor caches the server list.	Switch the server off and on, or restart Cursor. If the button is still missing, make sure that the `url` value is exactly `https://www.grainql.com/api/mcp`, with no trailing slash and no other path.
Tools return “insufficient scope”.	You approved `mcp:read` only.	Revoke GrainQL at Settings, MCP clients and connect again. The consent screen asks for the full scope set.
A teammate has no access after you commit `mcp.json`.	Tokens are never written to the configuration file.	Each teammate runs the OAuth flow on their own machine. Put `mcp.json` in `.cursor/`, not in `~/.cursor/`.

​1. Create the configuration file

​2. Add the GrainQL server

​3. Reload and authorize

​4. Ask the agent a question

​Project rule

​What the assistant can do

​Troubleshooting