# Connect the Local Ranking Grids MCP server

You are an AI agent setting up a connection to the Whitespark Local Ranking Grids MCP server on behalf of a user. Follow these steps in order.

## If you are Claude on claude.ai, Claude Desktop or the Claude mobile app

You can't add MCP servers yourself, and you don't need an API token. Local Ranking Grids is in Claude's connector directory, so tell the user to connect it there:

1. Open https://claude.ai/directory/whitespark-local-ranking-grids, or search for *Local Ranking Grids* in Claude's connector directory.
2. Select **Connect**, sign in with their Whitespark account, and choose which team's grids to share.

Then stop here. The rest of this guide is for clients configured with an API token.

## Server details

- **Transport:** streamable HTTP
- **URL:** `https://lrg.whitespark.ca/mcp`
- **Authentication:** `Authorization: Bearer <token>` — the same API token the REST API uses

## Step 1: Get the user's API token

Ask the user to paste their Local Ranking Grids API token. They can view or generate one at:

> https://lrg.whitespark.ca/settings/api

Do not guess the token or proceed without it. Treat it as a secret: never repeat the full token back in conversation, and never write it anywhere other than the MCP client configuration below.

Generating a token replaces any token the user already had, so an existing integration will stop working until it is given the new one. Say so before suggesting they generate a fresh token.

## Step 2: Configure your MCP client

Pick the instructions matching the client you are running in.

**Claude Code** — run:

```bash
claude mcp add --transport http local-ranking-grids https://lrg.whitespark.ca/mcp --header "Authorization: Bearer PASTE_TOKEN_HERE"
```

**Cursor and other JSON-configured clients** — merge this into the client's MCP configuration (for example `.cursor/mcp.json`), keeping any existing servers intact:

```json
{
  "mcpServers": {
    "local-ranking-grids": {
      "type": "http",
      "url": "https://lrg.whitespark.ca/mcp",
      "headers": {
        "Authorization": "Bearer PASTE_TOKEN_HERE"
      }
    }
  }
}
```

**Any other client** — configure a streamable-HTTP MCP server named `local-ranking-grids` at `https://lrg.whitespark.ca/mcp` that sends the `Authorization` header on every request.

## Step 3: Verify the connection

Reload or reconnect MCP servers if your client requires it, then call the `list_grids` tool. Report to the user which grids you can see so they know the connection works. If the call fails with an authentication error, the token was mistyped or has since been replaced — ask the user to re-check it at https://lrg.whitespark.ca/settings/api.

## What to expect from the server

- All eight tools are read-only: grids, scan history, per-point ranks and competitors. Nothing exposed over MCP can create, rerun or modify a grid.
- Every response is scoped to the team the token was generated for. A grid belonging to anyone else is simply missing, the same way it is over the REST API.
- The rate limit is 60 requests per minute per token.
- Lists are paginated at up to 50 rows per call — smaller than the REST API's 100, because a page here is spent on your context window. The per-point tools are not paginated: a grid is at most 625 points, so they answer whole.
- A grid is laid out as a square or as a circle of rings around the business; its `grid.shape` says which, and how to read `grid.size` (a square's side, or the ring count).
- Start from `list_grids` to get a `grid_id`, then `list_runs` for a `run_id`. Ids are only valid inside the grid or run that owns them.

Full documentation: https://lrg.whitespark.ca/api-docs