Installation

Before you start

The Ditto MCP server lives at:

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

It uses Streamable HTTP transport and supports OAuth, so most clients ask you to log in to Ditto the first time they connect. There’s no token to create, and no credentials to store in your configuration. Need a static credential instead — for continuous integration, a headless agent, or a client without OAuth support? See Authenticating with an API token.

Agent setup package

For Claude Code and Cursor, the agent setup package is the default way to integrate Ditto. It bundles:

The Ditto MCP server, preconfigured
Session instructions that tell the agent to check Ditto styleguide rules and reuse existing text when writing user-facing copy
Skills:
- /ditto-review: check the current diff’s user-facing strings against your styleguide rules and existing Ditto text; returns a fix-list.
- /ditto-audit [path]: check the path for user-facing strings against your styleguide rules and existing Ditto text; returns a fix-list.
- /ditto-spec-audit [component]: (for repos using Ditto specs) audit every instance of a specced component across the codebase against its spec’s rules.
- /ditto-spec-component <component>: (for repos using Ditto specs) analyze a component, create or update its Ditto spec file (and specs for child components that lack one), and sync styleguide rules from the platform.
- /ditto-spec-gaps [component]: (for repos using Ditto specs) find copy patterns across component instances that should be styleguide rules but aren’t; create approved ones on the platform.

If you only want the MCP server without the instructions and skills, use the manual setup in the sections below instead.

Install in Claude Code

Send each command as its own prompt:

/plugin marketplace add dittowords/ditto-agent-setup

/plugin install ditto@ditto

Then:

Restart Claude Code and approve the ditto MCP server (if not approved already).
Run /mcp, select ditto, and choose Authenticate. A browser tab opens for you to log in to Ditto and approve access.

Cursor

In Cursor Settings go to Plugins and paste https://github.com/dittowords/ditto-agent-setup in the “Search or Paste Link” input. Click on Ditto -> Add to Cursor.

Next go to Tools & MCPs and authenticate with the ditto Plugin MCP Server.

Optional: set up Ditto Specs

Ditto Specs are *.ditto.md files that co-locate copy rules with your components. Run /ditto-spec-setup and the agent will ask for confirmation, then install the specs CLI if missing, create dittospec.config.json and workspace.ditto.md, and scaffolds component spec files. With specs in place /ditto-spec-audit, /ditto-spec-component, and /ditto-spec-gaps become usable.

Manual setup

The sections below configure the MCP server directly in each client, without the package.

Figma Make

Open connector settings

From the chat box, select Add context, hover over Connectors, then choose Manage.

Create a new connector

Navigate to the Created by you tab and click Create. Enter “Ditto” as the connector name.

Set the MCP server URL

Enter the following URL and click Create:

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

Connect and log in

Click Connect on the connector. Figma Make picks up Ditto’s OAuth flow and opens a browser tab where you log in to Ditto and approve access.

Enable tools

Review the available tools and enable the ones you’d like to use.

Figma Make reaches MCP servers over HTTPS only. It doesn’t support localhost or stdio servers.

Claude Code

Claude Code supports remote MCP servers natively.

Local scope (default)

Adds the Ditto MCP server for your own use in the current project. This is private to you and won’t be visible to other team members.

claude mcp add --transport http ditto https://api.dittowords.com/v2/mcp

Project scope

Shares the Ditto MCP configuration with your entire team via version control. This creates a .mcp.json file at your project root that can be checked into source control.

claude mcp add --scope project --transport http ditto https://api.dittowords.com/v2/mcp

Or manually add a .mcp.json file to your project root:

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

The file holds no credentials, so it’s safe to commit. Each team member logs in with their own Ditto account the first time they use the server. Claude Code also prompts for approval the first time a project-scoped server is used.

User scope

Adds the Ditto MCP server across all of your projects. This is private to you but available everywhere.

claude mcp add --scope user --transport http ditto https://api.dittowords.com/v2/mcp

Log in

After adding the server with any scope, restart any active instances of Claude Code. Then run /mcp, select ditto, and choose Authenticate. A browser tab opens for you to log in to Ditto and approve access. Approve the connection to see Ditto MCP tools in your tool list.

Codex

Codex supports remote MCP servers over Streamable HTTP, with OAuth as the default authentication method.

Add the server

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

Or add it to ~/.codex/config.toml yourself:

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

To scope the server to a single project instead, use .codex/config.toml in the project root. Codex reads project-level configuration for trusted projects only.

Log in

codex mcp login ditto

A browser tab opens for you to log in to Ditto and approve access. Confirm the result with codex mcp list.

Cursor, VS Code, Windsurf

These clients support remote MCP servers with Streamable HTTP natively.

Open MCP settings

Cursor: Go to Cursor Settings > Tools & MCP and click + Add new MCP server.
VS Code: Open your user or workspace mcp.json and add to servers.
Windsurf: Open your MCP configuration file.

Add the server configuration

Cursor (~/.cursor/mcp.json or workspace .cursor/mcp.json):

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

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

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

Windsurf (MCP configuration file):

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

After saving, your client prompts you to log in to Ditto and approve access. Complete the login in the browser tab that opens, then check your MCP settings — a green status indicator next to the Ditto server means you’re connected.

Other clients

If your MCP client doesn’t support Streamable HTTP or SSE natively, use the mcp-remote package as a bridge. It runs the OAuth flow for you and opens a browser tab for login on first use. This also applies if you’re on Cursor 2.6.x, which has a known bug where the V2 MCP handler doesn’t fall back from Streamable HTTP to SSE — it retries indefinitely instead of connecting. Use the mcp-remote config below as a workaround until the bug is fixed.

Configuration using mcp-remote

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

Authenticating with an API token

OAuth is the recommended way to connect, but the MCP server also accepts a Ditto API token. Use a token when there’s no browser to log in with or no OAuth support to rely on:

Continuous integration and other automated pipelines
Headless agents running on a server
Machine-to-machine access, where the credential belongs to a system rather than a person
MCP clients that don’t support OAuth

With OAuth, the agent acts as you — the Ditto account you logged in with, and its permissions. With an API token, the agent acts as the user who generated that token, so if an API token is ever shared, the Ditto activity history will attribute certain actions to the wrong person.

Generate a token from your developer integrations settings, then pass it in an Authorization header as token <your-api-token>.

Figma Make

Follow the Figma Make steps, but before clicking Connect, open Advanced settings and add a custom request header:

Header name: Authorization
Header value: token <your-api-token>

Claude Code

Add --header to any of the scoped commands:

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

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

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

Or manually, in .mcp.json:

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

Each team member then sets the DITTO_API_TOKEN environment variable with their own API token.

Codex

Add an Authorization header to the server entry in ~/.codex/config.toml:

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

To keep the token out of the file, use env_http_headers to pull the header value from an environment variable instead:

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

Codex sends the environment variable’s value as the header verbatim, so include the token prefix when you set it:

export DITTO_MCP_AUTH="token <your-api-token>"

Skip bearer_token_env_var — it sends the credential as Authorization: Bearer <token>, which Ditto reads as an OAuth access token and rejects.

Cursor, VS Code, Windsurf

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

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

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

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

Windsurf (MCP configuration file):

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

mcp-remote with an API token

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

Overview

API Reference

CLI Reference

MCP Reference

Ditto Specs CLI Reference

Additional Tools

Legacy

Installation

Before you start

Agent setup package

Install in Claude Code

Cursor

Optional: set up Ditto Specs

Manual setup

Figma Make

Claude Code

Local scope (default)

Project scope

User scope

Log in

Codex

Add the server

Log in

Cursor, VS Code, Windsurf

Other clients

Authenticating with an API token

​Before you start

​Agent setup package

​Install in Claude Code

​Cursor

​Optional: set up Ditto Specs

​Manual setup

​Figma Make

​Claude Code

​Local scope (default)

​Project scope

​User scope

​Log in

​Codex

​Add the server

​Log in

​Cursor, VS Code, Windsurf

​Other clients

​Authenticating with an API token

Before you start

Agent setup package

Install in Claude Code

Cursor

Optional: set up Ditto Specs

Manual setup

Figma Make

Claude Code

Local scope (default)

Project scope

User scope

Log in

Codex

Add the server

Log in

Cursor, VS Code, Windsurf

Other clients

Authenticating with an API token