Uniform MCP server

The Uniform MCP server exposes tools that let an external MCP client — Cursor, Claude Code, GitHub Copilot, Windsurf, Claude Desktop, and others — manage your Uniform project. If you are new to MCP, see the Model Context Protocol introduction.

Uniform MCP server vs external MCP servers

These are two different things that work in opposite directions:

  • The Uniform MCP server (this page) exposes tools to manage Uniform from your AI assistant (Cursor, Claude Code, etc.).
  • External MCP servers bring third-party tools (Linear, Notion, GitHub, ...) into Scout, inside Uniform.

If you want Cursor to talk to Uniform, you want the Uniform MCP server. If you want Scout to talk to Linear, you want an external MCP server.

AI credits required

Tools that call an LLM — such as searching, creating, editing, and duplicating compositions, entries, patterns, components, and content types, or running translations — require AI credits in your Uniform team. Pure read tools do not consume credits.

If you have already used all your existing credits you can request additional credits.

Pair the MCP server with Uniform AI rules

The Uniform MCP server exposes tools — it doesn't explain what Uniform is, what its entities are, or how they relate. To get good results, pair it with the Uniform AI rules so your assistant has the conceptual context it needs to use the tools well.

Once connected, your AI assistant can do things like:

  • "Create a hero component with a title and a rich-text description field."
  • "Find every composition that references the Hero pattern."
  • "Duplicate this entry, rename it, and translate it to fr-FR."
  • "What's pending in the next release?"
  • "Re-read the latest content type definitions before we make changes."
  • "List the locales configured in this project."

The Uniform MCP server exposes 30+ tools covering content (compositions, entries, assets, translations), patterns, component and content type definitions, the project map, releases, classification (signals, quirks, aggregates, enrichments), optimization data, and utility helpers (locales, environment lookup, docs Q&A, UUIDs).

You will need a team admin access level to your Uniform project to get started.

The easiest way to set up the Uniform MCP server is to use the Uniform CLI. The CLI supports cursor, claude, copilot, and other (writes a generic mcp.json you can paste into any client):

npx @uniformdev/cli@latest ai mcp install

This command will automatically configure the MCP server for your project. Follow the prompts to enter your Uniform project details and pick the agent you want to install for.

If you prefer to set up the MCP server manually or need a custom configuration, follow the instructions below.

  1. Go to your team's /security/api-keys section.
  2. Create a new API key with Developer role assigned to your project.
  3. Click on the chevron icon next to "Copy as .env" and select "Copy as mcp json" option.
mcp-json
Create MCP json

Treat your `mcp.json` like a secret

The Developer API key has write access to the project. Do not commit mcp.json (or any file containing the key) to source control — add it to your .gitignore. If a key is leaked, revoke it and issue a new one.

Create a mcp.json file with the configuration for your chosen transport method. The location of this file depends on your MCP client. For example, in Cursor, create a mcp.json in the .cursor folder within the root of your project.

The endpoint URL depends on your team's region — see Regions and data residency. The snippets below render the right URL for your selected region.

The HTTP transport connects directly to the official Uniform MCP server. This is the recommended approach because it:

  • Requires no local dependencies or installation.
  • Is always running the latest version of the Uniform MCP server.
  • Works with web-based MCP hosts like v0.dev and n8n that cannot run local processes.
{ "mcpServers": { "Uniform": { "url": "https://ai.uniform.global/projects/<project-id>/mcp", "headers": { "x-api-key": "<api-key>" } } } }

Replace <project-id> with your Uniform project ID and <api-key> with the API key you created in the previous step.

Paste the JSON you copied in the previous step into the mcp.json file.

Afterwards, Cursor will prompt you to add the MCP server to your project:

mcp-server-detected
Add MCP server

This also depends on your MCP client. In Cursor, open Cursor Settings, go to Tools & Integrations, and see the Uniform MCP server. The icon should be green if the MCP server is running.

cursor-settings
MCP server in Cursor settings

For Claude Code, you can add mcp.json to the root of your project or add it via the Claude command line (see docs for more). Check the official documentation of your MCP client for more details.

To confirm the server is talking to the right project, ask your AI client:

Use getUniformEnvironment to tell me which Uniform project I'm connected to.

Now you can test the MCP server by running the following command in your MCP client prompt:

create a hero component with title and description field (rich text).

Voila! You should see something similar to this reply:

cursor-response
MCP server in Cursor

This indicates that Cursor called mutateComponent and inspected the payload as well as the response:

mcp-response
MCP server response in Cursor

Now, if you open your Uniform project's component library, you should see the new component you just created:

new-component-created
New component created.

To stop using the Uniform MCP server, do both of the following:

  1. Remove the Uniform entry from mcp.json (or delete the file if it only contains that entry) and restart your MCP client so it drops the tools.
  2. Revoke the API key under your team's /security/api-keys section. This is the only way to make sure the key cannot be used again, even if a copy of mcp.json was leaked.
SymptomLikely cause and fix
Tools don't appear in your client.Restart the client after editing mcp.json. In Cursor, open Cursor Settings → Tools & Integrations and check the server status; the icon should be green.
401 Unauthorized or "invalid API key".The API key is wrong, was revoked, or belongs to a different region. Re-copy the key from your team's /security/api-keys section and confirm the URL matches your team's region.
403 Forbidden on a write tool.The API key's role does not have access to the project, or lacks permissions for that entity. Use a key with the Developer role assigned to the right project.
404 Not Found from the MCP endpoint.The <project-id> in the URL is wrong, or the URL points at the wrong region. Double-check both.
Tool call returns "out of AI credits".Your team's monthly credits are exhausted. Wait for the next monthly allocation or request additional credits.
Stale data after dashboard edits.Your client is caching tool results. Ask your AI to re-read the entity (readContent, getDefinition, ...) before making more changes.

Follow these best practices to achieve reliable, high-quality results when working with the MCP server:

By default, LLM's knowledge of Uniform will be limited to what was indexed by LLM using the public internet and subject to the cutoff date. It is highly recommended that you feed uniform-specific AI rules into your LLM context to enhance your prompting with the latest knowledge of Uniform.

You can head over to the AI rules guide to learn how to use AI rules to enhance your dev experience.

After making structural changes through the MCP server, use the sync command to ensure your local project files stay up to date. Our AI rules provide instructions on maintaining regular synchronization.

Once you have synced your project, you should regularly commit your exported Uniform files to Git. This will give you a clear history of updates over time and make it easy to roll back changes if needed.

If you have made updates to Uniform entities such as components or content types directly in the Uniform dashboard, make sure to ask the MCP to reload the latest version before proceeding with any additional changes. This will keep the AI's context up to date and help prevent overwriting recent updates.

Provide clear, specific prompts instead of broad, ambiguous requests. For complex workflows, break them down into smaller, focused tasks that the AI can handle more accurately. Many AI-assisted editors include planning features that help decompose large tasks into manageable steps. Use these tools to create a structured approach before making changes through the MCP server. Keep chats concise and focused on the current task. Start new chats to clear context when starting a new task.

After the AI creates or modifies components, content types, or other entities through the MCP server, review the results in your Uniform project. AI assistants can misinterpret instructions or make mistakes, so it's important to verify that the generated structures match your expectations before using them in production.

You can use multiple MCP servers together to handle specialized tasks in your workflow.

For example:

  • Figma MCP: generate React components from Figma designs
  • Context7 MCP: query up-to-date documentation for code libraries
  • Storybook MCP: retrieve information about components in your design system

Manage your active MCP tools

AI editors support only a limited number of MCP tools at the same time, so you may need to enable or disable specific MCP servers based on what you're trying to accomplish.

Last modified
Next
AI rules