MCP Server

Bulkgrid exposes a remote MCP server at:

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:

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:

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:

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:

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:

claude mcp add --transport http bulkgrid "$BULKGRID_MCP_URL" \
  --header "Authorization: Bearer $BULKGRID_API_KEY"

Verify the server:

claude mcp list

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

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:

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

codex mcp add bulkgrid \
  --url "$BULKGRID_MCP_URL" \
  --bearer-token-env-var BULKGRID_API_KEY

Verify the server:

codex mcp list

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

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

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

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:

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:

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

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.

Introduction

Getting Started

Core Workflows

Platform Operations

Integration Patterns

Production

Recommended setup

One-command setup

Claude Code

Claude Desktop

Codex

Cursor

VS Code

Useful instruction

Troubleshooting

​Recommended setup

​One-command setup

​Claude Code

​Claude Desktop

​Codex

​Cursor

​VS Code

​Useful instruction

​Troubleshooting

​Related guides

Recommended setup

One-command setup

Claude Code

Claude Desktop

Codex

Cursor

VS Code

Useful instruction

Troubleshooting

Related guides