Connect AI agents

The Particles Model Context Protocol server exposes 42 tools — design tokens, semantic search, change-impact analysis, WCAG contrast, Figma component graphs, docs & guidelines, releases, scalability score, coverage, and governance status — to AI agents like Claude and Codex. Your agent reasons about real, live tokens instead of pasted hex codes. Six of the tools write (create a branch, and create/update/delete tokens on it — singly or in batch); the rest are reads. Writes are governed exactly like the Studio editor — main is protected, write-time policy applies, and a read-only token can only read.

Create an access token#

Both connection options below authenticate with an access token, created in Studio: Settings → Access Tokens → Create token.

Option 1 — Remote MCP endpoint (recommended)#

Zero install. Your client speaks Streamable HTTP directly to the hosted endpoint, authenticated with your access token as a bearer header:

https://api.particles-ui.com/v1/mcp

Claude Code

Add it with the CLI:

claude mcp add --transport http particles-ui https://api.particles-ui.com/v1/mcp \
  --header "Authorization: Bearer pat_your_token_here"

Or drop this into your project’s .mcp.json:

{
  "mcpServers": {
    "particles-ui": {
      "type": "http",
      "url": "https://api.particles-ui.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer pat_your_token_here"
      }
    }
  }
}

Codex

Codex configures MCP servers in ~/.codex/config.toml (or a project-scoped .codex/config.toml). A Streamable HTTP server takes a url plus either bearer_token_env_var (reads the token from an environment variable — recommended, keeps the secret out of the file) or a static http_headers entry:

[mcp_servers.particles-ui]
url = "https://api.particles-ui.com/v1/mcp"
bearer_token_env_var = "PARTICLES_TOKEN"

Export PARTICLES_TOKEN=pat_your_token_here in the shell Codex runs from. Alternatively, set the header inline (avoid checking this into version control):

[mcp_servers.particles-ui]
url = "https://api.particles-ui.com/v1/mcp"
http_headers = { "Authorization" = "Bearer pat_your_token_here" }

Claude.ai & Claude Desktop (connector UI)

Claude’s Add custom connector dialog only has a name and a URL field — there’s no way to set a header. The remote endpoint also accepts the access token as a ?token= query parameter for exactly this reason (the header wins if a client sends both).

1. In Claude (web or desktop), open Settings → Connectors → Add custom connector.
2. Name: Particles UI.
3. Remote MCP server URL: https://api.particles-ui.com/v1/mcp?token=pat_your_token_here.
4. Leave the OAuth Client ID and Client Secret fields empty — Particles authenticates with access tokens, not OAuth.
5. Click Add, then enable the connector from the tools menu in a chat.

Option 2 — Local stdio server (fallback / air-gapped)#

For clients that only support local process-based MCP servers, or for air-gapped environments, run the server locally with npx. It authenticates the same way — with a pat_… access token — or with a device token from particles auth login if you have the Particles CLI installed.

{
  "mcpServers": {
    "particles-ui": {
      "command": "npx",
      "args": ["-y", "@particlesui/mcp-server"],
      "env": {
        "PARTICLES_TOKEN": "pat_your_token_here",
        "PARTICLES_PROJECT_ID": "<optional default project id>"
      }
    }
  }
}

The equivalent Codex stdio entry:

[mcp_servers.particles-ui]
command = "npx"
args = ["-y", "@particlesui/mcp-server"]
env = { "PARTICLES_TOKEN" = "pat_your_token_here", "PARTICLES_PROJECT_ID" = "<optional default project id>" }

See the @particlesui/mcp-server README for GUI-client PATH pitfalls, the particles-mcp setup auto-configure command, and the full tool reference.

What can agents do?#

42 tools, grouped by what they’re for. Full input/output shapes are in the package README.

Tokens & search

Impact & accessibility

Figma components

Project navigation

Docs & knowledge graph

Scalability & governance

Editing tokens (write)

Design-system structure (write)

¹ find_tokens uses semantic ranking when embeddings are available for your project, and otherwise falls back to text matching — nothing to configure. ² search_docs and get_guidelines require the Team plan or above. ³ get_neighborhood requires the Business plan (knowledge graph explorer feature).

Troubleshooting#