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 installnpm run buildnpm 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.