Dialtone MCP Server | Dialtone Design System

The Dialtone MCP Server lets compatible AI clients search Dialtone through Model Context Protocol (MCP) tools. Use the Dialtone CLI for direct terminal queries, shell scripts, or lookups that should match the Dialtone version installed in your project.

What It Does

The Dialtone MCP Server provides AI assistants with real-time search access to:

3,315 CSS utility classes - Find classes like d-p8, d-d-flex, d-w100p
5,691 design tokens - Find tokens like --dt-color-foreground-primary, --dt-spacing-100
87 Vue components - Discover DtButton, DtModal with full API documentation
594 icons - Find icons like bell-ring, arrow-up, calendar-plus
Public documentation - search_documentation: Search usage prose, recipes, accessibility rules, migration guides, and design principles. Use for "how-to" and "why" questions that go beyond component/token/icon lookups.

Smart Features

Filters deprecated items - Automatically removes outdated classes and components
Recommends alternatives - Suggests better patterns when discouraged classes are found
AI-optimized results - Smart scoring provides the most relevant matches first
Design system aware - Understands Dialtone's conventions and patterns

Installation

There are three ways to install the Dialtone MCP Server. Project-scoped installation takes priority over user-scoped when both exist.

Project-Scoped (Recommended for Teams)

Best for team collaboration - everyone uses the same version via version control.

npm install -D @dialpad/dialtone-mcp-server

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "dialtone": {
      "command": "dialtone-mcp-server"
    }
  }
}

Commit .mcp.json to version control. Restart Claude Code to connect.

User-Scoped (Personal Use)

Available across all your projects. Choose one method:

Option A: Install in dedicated directory

# Install in a dedicated directory
mkdir -p ~/.mcp-servers
cd ~/.mcp-servers
npm install @dialpad/dialtone-mcp-server

# Add to Claude Code
claude mcp add dialtone --scope user dialtone-mcp-server

Option B: Install globally

npm install -g @dialpad/dialtone-mcp-server
claude mcp add dialtone --scope user dialtone-mcp-server

Option C: Use npx (no installation)

claude mcp add dialtone --scope user -- npx -y @dialpad/dialtone-mcp-server

This stores configuration in ~/.claude/mcp.json.

HTTP Transport (Coming Soon)

Remote server deployment for enterprise use.

claude mcp add dialtone-http --transport http --scope user https://mcp.dialtone.dialpad.com

Search Tools

Utility Classes

Tool: search_utility_classes

Find CSS utility classes to style HTML elements. Use when your query mentions CSS properties (padding, margin, display, flex) or values (8px, 100%, center, auto).

Example queries:

"padding 8px"       → d-p-100, d-pbs-100, d-pbe-100, d-pis-100, d-pie-100 d-px-100, d-py-100
"display flex"      → d-d-flex, d-d-inline-flex
"width 100%"        → d-w100p
"margin top auto"   → d-mbs-auto
"text align center" → d-ta-center

Parameters:

query (required): CSS property and/or value
limit (optional): Maximum results (1-50, default 15)

Design Tokens

Tool: search_tokens

Find design tokens (CSS variables) from Dialtone's design system. Use when your query mentions token categories (color, space, font, size) or semantic names (primary, positive, foreground, background).

Example queries:

"color foreground primary" → --dt-color-foreground-primary
"spacing 100"              → --dt-spacing-100, --dt-spacing-100-negative
"font family"              → --dt-font-family-body, --dt-font-family-expressive
"font weight bold"         → --dt-font-weight-bold

Parameters:

query (required): Token category, name, or value
limit (optional): Maximum results (1-50, default 15)

Components

Tool: search_components

Find Vue components from Dialtone's component library with props, events, and slots. Use when your query mentions UI elements (button, modal, input, dropdown) or component names.

Example queries:

"button"   → DtButton, DtButtonGroup, DtBanner (29 results)
"modal"    → DtModal, DtBanner, DtDropdown (6 results)
"checkbox" → DtCheckbox, DtCheckboxGroup, DtRadio

Returns:

Component name
Description
Props (name, type, default, description)
Events (name, description)
Slots (name, description)
Import path

Parameters:

query (required): Component name or UI element
limit (optional): Maximum results (1-30, default 10)

Icons

Tool: search_icons

Find icons from Dialtone's icon library and learn how to use icon components. Icons are imported from @dialpad/dialtone-icons/vue, not @dialpad/dialtone-vue.

Example queries:

"notification" → bell, bell-ring, bell-off, bell-plus
"arrow up"     → arrow-up, arrow-up-down, arrow-up-left
"profile"      → user
"calendar"     → calendar, calendar-plus, calendar-event

Returns:

Icon name
Categories
Keywords
Tree-shakable import path
Usage example

Parameters:

query (required): Icon name, category, or keyword
limit (optional): Maximum results (1-50, default 20)

Usage Examples

Finding Styling Classes

When working on a component and need specific styling:

User: "What class adds padding 8px to all sides?"
Claude: [Uses search_utility_classes tool]
Result: d-p-100 (padding: var(--dt-spacing-100) which equals 8px)

Discovering Components

When building UI and unsure what components exist:

User: "What button components are available in Dialtone?"
Claude: [Uses search_components tool]
Result: DtButton, DtButtonGroup, DtIconButton with complete
        prop documentation, events, and usage examples

Looking Up Tokens

When implementing designs and need exact token values:

User: "What's the primary foreground color token?"
Claude: [Uses search_tokens tool]
Result: --dt-color-foreground-primary
        Value: #1C1C1C (in light theme)
        Available in: dp-light, dp-dark themes

Finding Icons

When adding icons to your interface:

User: "Show me all notification-related icons"
Claude: [Uses search_icons tool]
Result: bell, bell-ring, bell-off, bell-plus, bell-minus
        Import: import { IconBell } from '@dialpad/dialtone-icons/vue'

CLI or MCP Server

The MCP server and Dialtone CLI use the same Dialtone search engine. Choose the interface that fits the task:

Use the MCP server when you want an AI client to choose and run Dialtone searches during a conversation.
Use the CLI when you want to run an explicit terminal query, use Dialtone data in a script, or inspect the version installed in your project.

You can install both. The MCP server handles tool calls from an AI client, while the CLI handles commands that you run directly.

Configuration

Updating the Server

The server checks for updates automatically on startup. If a new version is available, you'll see:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  Dialtone MCP Server Update Available
   Current: v1.2.0
   Latest:  v1.2.1

   To update:
   1. npm install -D @dialpad/dialtone-mcp-server@latest
   2. Restart this conversation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To update:

Project-scoped:

npm install -D @dialpad/dialtone-mcp-server@latest

User-scoped (local directory):

cd ~/.mcp-servers
npm update @dialpad/dialtone-mcp-server

User-scoped (global):

npm update -g @dialpad/dialtone-mcp-server

User-scoped (npx): No action needed - npx always uses the latest version.

After updating, restart your Claude Code conversation to load the new version.

Managing Connections

List configured servers:

claude mcp list

View specific server:

claude mcp get dialtone

Remove server:

claude mcp remove dialtone

Compatible Platforms

The Dialtone MCP Server works with any MCP-compatible AI assistant:

✅ Claude Code CLI - Primary integration
✅ Claude Desktop - Via configuration file
✅ VS Code - With GitHub Copilot
✅ Cursor - Native MCP support
✅ Windsurf - Native MCP support
✅ Cline - MCP integration
✅ Continue - MCP support
✅ Any MCP-compatible client

Platform-Specific Setup

Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dialtone": {
      "command": "npx",
      "args": ["-y", "@dialpad/dialtone-mcp-server"]
    }
  }
}

Restart Claude Desktop and look for the 🔌 icon to confirm connection.

Troubleshooting

Server Not Connecting

For project-scoped installation:

Verify .mcp.json exists in your project root with correct format
Check package is installed:
```
npm list @dialpad/dialtone-mcp-server
```

Verify bin command exists:

ls node_modules/.bin/dialtone-mcp-server

Restart Claude Code completely

For user-scoped installation:

List configured servers:
```
claude mcp list
```
Check if dialtone is listed and enabled
Test the server:
```
claude mcp get dialtone
```
Check configuration:
```
cat ~/.claude/mcp.json
```

Version Shows Old After Updating

The server loads once at conversation start. You must restart your conversation after updating to see the new version.

No Search Results

Use keywords, not questions - Try "button" instead of "What button components exist?"
Try broader terms first - Search "padding" before "padding left 16px"
Check example queries - Review the examples in each tool section above
Verify installation - Ensure the server is running: claude mcp list

Build Issues

If you're developing or testing locally:

Ensure workspace dependencies are built first
Run from monorepo root: pnpm install
Build the server: pnpm nx run dialtone-mcp-server:build
Check for TypeScript errors in the console

Resources

Dialtone Documentation - dialtone.dialpad.com
npm Package - @dialpad/dialtone-mcp-server
GitHub Repository - github.com/dialpad/dialtone
MCP Protocol - modelcontextprotocol.io
Report Issues - GitHub Issues

Next Steps

Now that you have the MCP server installed, explore these resources:

Dialtone CLI - Search Dialtone from your terminal or a script
Getting Started with Dialtone - Learn Dialtone basics
Utility Classes - Browse all utility classes
Design Tokens - Explore design tokens
Components - Discover Vue components
Icons - View the icon library

Dialtone MCP Server documentation last updated Friday, September 4, 2026

fix/popover-modal-zindex-scope

What It Does #

Smart Features #

Installation #

Project-Scoped (Recommended for Teams) #

User-Scoped (Personal Use) #

Option A: Install in dedicated directory

Option B: Install globally

Option C: Use npx (no installation)

HTTP Transport (Coming Soon) #

Search Tools #

Utility Classes #

Design Tokens #

Components #

Icons #

Usage Examples #

Finding Styling Classes #

Discovering Components #

Looking Up Tokens #

Finding Icons #

CLI or MCP Server #

Configuration #

Updating the Server #

Managing Connections #

Compatible Platforms #

Platform-Specific Setup #

Troubleshooting #

Server Not Connecting #

Version Shows Old After Updating #

No Search Results #

Build Issues #

Resources #

Next Steps #

What It Does

Smart Features

Installation

Project-Scoped (Recommended for Teams)

User-Scoped (Personal Use)

HTTP Transport (Coming Soon)

Search Tools

Utility Classes

Design Tokens

Components

Icons

Usage Examples

Finding Styling Classes

Discovering Components

Looking Up Tokens

Finding Icons

CLI or MCP Server

Configuration

Updating the Server

Managing Connections

Compatible Platforms

Platform-Specific Setup

Troubleshooting

Server Not Connecting

Version Shows Old After Updating

No Search Results

Build Issues

Resources

Next Steps