Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bulkgrid.com/llms.txt

Use this file to discover all available pages before exploring further.

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