Skip to content
← All install options

Install Better Design MCP in Claude Code

Follow the setup below to give Claude Code Better Design's systems and interface guidance.

Setup

Config
bash
claude mcp add --scope user better-design --transport http https://better-design.com/api/mcp --header "Authorization: Bearer <YOUR_API_KEY>" --header "X-Better-Design-Client: claude-code"

Choose where Claude Code keeps the server

The command above uses --scope user, so the server loads in every project on your machine. Claude Code stores user and local servers in ~/.claude.json. A project server lives in .mcp.json at the project root, which you can commit for your team.

When the same server name is defined in more than one scope, Claude Code uses the local definition first, then project, then user.

Check that Claude Code connected

Run these commands after the install. The list shows a status next to each server, such as Connected, Needs authentication or Failed to connect. Inside a session, type /mcp to see the same status and the tool count.

terminal
claude mcp get better-design
claude mcp list

What the agent can use after setup

Better Design gives the agent design context and review tools. The agent still writes the code, and your repository stays the source of truth.

  • Find a catalog design system or create one for your brand before frontend work starts.
  • Load UI principles for visual choices and UX principles for flows and behavior.
  • Get component and icon guidance that matches the chosen system.
  • Run review rules, comprehension checks and spacing checks on rendered pages.

Fix a Claude Code MCP connection

When a server fails, claude mcp get better-design shows an Issue line with the HTTP status and the error the server returned. Start from that line.

  • Claude Code warns about leading or trailing whitespace in the Authorization header: the pasted key carries a newline. Edit the config and remove it, because Claude Code does not trim it.
  • The server returns 401: replace the key in the Authorization header with a current one. Claude Code does not retry an authentication error on its own.
  • Claude Code warns about a conflict: the name better-design exists in two scopes. Remove the copy you do not want with claude mcp remove better-design --scope <scope>.
  • A project server shows Pending approval: start claude in that project and approve the server.
  • A tool result is cut off: Claude Code limits MCP output to 25,000 tokens by default. Raise it with the MAX_MCP_OUTPUT_TOKENS environment variable.

Questions

Does the server load in every project?

Yes, with --scope user. Without a scope flag, Claude Code adds the server to the current project only, because local scope is the default.

How do I share the server with my team?

Add it with --scope project. Claude Code writes it to .mcp.json at the project root, and each teammate approves it the first time they start Claude Code there. Keep the API key out of the committed file.

How do I remove Better Design from Claude Code?

Run claude mcp remove better-design. Add --scope with the scope you installed it in when the name exists in more than one place.

Official Claude Code resources

Related