MCP Server

Connect AI assistants to Helios component APIs, documentation, design tokens, and icons.

The Helios Design System (HDS) MCP server gives AI assistants structured access to our component APIs, documentation, design tokens, and icons. It helps an assistant find HDS resources and apply our guidance while you design, build, or review an application.

The server implements the Model Context Protocol (MCP), an open standard for connecting AI applications to external tools and data sources.

What the server provides

After you connect the server, your AI assistant can consult:

Exact component invocation names and API details.
Component usage, accessibility, and content guidance.
Design token names and resolved values.
Icon names, sizes, and variants.

Your assistant can use these sources when HDS information is relevant to your task. The server provides context and guidance. It doesn't generate application files, install dependencies, or modify your project.

Set up the server

Requirements

You need:

Node.js 24 or later
An MCP client that supports local servers using the standard input/output (stdio) transport

The examples below use pnpm.

Install the server

Install @hashicorp/design-system-mcp as a development dependency from your application directory.

.bash

pnpm add --save-dev @hashicorp/design-system-mcp

The package includes the compiled server, so you don't need to clone or build the HDS repository. It runs as a separate development tool; don't import it into your application or include it in your production bundle.

Connect an MCP client

Add the following server definition to your MCP client configuration. Replace /absolute/path/to/application with the absolute path to the application where you installed the package.

.json

{
  "mcpServers": {
    "helios-design-system": {
      "command": "pnpm",
      "args": [
        "--dir",
        "/absolute/path/to/application",
        "exec",
        "helios-design-system-mcp"
      ]
    }
  }
}

The --dir option ensures that pnpm finds the locally installed server and starts it in your application directory. If your client already starts there, you can use "args": ["exec", "helios-design-system-mcp"] instead.

Restart or reload your MCP client after updating its configuration.

Verify the connection

Ask your client a question that requires HDS information, for example:

Find the HDS component for an advanced data table and show me its exact invocation name.

Your client should call search_hds_components and return one or more matching components. If your client displays connected servers or tools, look for the server you configured as helios-design-system and the tools listed below.

Available tools

Your assistant uses these tools to find HDS information in response to your requests. All tools are read-only and use local catalogs or bundled documentation.

Tool	Purpose
`search_hds_components`	Finds components and confirms their exact names.
`get_hds_component`	Retrieves a component's API, including arguments, accepted values, blocks, and yielded components.
`search_hds_docs`	Finds usage, accessibility, and other guidance in the bundled HDS documentation.
`read_hds_docs`	Reads a complete documentation passage, including guidance and code examples.
`search_hds_icons`	Finds icons and their available sizes by name or keyword.
`search_hds_tokens`	Finds design tokens, their values, and CSS variable names.

Prompt guidance and examples

Tell your assistant what you want to accomplish and include relevant context, such as the component name, framework, documentation area, or code you want reviewed. Specific requests help your assistant find relevant HDS guidance.

For more specific results, you can ask your assistant to find a component and consult its documentation before suggesting an implementation. For example:

Find the HDS Button component, search its documentation for full-width usage, then read the guidance and code examples before showing me how to add it to my Ember template.

Example prompts

"Which HDS component should I use for a confirmation dialog?"
"How do I add sorting to an HDS Advanced Table?"
"Review this template against the HDS Button accessibility guidance."
"Find the design token for the primary interactive color."
"Find the icon for copying content and list its available sizes."
"What changed in the latest version of the HDS Modal?"

Data and privacy

The server is read-only. It doesn't modify your application, HDS packages, or documentation.

Component, token, and icon data come from your application's installed HDS packages when their catalogs can be resolved. Otherwise, the server uses its own HDS dependencies, which may be different versions.
Documentation search uses a snapshot bundled with the server.
Tool and resource requests don't make network requests or send your project data to an HDS service.

Documentation results include canonical helios.hashicorp.design URLs. An MCP client may choose to open or fetch those URLs independently, subject to the client's configuration and permissions.

Troubleshooting

The server doesn't connect

Confirm that the --dir argument points to the application where you installed @hashicorp/design-system-mcp.
Confirm that Node.js 24 or later and pnpm are available to the process that starts your MCP client.
Confirm that you've installed your application's dependencies.
Restart or reload your MCP client after changing its configuration.

Tools or resources return catalog errors

Run pnpm install from your application directory, then restart your MCP client. Check the client's server logs for the package and catalog path involved. If the error persists, include the error message and your installed MCP and HDS package versions when contacting support.

Inspect the server directly

Run the MCP Inspector from your application directory to view the registered tools and resources and call them interactively.

.bash

pnpm dlx @modelcontextprotocol/inspector pnpm exec helios-design-system-mcp

For implementation details, visit the HDS repository. To get support or report an issue, visit the support page.

On this page: