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

# MCP Server

> Connect the Bulkgrid MCP server to VS Code, Cursor, Claude Code, Codex, and other MCP clients.

Bulkgrid exposes a remote MCP server at:

```bash theme={null}
https://your-bulkgrid-base-url/api/v1/mcp
```

Use a Bulkgrid API key with the `mcp:use` scope. Add `search:query` when the MCP client should search your indexed content.

## Recommended setup

Set these values before configuring your MCP client:

```bash theme={null}
export BULKGRID_API_KEY='bg_live_your_api_key'
export BULKGRID_MCP_URL='https://your-bulkgrid-base-url/api/v1/mcp'
```

Bulkgrid accepts the API key through either `Authorization: Bearer ...` or `x-api-key`. Prefer the bearer header for MCP clients because several agent CLIs have first-class support for bearer tokens.

## One-command setup

Use the Bulkgrid CLI to configure the Bulkgrid MCP server for every supported client it can find:

```bash theme={null}
npx -y @bulkgrid/cli init --all
```

The CLI prompts for authentication. You can open the Bulkgrid dashboard to create an API key, enter an API key manually, or skip authentication and use client-side prompts or environment variables.

You can also configure a single MCP client:

```bash theme={null}
npx -y @bulkgrid/cli init --cursor
npx -y @bulkgrid/cli init --vscode
npx -y @bulkgrid/cli init --claude
npx -y @bulkgrid/cli init --codex
```

Pass the MCP URL directly if you do not want to set `BULKGRID_MCP_URL` first:

```bash theme={null}
npx -y @bulkgrid/cli init --all \
  --mcp-url 'https://your-bulkgrid-base-url/api/v1/mcp'
```

By default, the CLI does not write raw API keys into generated Cursor or VS Code project files. It uses prompts or environment-variable references where the client supports them.

## Claude Code

Run this from the project where you use Claude Code:

```bash theme={null}
claude mcp add --transport http bulkgrid "$BULKGRID_MCP_URL" \
  --header "Authorization: Bearer $BULKGRID_API_KEY"
```

Verify the server:

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

To make Bulkgrid available across all Claude Code projects on your machine, add `--scope user`:

```bash theme={null}
claude mcp add --transport http --scope user bulkgrid "$BULKGRID_MCP_URL" \
  --header "Authorization: Bearer $BULKGRID_API_KEY"
```

## Claude Desktop

Add Bulkgrid to your Claude Desktop MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "bulkgrid": {
      "type": "http",
      "url": "https://your-bulkgrid-base-url/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer bg_live_your_api_key"
      }
    }
  }
}
```

Restart Claude Desktop after changing the file.

## Codex

Codex can store a remote MCP server with a bearer token environment variable:

```bash theme={null}
codex mcp add bulkgrid \
  --url "$BULKGRID_MCP_URL" \
  --bearer-token-env-var BULKGRID_API_KEY
```

Verify the server:

```bash theme={null}
codex mcp list
```

You can also configure Codex directly in `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.bulkgrid]
url = "https://your-bulkgrid-base-url/api/v1/mcp"
bearer_token_env_var = "BULKGRID_API_KEY"
```

## Cursor

Create `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for a global setup:

```json theme={null}
{
  "mcpServers": {
    "bulkgrid": {
      "url": "https://your-bulkgrid-base-url/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BULKGRID_API_KEY}"
      }
    }
  }
}
```

Restart Cursor after changing the file. In Cursor CLI, you can check the configured server with:

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

## VS Code

VS Code stores MCP configuration in `.vscode/mcp.json` for a workspace or in the user profile.

You can add a server from the command line, then edit the saved configuration if you want to use VS Code input prompts for the key:

```bash theme={null}
code --add-mcp '{"name":"bulkgrid","type":"http","url":"https://your-bulkgrid-base-url/api/v1/mcp","headers":{"Authorization":"Bearer bg_live_your_api_key"}}'
```

For a shareable workspace configuration that prompts each developer for their own key, create `.vscode/mcp.json`:

```json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "bulkgrid-api-key",
      "description": "Bulkgrid API Key",
      "password": true
    }
  ],
  "servers": {
    "bulkgrid": {
      "type": "http",
      "url": "https://your-bulkgrid-base-url/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bulkgrid-api-key}"
      }
    }
  }
}
```

Open Copilot Chat in Agent mode and enable the Bulkgrid server in the tools picker.

## Useful instruction

Add this to your project or assistant instructions when you want tools to use Bulkgrid consistently:

```text theme={null}
Use the Bulkgrid MCP server when you need to search indexed source content, inspect accessible collections, or ground answers in curated Bulkgrid data.
```

## Troubleshooting

* `401 Unauthorized`: the API key is missing, malformed, expired, or sent with the wrong header.
* `403 Forbidden`: the API key is valid but does not include `mcp:use`, or it lacks the tool-specific scope such as `search:query`.
* No tools appear: restart the agent client and verify the MCP server list command for that client.
* Empty or unexpected search results: check the key's collection restrictions in Bulkgrid.

## Related guides

* [API Key Scopes](/guides/api-key-scopes)
* [Collections and Access](/guides/collections-and-access)
* [RAG and Agent Workflows](/integrations/rag-and-agent-workflows)