MCP Setup - ChatGrid API

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, 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:

.mcp.json

{
  "mcpServers": {
    "chatgrid": {
      "command": "npx",
      "args": ["-y", "chatgrid-mcp"],
      "env": {
        "CHATGRID_API_KEY": "cgk_live_your_key_here"
      }
    }
  }
}

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

Shared Claude Code config

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

.mcp.json

{
  "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:

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:

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:

claude mcp list
claude mcp get chatgrid

Inside Claude Code, run:

/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:

.cursor/mcp.json

{
  "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:

.cursor/mcp.json

{
  "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:

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:

~/.codeium/windsurf/mcp_config.json

Add this config:

mcp_config.json

{
  "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:

mcp_config.json

{
  "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:

mcp_config.json

{
  "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.

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

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

> Create a ChatGrid board for the payments project

Add a YouTube video

> 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

> 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

> 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

> 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

> 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

> 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

> 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

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.

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.

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.

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

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.

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.

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.

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.

Tips

One board per project

Keep boards focused. A “Payments” board, a “Frontend” board, an “Infrastructure” board. Don’t dump everything in one board.

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.

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.

​Prerequisites

​Step 1: Get a ChatGrid API key

​Step 2: Add ChatGrid to your IDE

​Claude Code

​Option A: Project .mcp.json

​Shared Claude Code config

​Option B: Claude Code CLI

​Verify Claude Code

​Cursor

​Option A: Project .cursor/mcp.json

​Option B: Cursor config without committing secrets

​Verify Cursor

​Windsurf

​Option A: Windsurf settings

​Option B: Windsurf config without committing secrets

​Verify Windsurf

​Step 3: Try it

​Create a board

​Add a YouTube video

​Add a website

​Upload a PDF

​Upload an image

​Add a text note

​Search your knowledge

​Ask questions

​All MCP tools

​Supported content types

​Troubleshooting

​Tips

Prerequisites

Step 1: Get a ChatGrid API key

Step 2: Add ChatGrid to your IDE

Claude Code

Option A: Project `.mcp.json`

Shared Claude Code config

Option B: Claude Code CLI

Verify Claude Code

Cursor

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

Option B: Cursor config without committing secrets

Verify Cursor

Windsurf

Option A: Windsurf settings

Option B: Windsurf config without committing secrets

Verify Windsurf

Step 3: Try it

Create a board

Add a YouTube video

Add a website

Upload a PDF

Upload an image

Add a text note

Search your knowledge

Ask questions

All MCP tools

Supported content types

Troubleshooting

Tips