brandpilot-mcp

MCP server for BrandPilot: 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 (BRANDPILOT_API_KEY): 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 bp_live_. Replace bp_live_your_key_here 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 BRANDPILOT_API_KEY in your shell and use env_vars = ["BRANDPILOT_API_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 BRANDPILOT_API_KEY in its environment. The same shape works in Claude Desktop's claude_desktop_config.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, list_brands, get_design_context, get_repo_rules_pack, get_claude_design_kit, finish_external_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:

On the hosted server, list_systems, get_agent_prompt and get_design_handoff are deprecated aliases of list_brands, get_repo_rules_pack and get_design_context.

Prompt pack v2

get_design_prompt_pack returns the v1 pack when called with only designId. The v2 pack runs in two passes in one Claude Design project:

1. pass: "explore" - every surface asks for 2-3 clearly different directions with a short critique. Add with3d: true for one 3D Objects prompt.
2. pass: "lock", direction: "<the direction you picked>" - every surface is built in the chosen direction (max 2000 characters, required for this pass).

format: "json" returns the structured pack instead of markdown, and format: "copy-map" returns the copy map the v2 pack lists as a project file. direction and with3d without a pass are rejected rather than silently returning v1.

Legacy handoff keys

Legacy per-design handoff keys are deprecated and stop working on 2027-01-31. Move to a workspace API key: one key covers every design in the workspace.

Until then, the legacy design-scoped tools (get_design_handoff, get_design_prompt_pack, import_design_artifacts, finish_external_design) accept a Bearer key scoped to one design, minted on the design page (/designs/<id>, section "Continue this design", "Copy API key"). Pass it as DESIGNFLOW_HANDOFF_KEY in the server's environment, or as a per-call handoffKey argument, which overrides the environment variable for that one call. When DESIGNFLOW_HANDOFF_KEY is set the server prints one deprecation line to stderr at startup. When BRANDPILOT_API_KEY is also set, the API key wins and the handoff key is ignored.

Environment variables

Local development

npm install
npm run build
npm test

npm link then an MCP config pointing at the linked bin is the fastest way to verify against a live server: in API-key mode confirm whoami names your workspace; without a key confirm list_systems returns the curated pool and nothing private.

See CHANGELOG.md for release notes.