> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatgrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Add ChatGrid to Claude Code, Cursor, or Windsurf, verify the MCP server, and know exactly what is searchable.

## Prerequisites

* Claude Code, Cursor, or Windsurf installed
* Node.js 18 or newer
* A ChatGrid API key with `read` and `write` scopes

## Step 1: Get a ChatGrid API key

Go to the [ChatGrid dashboard](https://www.chatgrid.ai/dashboard), open your profile, and create an API key from the **API Keys** section. The key starts with `cgk_live_` and is shown only once.

## Step 2: Add ChatGrid to your IDE

Claude Code, Cursor, and Windsurf all use an `mcpServers` JSON object, but they do **not** all use the same config file or the same environment-variable syntax.

## Claude Code

Use this when you run ChatGrid from Claude Code in a project.

### Option A: Project `.mcp.json`

Create or edit `.mcp.json` in your project root. This project-scoped file is the format Claude Code expects:

```json .mcp.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "cgk_live_your_key_here"
      }
    }
  }
}
```

<Warning>
  Add `.mcp.json` to `.gitignore` if it contains the raw API key. For a shared project config, use the environment variable version below.
</Warning>

### Shared Claude Code config

Claude Code expands environment variables in `.mcp.json`, so teams can commit the config without committing the key:

```json .mcp.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "${CHATGRID_API_KEY}"
      }
    }
  }
}
```

Then start Claude Code from a shell where the key is set:

```bash theme={null}
export CHATGRID_API_KEY="cgk_live_your_key_here"
claude
```

If `CHATGRID_API_KEY` is not set, Claude Code will fail to parse the config.

### Option B: Claude Code CLI

You can also let Claude Code write the config:

```bash theme={null}
claude mcp add --transport stdio --scope project \
  --env CHATGRID_API_KEY="$CHATGRID_API_KEY" \
  chatgrid -- npx -y chatgrid-mcp
```

### Verify Claude Code

Close and reopen Claude Code from the project directory. Because `.mcp.json` is project-scoped, Claude Code may ask you to approve the `chatgrid` server before it can run.

Verify the connection:

```bash theme={null}
claude mcp list
claude mcp get chatgrid
```

Inside Claude Code, run:

```text theme={null}
/mcp
```

The `/mcp` panel shows server status and tool count. It is a status/auth panel, not a config reload command.

## Cursor

Use this when you want ChatGrid tools in Cursor.

### Option A: Project `.cursor/mcp.json`

Create `.cursor/mcp.json` in your project:

```json .cursor/mcp.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "cgk_live_your_key_here"
      }
    }
  }
}
```

### Option B: Cursor config without committing secrets

Cursor uses `${env:VAR_NAME}` for environment-variable interpolation:

```json .cursor/mcp.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "${env:CHATGRID_API_KEY}"
      }
    }
  }
}
```

Use `~/.cursor/mcp.json` instead if you want ChatGrid available across all Cursor projects.

### Verify Cursor

Open Cursor MCP settings and confirm `chatgrid` is enabled. If you use Cursor CLI, run:

```bash theme={null}
cursor-agent mcp list
```

## Windsurf

Use this when you want ChatGrid tools inside Cascade.

### Option A: Windsurf settings

Open **Windsurf Settings** → **Cascade** → **MCP Servers** and add a custom server. If you prefer raw JSON, edit:

```text theme={null}
~/.codeium/windsurf/mcp_config.json
```

Add this config:

```json mcp_config.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "cgk_live_your_key_here"
      }
    }
  }
}
```

### Option B: Windsurf config without committing secrets

Windsurf uses `${env:VAR_NAME}` for environment-variable interpolation:

```json mcp_config.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "${env:CHATGRID_API_KEY}"
      }
    }
  }
}
```

You can also read the key from a local file:

```json mcp_config.json theme={null}
{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "${file:~/.secrets/chatgrid_api_key}"
      }
    }
  }
}
```

### Verify Windsurf

Open the **MCPs** menu in Cascade or **Windsurf Settings** → **Cascade** → **MCP Servers**. Confirm `chatgrid` is listed, then enable the tools you want Cascade to use.

<Note>
  Windsurf has a 100-tool limit across enabled MCP servers. ChatGrid exposes 8 tools.
</Note>

## Step 3: Try it

Talk to your IDE naturally. It can use ChatGrid tools when a prompt needs board context or board changes.

### Create a board

```text theme={null}
> Create a ChatGrid board for the payments project
```

### Add a YouTube video

```text theme={null}
> Add this YouTube video to the payments board: https://youtube.com/watch?v=abc123
```

The video appears on the canvas as a source node. To make transcript content searchable, add the transcript text as a text resource or send it to `/documents/vectorize`.

### Add a website

```text theme={null}
> Add this blog post to the board: https://vercel.com/blog/ai-sdk-4-2
```

The page appears on the canvas as a website source node. To make page content searchable, add extracted page text as a text resource or send it to `/documents/vectorize`.

### Upload a PDF

```text theme={null}
> Upload this PDF to the board: /Users/me/docs/architecture.pdf
```

The file is uploaded to storage and a PDF node appears on the canvas. Uploads are limited to 50 MB. To make file text searchable, extract the text and send it to `/documents/vectorize`.

### Upload an image

```text theme={null}
> Upload this diagram to the board: /Users/me/docs/system-diagram.png
```

The image is uploaded to storage and displayed on the canvas. Image contents are not searchable unless you add a text description or extracted OCR text.

### Add a text note

```text theme={null}
> Add these architecture notes to the board: "We use Stripe webhooks
  verified with the signing secret. Events go through Inngest for
  reliable processing. See src/server/stripe/webhooks.ts."
```

Notes appear as sticky notes on the canvas and are vectorized for search.

### Search your knowledge

```text theme={null}
> Search the payments board for webhook verification
```

Search returns vectorized notes and text resources. URL, YouTube, PDF, image, and document nodes are visible on the board but are not searchable until their extracted text is vectorized.

### Ask questions

```text theme={null}
> Based on our team's board, how should I implement retry logic
  for failed payment webhooks?
```

The MCP tool searches the board first. When matching board content exists, the answer is grounded in those sources; when nothing matches, the response will say that no board content matched.

## All MCP tools

| Tool              | What it does                                                                |
| ----------------- | --------------------------------------------------------------------------- |
| **list\_boards**  | See all your team's boards                                                  |
| **create\_board** | Start a new project board                                                   |
| **list\_nodes**   | See everything on a board                                                   |
| **add\_resource** | Add a YouTube source node, website source node, or searchable text resource |
| **add\_note**     | Add a searchable sticky note with text content                              |
| **upload\_file**  | Upload a PDF, image, or document file from disk and create a canvas node    |
| **search\_board** | Semantic search across vectorized board text                                |
| **ask\_board**    | Ask a question after searching vectorized board text                        |

## Supported content types

| Type              | How to add                        | What happens                  | Search behavior                                    |
| ----------------- | --------------------------------- | ----------------------------- | -------------------------------------------------- |
| **YouTube**       | Paste a YouTube URL               | Video source node             | Searchable after transcript text is vectorized     |
| **Website**       | Paste any URL                     | Website source node           | Searchable after extracted page text is vectorized |
| **PDF**           | Upload from disk                  | PDF viewer node               | Searchable after extracted text is vectorized      |
| **Image**         | Upload from disk                  | Image displayed on canvas     | Searchable after you add OCR or description text   |
| **Text resource** | Paste content with `add_resource` | Sticky note-style text node   | Searchable immediately                             |
| **Note**          | Paste content with `add_note`     | Sticky note with visible text | Searchable immediately                             |

Supported upload extensions include `pdf`, `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`, `doc`, `docx`, `txt`, `md`, and `csv`. Other extensions upload as generic document nodes.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude Code does not show chatgrid">
    Run `claude mcp list` from the project directory and confirm `chatgrid` appears. If you use `.mcp.json`, restart Claude Code and approve the project-scoped server when prompted.
  </Accordion>

  <Accordion title="Windsurf does not show chatgrid">
    Open **Windsurf Settings** → **Cascade** → **MCP Servers** and confirm the server exists in `~/.codeium/windsurf/mcp_config.json`. If it appears but tools are disabled, enable the ChatGrid tools from the MCPs menu in Cascade.
  </Accordion>

  <Accordion title="Cursor does not show chatgrid">
    Confirm the server exists in `.cursor/mcp.json` for the current project or `~/.cursor/mcp.json` globally. In Cursor CLI, run `cursor-agent mcp list` to confirm Cursor sees the server.
  </Accordion>

  <Accordion title="CHATGRID_API_KEY is missing">
    For Claude Code, `${CHATGRID_API_KEY}` requires the environment variable to be set before launching `claude`. Cursor and Windsurf use `${env:CHATGRID_API_KEY}`. If a GUI app cannot see that variable, paste the key directly; Windsurf can also use `${file:~/.secrets/chatgrid_api_key}`.
  </Accordion>

  <Accordion title="npx or Node fails">
    Install Node.js 18 or newer, then run `node --version` and `npx --version`. The server is launched with `npx -y chatgrid-mcp`.
  </Accordion>

  <Accordion title="Search returns no results">
    Search only covers vectorized text. Add notes, add text resources, or vectorize extracted transcript/page/PDF text before expecting results from source nodes or uploads.
  </Accordion>

  <Accordion title="Upload fails">
    Use an absolute file path that your IDE can read. Files must be under 50 MB. Permission errors and missing files are reported by the MCP tool.
  </Accordion>

  <Accordion title="API returns 401, 403, or 429">
    `401` means the key is missing, invalid, revoked, or expired. `403` means the key does not have the required scope. `429` means the key hit its rate limit.
  </Accordion>
</AccordionGroup>

## Tips

<AccordionGroup>
  <Accordion title="One board per project">
    Keep boards focused. A "Payments" board, a "Frontend" board, an "Infrastructure" board. Don't dump everything in one board.
  </Accordion>

  <Accordion title="Add content as you go">
    Found a useful Stack Overflow answer? Add it as a note or text resource. Read a useful blog post or watched a tutorial? Add the source node, then vectorize the extracted text you want AI to search.
  </Accordion>

  <Accordion title="Upload PDFs and images directly">
    The MCP server can read files from your local disk. Give it an absolute path such as "Upload /path/to/file.pdf to the board". No hosting step is required.
  </Accordion>

  <Accordion title="Share with your team">
    Prefer individual API keys for each developer, or a managed team key that can be rotated. The board itself is shared, so one developer's source nodes and vectorized notes help everyone with access.
  </Accordion>
</AccordionGroup>