Connect the Ditto MCP

Use Ditto with your agents, whether in drafting new copy, reusing existing strings, or integrating with code. The Ditto MCP (Model Context Protocol) server connects AI coding agents to your team’s text in Ditto. Once connected, an agent can fetch your style guide rules before it writes UI copy, search for existing text to reuse instead of inventing new strings, check text against your rules, and create or edit text, projects, variants, and style guides directly from your editor. The server is remote:

https://api.dittowords.com/v2/mcp

It uses Streamable HTTP and OAuth: the first time a client connects, it asks you to log in to Ditto in a browser, and from then on the agent acts as you. There is no token to create and nothing secret to store in your configuration. A static API key is accepted for CI and headless clients that cannot open a browser; see API key for CI and headless clients.

Choose your setup

Client	Recommended path	What you get
Claude Code, Claude Desktop, Cursor	Install the Ditto plugin	The MCP server, always-on instructions that make the agent check Ditto before writing copy, and skills such as `/ditto-review` and `/ditto-audit`
Codex, VS Code, Windsurf, Figma Make, other clients	Add the MCP server directly	The MCP server only. Add your own instructions from Agent instructions

Either path ends with the same tools available to the agent.

Install the Ditto plugin

The plugin is the agent setup package. It bundles the MCP server configuration, session instructions that make the agent check Ditto before writing copy, and skills such as /ditto-review and /ditto-audit; the full list is on Agent instructions.

Claude Code

Run these in a terminal (an agent can run them too; they change settings rather than starting a session):

claude plugin marketplace add dittowords/ditto-agent-setup
claude plugin install ditto@ditto
claude plugin list

Or, inside a Claude Code session, send each command as its own prompt:

/plugin marketplace add dittowords/ditto-agent-setup

/plugin install ditto@ditto

Then log in:

Restart any running Claude Code sessions and approve the ditto MCP server when prompted.
Run /mcp, select the Ditto server (listed as ditto, or plugin:ditto:ditto when it comes from the plugin), and choose Authenticate. A browser tab opens for you to log in to Ditto and approve access.
Back in Claude Code, the Ditto tools appear in your tool list.

Claude Desktop

Claude Desktop has a plugin manager instead of a /plugin command.

Click Customize.
Open the Plugins tab, click Add, then Add marketplace.
Paste https://github.com/dittowords/ditto-agent-setup and confirm.
Find Ditto in the marketplace and click Install.
Go to Connectors, find Ditto, and click Connect (or Reconnect). A browser tab opens for you to log in to Ditto and approve access.

Screenshots of the Claude Desktop steps

Claude Desktop: Plugins tab, Add, Add marketplace

Claude Desktop: paste the marketplace URL

Claude Desktop: Connectors, Ditto, Connect

Cursor

Open Cursor Settings and go to Plugins.
Paste https://github.com/dittowords/ditto-agent-setup into the Search or Paste Link field.
Click Ditto, then Add to Cursor.
Go to Tools & MCPs and log in to the ditto server. A browser tab opens for you to log in to Ditto and approve access. A green status indicator means you are connected.
Start a new Cursor session. Tools from a newly added server only load in sessions started after the install, so a “tools unavailable” message in the current session is expected.

Screenshots of the Cursor steps

Cursor: Plugins, paste the marketplace link

Add the MCP server directly

Use this when you only want the MCP server, or for a client the plugin does not support. Afterwards, add the instruction block from Agent instructions so the agent knows when to use the tools.

Pick a scope:

# Local scope (default): this project, only you
claude mcp add --transport http ditto https://api.dittowords.com/v2/mcp

# Project scope: writes .mcp.json at the repo root so the whole team gets it
claude mcp add --scope project --transport http ditto https://api.dittowords.com/v2/mcp

# User scope: all of your projects, only you
claude mcp add --scope user --transport http ditto https://api.dittowords.com/v2/mcp

Project scope creates this .mcp.json, which holds no credentials and is safe to commit:

{
  "mcpServers": {
    "ditto": {
      "type": "http",
      "url": "https://api.dittowords.com/v2/mcp"
    }
  }
}

Then restart Claude Code, run /mcp, select ditto, and choose Authenticate. Each team member logs in with their own Ditto account the first time. Claude Code also asks for approval the first time a project-scoped server is used.

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in the repo (this project):

{
  "mcpServers": {
    "ditto": {
      "url": "https://api.dittowords.com/v2/mcp"
    }
  }
}

Or go to Cursor Settings › Tools & MCP, click + Add new MCP server, and enter the URL. After saving, Cursor prompts you to log in to Ditto; a green status indicator means you are connected.

Cursor 2.6.x has a known bug where remote servers retry indefinitely instead of connecting. Use the mcp-remote configuration under Other clients as a workaround until it is fixed.

Add to ~/.vscode/mcp.json (all workspaces) or .vscode/mcp.json in the repo:

{
  "servers": {
    "ditto": {
      "type": "http",
      "url": "https://api.dittowords.com/v2/mcp"
    }
  }
}

After saving, VS Code prompts you to log in to Ditto and approve access.

Add to your Windsurf MCP configuration file:

{
  "mcpServers": {
    "ditto": {
      "serverUrl": "https://api.dittowords.com/v2/mcp"
    }
  }
}

After saving, Windsurf prompts you to log in to Ditto and approve access.

codex mcp add ditto --url https://api.dittowords.com/v2/mcp
codex mcp login ditto
codex mcp list

Or add it to ~/.codex/config.toml yourself (use .codex/config.toml in the repo to scope it to one project; Codex reads project-level configuration for trusted projects only):

[mcp_servers.ditto]
url = "https://api.dittowords.com/v2/mcp"

codex mcp login ditto opens a browser tab for you to log in to Ditto. If the login never completes, that is a known Codex bug; use an API key instead (below). Tools appear in Codex sessions started after the server was added.

From the chat box, select Add context, hover over Connectors, then choose Manage.
Open the Created by you tab and click Create. Name the connector “Ditto”.
Enter https://api.dittowords.com/v2/mcp and click Create.
Click Connect. Figma Make opens a browser tab where you log in to Ditto and approve access.
Review the available tools and enable the ones you want.

Figma Make reaches MCP servers over HTTPS only; it does not support localhost or stdio servers.

If your client does not support Streamable HTTP or SSE, bridge it with mcp-remote. It runs the OAuth flow for you and opens a browser tab on first use.

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.dittowords.com/v2/mcp"]
    }
  }
}

Verify the connection

Ask the agent:

List the style guide rules in my Ditto workspace.

A connected agent calls get_styleguide_rules and returns your rules, or says the workspace has none yet. From a terminal, claude mcp list (Claude Code) or codex mcp list (Codex) shows the server’s status; Needs authentication means the login step has not been completed.

API key for CI and headless clients

Logging in with your Ditto account is the recommended way to connect. An API key is for the cases where no browser login is possible: a CI pipeline, an agent running unattended on a server, machine-to-machine access, or a client whose OAuth is broken (Codex, while its bug is open). With a key, the agent acts as the user who created it rather than as the person running it, and Ditto’s activity history attributes its actions accordingly.

Configure an API key

Create an API key (a workspace admin does this once)

The steps are in API authentication.

Pass it as an Authorization header

The header value is token <your-api-key>. If the same pipeline also runs the CLI, keep the key in the DITTO_TOKEN environment variable, which the CLI and the Ditto Specs CLI read.

Claude Code
Cursor, VS Code, Windsurf
Codex
Figma Make
mcp-remote

claude mcp add --transport http ditto https://api.dittowords.com/v2/mcp --header "Authorization: token <your-api-key>"

For project scope, reference the environment variable so the committed file stays free of secrets:

claude mcp add --scope project --transport http ditto https://api.dittowords.com/v2/mcp --header 'Authorization: token ${DITTO_TOKEN}'

Equivalent .mcp.json:

{
  "mcpServers": {
    "ditto": {
      "type": "http",
      "url": "https://api.dittowords.com/v2/mcp",
      "headers": {
        "Authorization": "token ${DITTO_TOKEN}"
      }
    }
  }
}

Each team member then sets DITTO_TOKEN to their own API key.

Add a headers object to the server entry.Cursor (~/.cursor/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "ditto": {
      "url": "https://api.dittowords.com/v2/mcp",
      "headers": { "Authorization": "token <your-api-key>" }
    }
  }
}

VS Code (~/.vscode/mcp.json or .vscode/mcp.json):

{
  "servers": {
    "ditto": {
      "type": "http",
      "url": "https://api.dittowords.com/v2/mcp",
      "headers": { "Authorization": "token <your-api-key>" }
    }
  }
}

Windsurf:

{
  "mcpServers": {
    "ditto": {
      "serverUrl": "https://api.dittowords.com/v2/mcp",
      "headers": { "Authorization": "token <your-api-key>" }
    }
  }
}

Do not commit a file that contains a literal key.

In ~/.codex/config.toml:

[mcp_servers.ditto]
url = "https://api.dittowords.com/v2/mcp"
http_headers = { Authorization = "token <your-api-key>" }

To keep the key out of the file, point Codex at an environment variable instead. Codex sends the variable’s value as the header verbatim, so the value must include the token prefix:

[mcp_servers.ditto]
url = "https://api.dittowords.com/v2/mcp"
env_http_headers = { Authorization = "DITTO_MCP_AUTH" }

export DITTO_MCP_AUTH="token $DITTO_TOKEN"

Do not use bearer_token_env_var: it sends Authorization: Bearer <token>, which Ditto reads as an OAuth access token and rejects.

Follow the Figma Make steps above, but before clicking Connect, open Advanced settings and add a custom request header with name Authorization and value token <your-api-key>.

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.dittowords.com/v2/mcp",
        "--header",
        "Authorization: token <your-api-key>"
      ]
    }
  }
}

Scope results to your codebase

Add a ditto/config.yml (or ditto/config.yaml) file at the repo root listing the Ditto projects this codebase owns:

projects:
  - id: your-project-developer-id

The MCP tools read it and scope results to those projects; it is the same file the CLI uses for pull (see Scope results to your codebase). Find a project’s developer ID under the project’s Development integration menu in the web app, or ask the agent to call list_projects.

Make it stick

Commit:

.mcp.json (Claude Code project scope) or .cursor/mcp.json / .vscode/mcp.json, with no literal keys in them.
ditto/config.yml with your project IDs.
The instruction block from Agent instructions in CLAUDE.md or AGENTS.md. If you installed the plugin, the same instructions load automatically at session start; committing the block as well means every agent, plugin or not, behaves the same way.
DITTO_TOKEN as a secret in CI, only if pipelines run agents or the CLI without a browser.

Optional: Ditto Specs

Ditto Specs are *.ditto.md files that sit next to your design system components and declare their text surfaces, with matching style guide rules synced from Ditto. With the plugin installed, run /ditto-spec-setup; the agent installs the Specs CLI if it is missing, creates dittospec.config.json and workspace.ditto.md, and scaffolds component spec files.

Frequently asked questions

Is this the same as the documentation MCP server? No. https://api.dittowords.com/v2/mcp is the Ditto MCP server described on this page; it connects an agent to your workspace. https://developer.dittowords.com/mcp is this documentation site’s own server for searching the docs. Which tools will the agent use? It depends on the task. Writing UI copy uses get_styleguide_rules, search_ditto_text, and suggest_edit; importing a prototype or a codebase uses create_ditto_project, create_text_items, and the library tools; localization uses the variant and variable tools. Every tool is defined on the Tools page.

Troubleshooting

Needs authentication in claude mcp list: run /mcp, select the server, choose Authenticate, and complete the browser login.
The tools are not in the tool list: restart the session. Newly added servers only load in sessions started after the change.
Unauthorized with an API key (CI only): the header must read Authorization: token <your-api-key>, and the key must come from a workspace with developer integrations enabled.
Results include the wrong projects: check ditto/config.yml at the repo root.

Full list of tools and what each does: MCP tools.

Start here

Concepts

CLI Reference

API Reference

String Formats

MCP Reference

Ditto Specs CLI

Additional Tools

Legacy

Connect the Ditto MCP

Choose your setup

Install the Ditto plugin

Claude Code

Claude Desktop

Cursor

Add the MCP server directly

Verify the connection

API key for CI and headless clients

Scope results to your codebase

Make it stick

Optional: Ditto Specs

Frequently asked questions

Troubleshooting

​Choose your setup

​Install the Ditto plugin

​Claude Code

​Claude Desktop

​Cursor

​Add the MCP server directly

​Verify the connection

​API key for CI and headless clients

​Scope results to your codebase

​Make it stick

​Optional: Ditto Specs

​Frequently asked questions

​Troubleshooting

Choose your setup

Install the Ditto plugin

Claude Code

Claude Desktop

Cursor

Add the MCP server directly

Verify the connection

API key for CI and headless clients

Scope results to your codebase

Make it stick

Optional: Ditto Specs

Frequently asked questions

Troubleshooting