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

> Add Grain as a custom connector in Claude.ai, Claude Desktop, or Claude Code.

Grain's MCP server works with every Claude surface Anthropic ships: the web app, the desktop app, and the Claude Code CLI. Pick the one you use most — the OAuth flow is identical under the hood.

<Info>
  **You'll need:** an active Grain workspace and whatever plan your Claude client requires. Custom connectors are available on Claude Free, Pro, Max, Team, and Enterprise — Free accounts are limited to a single custom connector.
</Info>

## Claude.ai (web) and Claude Desktop

The web and desktop apps share the same connector UI.

<Steps>
  <Step title="Open the connector settings">
    In Claude, click your profile, then **Settings → Connectors**. On Team and Enterprise plans, an owner adds the connector org‑wide under **Organization settings → Connectors**, and members connect individually afterwards.
  </Step>

  <Step title="Add a custom connector">
    Click **+ Add connector**, then **Add custom connector** (on Team/Enterprise: **Add → Custom → Web**).
  </Step>

  <Step title="Paste the Grain endpoint">
    ```
    https://grainql.com/api/mcp
    ```

    Leave **Advanced settings** alone — Grain handles client registration automatically via RFC 7591. You don't need to provide a client ID or secret.
  </Step>

  <Step title="Authorize in the browser">
    Claude opens Grain's consent screen. Pick the workspace you want Claude to see, review the scopes, and click **Authorize**. You'll see a 7‑day preview of the workspace so you know exactly what's being shared.

    <Check>
      You land back in Claude with the connector enabled.
    </Check>
  </Step>

  <Step title="Turn it on in a chat">
    In any conversation, click the **+** button, open **Connectors**, and toggle **Grain** on. Ask something like:

    > What were my top 5 traffic sources last week?

    Claude will call `grain.query`, narrate the result, and cite the rows it used.
  </Step>
</Steps>

<Tip>
  The first tool call of a fresh session is the slowest — Claude is discovering the tool surface. Follow‑ups are instant.
</Tip>

## Claude Code

Claude Code ships a first‑class CLI for MCP servers. One command gets you connected.

<Steps>
  <Step title="Install Claude Code">
    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```

    If you already have it, make sure you're on a recent version — remote HTTP transport is relatively new.
  </Step>

  <Step title="Add the Grain server">
    ```bash theme={null}
    claude mcp add --transport http grain https://grainql.com/api/mcp
    ```

    <Note>
      Add `--scope user` to make Grain available across every project, or `--scope project` to commit the connection to `.mcp.json` for your whole team.
    </Note>
  </Step>

  <Step title="Authenticate">
    Inside Claude Code, run:

    ```
    /mcp
    ```

    Select **grain**, then **Authenticate**. The CLI pops Grain's consent screen in your browser, you approve the workspace, and control returns to the terminal.
  </Step>

  <Step title="Try it">
    Ask Claude Code a question that needs Grain data:

    > Which pages had the biggest drop in conversions this week vs last?

    It will pick the right tool (`grain.query.compare` or `grain.segment.compare`), run it, and summarize.
  </Step>
</Steps>

### Useful CLI commands

```bash theme={null}
# Confirm the server is listed
claude mcp list

# Inspect just Grain
claude mcp get grain

# Remove it
claude mcp remove grain
```

## What Claude can actually do

With all three scopes granted, Claude has eleven tools at its disposal. A few high‑leverage prompts to try:

<AccordionGroup>
  <Accordion title="Schema discovery">
    > What events do I track, and which dimensions can I break them down by?

    Uses `grain.events.list` + `grain.dimensions.discover`. Great first prompt on a brand new workspace.
  </Accordion>

  <Accordion title="A week in review">
    > Give me a digest of what changed this week — metrics, sources, and anything that looks surprising.

    Uses `grain.query.digest`. The result includes Grain's surprise‑detection hints (concentration, volatility, rank changes) so the narration calls out anomalies, not just numbers.
  </Accordion>

  <Accordion title="Investigate a drop">
    > Checkout conversions fell Tuesday. Compare the users who dropped against those who converted and tell me what's different.

    Uses `grain.segment.compare` + `grain.sessions.cluster` under the hood.
  </Accordion>

  <Accordion title="Tracking audit">
    > Is my analytics tag firing correctly?

    Uses `grain.integration.status`. Handy before an investigation so you know the data itself is trustworthy.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="“Connect” button does nothing / OAuth window fails to open">
    Claude Desktop needs a default browser. On macOS, check **System Settings → Desktop & Dock → Default web browser**. On the web, make sure popups are allowed for `claude.ai`.
  </Accordion>

  <Accordion title="“Invalid tenant” or 403 after authorizing">
    You probably picked a workspace you don't have access to. Revoke the connection from [Grain's settings](https://grainql.com/dashboard/settings?tab=connectors\&category=mcp) and reconnect — the consent screen will only show workspaces you actually belong to.
  </Accordion>

  <Accordion title="Tools missing from the list">
    Grain filters tools by granted scope. If `grain.segment.compare` isn't showing up, reconnect and approve the `mcp:investigate` scope.
  </Accordion>

  <Accordion title="“Server disconnected” mid‑session in Claude Code">
    Claude Code auto‑reconnects with exponential backoff (up to 5 attempts). If it gives up, run `/mcp` → select grain → **Reconnect**.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Tool reference" icon="book" href="/ai-tools/mcp/tools">
    Every tool, its inputs, and what scope it requires.
  </Card>

  <Card title="Security & scopes" icon="shield-check" href="/ai-tools/mcp/security">
    How tokens, scopes, and revocation work.
  </Card>
</CardGroup>

## References

* [Claude Code — Connect to tools via MCP](https://code.claude.com/docs/en/mcp)
* [Claude Help Center — Custom connectors via remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
* [Model Context Protocol — connect to remote servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers)