MCP Server for Coding Agents

Coding agents hardcode values because they never read your token file. buoy mcp gives Claude Code, Cursor, Codex and Windsurf four tools that answer "what tokens does this repo have?" and "did I just drift?" while the agent is writing, so the fix happens before the PR.

Setup

Claude Code plugin (MCP server, post-edit hook and a design-tokens skill in one install):

/plugin marketplace add ahoybuoy/buoy
/plugin install buoy@buoy

Any MCP client, or Claude Code without the plugin system:

npx @buoy-design/cli mcp install claude    # or cursor, codex, windsurf, all

For Claude Code this writes two files into the repo:

  • .mcp.json — registers the buoy MCP server (runs buoy mcp serve over stdio)
  • .claude/settings.json — a PostToolUse hook that checks every style file Claude edits

Other clients get their own mcp.json (.cursor/, .codex/, .windsurf/). Existing servers and hooks in those files are kept. Commit the files so everyone on the team gets the same agent setup.

Tools

ToolWhat the agent gets
context_for_fileJust the design context for the file the agent is about to edit: tokens it and its neighbours already use, the spacing, type and radius steps for the values it contains, components to reuse, and drift already in it. About 500 tokens of context where the full token list of a large system is about 8,000. Meant to be called before each edit.
list_design_tokensThe repo's tokens (CSS custom properties, Tailwind theme, tokens.json, SCSS). Without arguments, a short summary: counts plus a few per category. With a category or name, the full list.
find_token_for_valueThe token whose value equals a literal the agent is about to write: #1a73e8 → --color-primary. Handles hex shorthand, case and units.
check_ui_against_design_systemLine-level check of the files just edited: each off-system value with the token to use, plus an exact line edit when the swap is unambiguous. Without files, the full repository analysis.
design_system_contextA Markdown overview of the system: token categories, components, and the anti-patterns Buoy flags. One call at the start of a UI task.

The hook

After Claude writes or edits a .tsx, .jsx, .vue, .svelte, .css, .scss or .html file, buoy mcp hook checks that file and, if it drifted, returns feedback Claude acts on immediately: 

Buoy: 2 design drift issues in src/components/Hero.css
- src/components/Hero.css:2 Hardcoded color #1a2744 has a token: --color-navy -> use var(--color-navy)
- src/components/Hero.css:3 Hardcoded spacing 8px (no matching token)
Replace the literal values with the tokens above, then continue.

Files that are already tokenised produce no output. A hook failure never blocks the agent; it exits 0 with a note.

Without an install step

Buoy is listed in the official MCP Registry as io.github.ahoybuoy/buoy. Any MCP client can also register the server by hand:

{
  "mcpServers": {
    "buoy": { "command": "npx", "args": ["-y", "@buoy-design/cli", "mcp", "serve"] }
  }
}

And any agent runner can call the hook directly: buoy mcp hook --file src/Button.tsx (exit code 2 means drift, with details on stderr).

Pairs with the GitHub App

The MCP server catches drift while the agent writes; the GitHub App catches what slipped through on the PR, from agents and people alike, and a DESIGN.md gives both the same rules. Repos with no tokens yet can run buoy dock tokens to extract a set from the values already in use.

Install the GitHub App. It is free, and installing it is all it takes: the first pull request is reviewed with no Buoy account or sign-up. Sign in to the dashboard later if you want history and trends; your reviews come with you.

Related