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

# Connect Cursor

> Add Grain as a remote MCP server in Cursor so the in‑editor agent can query your analytics.

Cursor has first‑class support for remote MCP servers. Once Grain is wired up, the Cursor agent (and Composer) can look up events, run queries, and investigate funnels without leaving the editor — useful when you're shipping a fix for a conversion drop and want the data right next to the code.

## Setup

Cursor reads MCP servers from a JSON file. You pick where to put it:

* **Global** — `~/.cursor/mcp.json` in your home directory. Available in every project you open.
* **Project** — `.cursor/mcp.json` in the repo root. Commit it if you want every teammate to inherit the same MCP servers.

<Steps>
  <Step title="Create the config file">
    <CodeGroup>
      ```bash Global theme={null}
      mkdir -p ~/.cursor
      touch ~/.cursor/mcp.json
      ```

      ```bash Project theme={null}
      mkdir -p .cursor
      touch .cursor/mcp.json
      ```
    </CodeGroup>
  </Step>

  <Step title="Add the Grain server">
    Paste this into `mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "grain": {
          "url": "https://grainql.com/api/mcp"
        }
      }
    }
    ```

    That's the whole config. Grain handles client registration and PKCE automatically — you do **not** need to supply a `client_id`, a secret, or an `Authorization` header.
  </Step>

  <Step title="Reload and authorize">
    Open **Cursor Settings → MCP** (or **Settings → Tools & MCP** depending on version). You should see **grain** listed with an **Authorize** button. Click it.

    Cursor opens Grain's consent screen in your browser. Pick the workspace, review the scopes, and click **Authorize**.

    <Check>
      Back in Cursor, the grain server switches to a green “Connected” state and the tool count appears (11 tools if you granted all scopes).
    </Check>
  </Step>

  <Step title="Ask the agent something">
    Open Cursor's chat or Composer and try:

    > @grain What's my top traffic source for the landing page I'm editing?

    Cursor will call `grain.query`, and — because it knows the file you're in — can even filter by the right `page` property automatically.
  </Step>
</Steps>

<Tip>
  Prefix your prompt with `@grain` to hint that you want the Grain tools used. Cursor normally picks the right tool on its own, but the hint reduces round‑trips on ambiguous questions.
</Tip>

## Project rule for consistent prompts

Adding a short project rule helps Cursor route analytics questions to Grain without you having to remember the tool names. Create `.cursor/rules.md`:

```markdown theme={null}
# Grain analytics rule

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

1. Prefer Grain 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 Grain dashboard URL returned in the tool's `citations` field
   so the user can verify.
```

Rules are optional — Cursor works fine without one — but they pay for themselves the second time someone on your team asks "why is conversion down?"

## Good prompts to try

<AccordionGroup>
  <Accordion title="Before touching a checkout flow">
    > Before I refactor this checkout page, show me the Track for `checkout_started → checkout_completed` over the last 30 days and flag the biggest drop‑off step.

    Uses `grain.track.analyze`.
  </Accordion>

  <Accordion title="Tag audit after a deploy">
    > Did my last deploy break any events? Compare event volumes this week to last week and list anything that dropped more than 50%.

    Uses `grain.query.compare`.
  </Accordion>

  <Accordion title="Debugging a single user report">
    > 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.

    Uses `grain.query` with a `browser` group‑by.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="“Server failed to start” in Cursor's MCP panel">
    Almost always a JSON typo. Validate `mcp.json` with a linter — a trailing comma is the usual suspect. Then click **Reload** in the MCP panel.
  </Accordion>

  <Accordion title="No Authorize button appears">
    Cursor caches the server list. Toggle the server off and on, or fully restart Cursor. If it still misses, check that the `url` value is exactly `https://grainql.com/api/mcp` — no trailing slash, no `/mcp/` path variations.
  </Accordion>

  <Accordion title="Tools return “insufficient scope”">
    You probably approved `mcp:read` only. Revoke Grain from [Settings → Connectors](https://grainql.com/dashboard/settings?tab=connectors\&category=mcp) and reconnect; the consent screen will re‑prompt for the full scope set.
  </Accordion>

  <Accordion title="Want to share the config with your team?">
    Put `mcp.json` in `.cursor/` (not `~/.cursor/`) and commit it. Each teammate still goes through their own OAuth flow — tokens are never written to the config file.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tool reference" icon="book" href="/ai-tools/mcp/tools">
    Every tool Grain exposes and what it returns.
  </Card>

  <Card title="Security & scopes" icon="shield-check" href="/ai-tools/mcp/security">
    How to audit and revoke connections.
  </Card>
</CardGroup>

## References

* [Cursor Docs — Model Context Protocol](https://cursor.com/docs/context/mcp)
* [Model Context Protocol — connect to remote servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers)