Brandpilot MCP server

brandpilot-mcp

MCP server for BrandPilot (DesignFlow): bring a brand into your coding agent - list your brands, read a design's context and continuation contract, install its repo rules pack and tokens, and fetch its Claude Design kit - natively from Claude Code, Codex, Cursor, Claude Desktop or any other MCP client.

The package runs in one of two modes:

• With a workspace API key (BRANDPILOTAPIKEY): a thin stdio proxy onto the hosted BrandPilot MCP at https://brandpilot.dev/api/mcp. Every tools/list, tools/call, prompts/list and prompts/get is forwarded and the answer relayed, so the tool list is always the one BrandPilot serves today - new tools arrive without a package update.
• Without one: the legacy 0.2.x server - the public design-system tools, plus the design-scoped tools behind a per-design handoff key (deprecated, see Legacy handoff keys).

It never touches a database; any machine with network access to brandpilot.dev can run it. Requires Node.js 20 or newer.

Connect with an API key

Create a workspace API key in BrandPilot under Settings, API keys. It starts with bplive. Replace bpliveyourkeyhere below with it, and keep it out of committed files.

Claude Code

claude mcp add brandpilot --scope user -e BRANDPILOT_API_KEY=bp_live_your_key_here -- npx -y brandpilot-mcp

Then run /mcp in Claude Code to confirm brandpilot is connected, and ask "Ask BrandPilot who I am and list my brands".

Codex

codex mcp add brandpilot --env BRANDPILOT_API_KEY=bp_live_your_key_here -- npx -y brandpilot-mcp

or in ~/.codex/config.toml:

[mcp_servers.brandpilot]
command = "npx"
args = ["-y", "brandpilot-mcp"]

[mcp_servers.brandpilot.env]
BRANDPILOT_API_KEY = "bp_live_your_key_here"

To keep the key out of the file, export BRANDPILOTAPIKEY in your shell and use envvars = ["BRANDPILOTAPI_KEY"] in place of the env table.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "brandpilot": {
      "command": "npx",
      "args": ["-y", "brandpilot-mcp"],
      "env": {
        "BRANDPILOT_API_KEY": "bp_live_your_key_here"
      }
    }
  }
}

Any other MCP client

Run npx -y brandpilot-mcp as a stdio server with BRANDPILOTAPIKEY in its environment. The same shape works in Claude Desktop's claudedesktopconfig.json.

What the errors mean

The key is sent only in the Authorization header and is never printed, including in error messages and on stderr.

Tools

In API-key mode the tools and prompts come from the hosted server (whoami, listbrands, getdesigncontext, getreporulespack, getclaudedesignkit, finishexternal_design and more, plus the deprecated aliases below); the current list is at https://brandpilot.dev/api/v1/mcp/tools and on brandpilot.dev/docs. A good first call is whoami.

The legacy mode serves these eight tools:

Shortened. The full README is on GitHub.