MCP Server

The Humic MCP server gives AI coding agents direct access to your design system. Your agent can read tokens, create color scales, update primitives, and validate code against your design system — all without leaving the editor. The server uses the Model Context Protocol (MCP) with stdio transport, which means it works with any MCP-compatible client.

Prerequisites

Before setting up the MCP server, make sure you have:

A Humic account with at least one design system
Node.js 18 or later

Step 1: Authenticate

The MCP server needs credentials to access your design system. Run the login command to authenticate via your browser:

npx @humicdev/cli login

This opens humic.dev in your browser. After signing in, credentials are saved to ~/.config/humic/credentials and the MCP server picks them up automatically.

Alternatively, you can set the HUMIC_API_KEY environment variable with an API key from your Humic dashboard. This is useful for CI environments or shared machines.

Step 2: Configure your client

Add the Humic MCP server to your client. The server runs via npx, so there’s nothing to install globally.

Claude Code
Cursor
Windsurf
Codex
Other clients

claude mcp add humic -- npx -y @humicdev/cli mcp serve

That’s it. Claude Code will start the server automatically when needed.

Manual configuration

If you prefer to configure manually, add to your project’s .mcp.json or global ~/.claude.json:

.mcp.json

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

Open a terminal in your project and run:

cursor mcp add humic -e npx -a '-y' -a '@humicdev/cli' -a 'mcp' -a 'serve'

Manual configuration

Go to Cursor Settings > MCP and add a new server, or add to your project’s .cursor/mcp.json:

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

Add to your ~/.codeium/windsurf/mcp_config.json:

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

codex mcp add humic -- npx -y @humicdev/cli mcp serve

If this is the first time you are using an MCP server in Codex, enable the rmcp feature first. Add the following to your ~/.codex/config.toml:

[features]
experimental_use_rmcp_client = true

Any MCP client that supports stdio transport can connect to the Humic server. The configuration is always the same:

Command: npx
Arguments: -y @humicdev/cli mcp serve
Transport: stdio

Refer to your client’s documentation for how to add MCP servers.

Step 3: Verify the connection

Ask your agent something like:

List my design systems

If everything is set up correctly, you’ll see your organizations and design systems. If you get an authentication error, run npx @humicdev/cli login again.

Available tools

The MCP server exposes the following tools to your agent. Tools are annotated with safety hints so your agent knows which operations are read-only and which modify data.

Reading data

Tool	Description
`getDesignSystems`	List all design systems and organizations you have access to
`getTokens`	Get all tokens with resolved values, filterable by type and status
`getUsageGuidelines`	Get the full design system context including CSS, Tailwind config, and usage rules
`getScales`	Get color scales and their steps (light and dark hex values)
`getPrimitives`	Get primitive scale values (spacing, fonts, radii, etc.)
`getUnusedTokens`	Find tokens not referenced by any other token
`getInconsistentTokens`	Find tokens with values outside your design system’s scales
`getActivityLog`	Get recent changes with who changed what and when

Creating and updating

Tool	Description
`setupDesignSystem`	Create a complete design system with scales, primitives, and tokens in one call
`createDesignSystem`	Create an empty or template-based design system
`upsertTokens`	Create or update up to 500 tokens in bulk
`createColorScale`	Add a color scale with light and dark mode steps
`createPrimitives`	Add primitive scale values (spacing, font sizes, etc.)
`updateColorScaleSteps`	Update hex values for specific scale steps
`updatePrimitives`	Update existing primitive values
`renameDesignSystem`	Rename a design system
`renameToken`	Rename a token while preserving its history
`moveTokens`	Move tokens to a different group by changing their name prefix
`duplicateToken`	Copy a token with a new name

Deleting

Tool	Description
`deleteTokens`	Soft-delete tokens (restorable in the Humic UI)
`deleteColorScale`	Soft-delete a color scale (restorable in the Humic UI)
`deletePrimitives`	Permanently delete primitive scale values

Syncing and validation

Tool	Description
`syncProjectFiles`	Write latest CSS, Tailwind config, and context files to your project
`validateTokenUsage`	Check code against your design system’s usage rules (requires Anthropic API key)

Syncing project files

If you use humic init to set up a humic.config.json in your project, the agent can call syncProjectFiles to write the latest CSS custom properties, Tailwind config, and usage context to your local files after making changes. This keeps your project in sync without leaving the editor.

Code validation

The validateTokenUsage tool checks your code against the design system’s rules — catching hardcoded colors, spacing values, and other violations. It returns a compliance score and specific suggestions. This tool requires an Anthropic API key (used locally, no data is sent to Humic):

npx @humicdev/cli config set anthropic-key sk-ant-...

Example prompts

Once connected, try these prompts with your agent:

“Show me all color tokens in my design system”
“Create a new spacing token spacing.lg with value 32px”
“Are there any tokens using values outside my scales?”
“Set up a new design system called ‘Brand 2.0’ with a blue and gray color scale”
“Validate this component against my design system”
“What changed in the design system this week?”

Environment variables

Variable	Description
`HUMIC_API_KEY`	API key for authentication (alternative to `humic login`)
`HUMIC_BASE_URL`	Override the API base URL (default: `https://humic.dev`)

Troubleshooting

'Not authenticated' error

Run npx @humicdev/cli login to re-authenticate. If you’re using HUMIC_API_KEY, verify the key is valid in your Humic dashboard.

Server not showing up in my client

Make sure Node.js 18+ is installed and accessible from your terminal. Try running npx @humicdev/cli mcp serve manually — if it starts without errors, the issue is in your client configuration.

'Could not reach Humic API' error

Check your internet connection. If you’re behind a proxy or firewall, you may need to configure HUMIC_BASE_URL or allow traffic to humic.dev.

validateTokenUsage not working

This tool requires a separate Anthropic API key. Set it with npx @humicdev/cli config set anthropic-key sk-ant-.... The key is stored locally and only used for local validation.

Getting Started

​Prerequisites

​Step 1: Authenticate

​Step 2: Configure your client

​Step 3: Verify the connection

​Available tools

​Reading data

​Creating and updating

​Deleting

​Syncing and validation

​Syncing project files

​Code validation

​Example prompts

​Environment variables

​Troubleshooting

Prerequisites

Step 1: Authenticate

Step 2: Configure your client

Step 3: Verify the connection

Available tools

Reading data

Creating and updating

Deleting

Syncing and validation

Syncing project files

Code validation

Example prompts

Environment variables

Troubleshooting