dev.brandpilot/brandpilot-mcp

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 design system 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 public design-system tools, served over the BrandPilot REST API v2 with no account and no key.

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 (brands, design context, repo rules pack, design system kit, importing finished work back for review, and more); the current list is at https://brandpilot.dev/api/v2/mcp/tools and on brandpilot.dev/docs. A good first call is whoami.

Without a key the server serves these public tools, all over the BrandPilot REST API v2:

Upgrading from 0.x

1.0.0 is a major release because tools and a variable were removed. BrandPilot API v1 and the per-design handoff keys stop answering on 2026-12-15 (HTTP 410), so every 0.x install loses its keyless calls that day; upgrade before then.

• The public tools now call API v2 (/api/v2/..., and /api/v2/systems/{name}/export for tokens) instead of API v1 and /api/systems/export/{name}, and take the v2 names the hosted server uses: list_systems is now list_public_systems, get_system_adoption is get_system_manifest, get_system_tokens is export_system_tokens and get_agent_prompt is get_adoption_brief. Arguments are unchanged; export_system_tokens also accepts tailwind-v4 and dtcg.
• get_adoption_brief returns the new v2 brief: a design round on a Design canvas (Claude Code) or local HTML drafts (other agents), instead of the Claude Design steps.
• get_design_handoff, get_design_prompt_pack, import_design_artifacts and finish_external_design are removed from the keyless server, and DESIGNFLOW_HANDOFF_KEY is no longer read (a leftover value only prints one line asking you to remove it). Their v2 successors (get_design_context, get_design_brief, import_design_work, finish_design_import) are served by the hosted MCP: create a workspace API key in BrandPilot (Settings, API keys) and set BRANDPILOT_API_KEY, see Connect with an API key.
• The Claude Design prompt pack is gone with it: claude.ai/design closes on 2026-12-14. The hosted tools return a design's context and repo rules pack for building in your own repo instead.
• brandpilot-mcp/catalog now exports the four public tools only, with their v2 endpoints.

Environment variables

Local development

npm install
npm run build
npm test

The e2e tests drive the built server against a fake origin that answers API v2 and returns 410 on every v1 path. To run them against a local BrandPilot instead, set BRANDPILOT_E2E_ORIGIN=http://localhost:3005 (any origin that serves API v2) before 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_public_systems returns the curated pool and nothing private.

See CHANGELOG.md for release notes.