> ## Documentation Index > Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code. > The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference). > Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs. > Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only. > Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install. # Connect the Ditto MCP > Connect Claude Code, Cursor, Codex, VS Code, Windsurf, or Figma Make to Ditto with your Ditto login so agents follow your style guide and reuse text. 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: ```text theme={null} 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](#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](#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](#add-the-mcp-server-directly) | The MCP server only. Add your own instructions from [Agent instructions](/guides/agent-instructions) | Either path ends with the same tools available to the agent. ## Install the Ditto plugin The plugin is the [agent setup package](https://github.com/dittowords/ditto-agent-setup). 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](/guides/agent-instructions#skills-from-the-plugin). ### Claude Code Run these in a terminal (an agent can run them too; they change settings rather than starting a session): ```bash theme={null} 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: ```text theme={null} /plugin marketplace add dittowords/ditto-agent-setup ``` ```text theme={null} /plugin install ditto@ditto ``` Then log in: 1. Restart any running Claude Code sessions and approve the `ditto` MCP server when prompted. 2. 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. 3. 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. 1. Click **Customize**. 2. Open the **Plugins** tab, click **Add**, then **Add marketplace**. 3. Paste `https://github.com/dittowords/ditto-agent-setup` and confirm. 4. Find **Ditto** in the marketplace and click **Install**. 5. Go to **Connectors**, find **Ditto**, and click **Connect** (or **Reconnect**). A browser tab opens for you to log in to Ditto and approve access. Claude Desktop: Customize Claude Desktop: Plugins tab, Add, Add marketplace Claude Desktop: paste the marketplace URL Claude Desktop: install Ditto Claude Desktop: Connectors, Ditto, Connect ### Cursor 1. Open **Cursor Settings** and go to **Plugins**. 2. Paste `https://github.com/dittowords/ditto-agent-setup` into the **Search or Paste Link** field. 3. Click **Ditto**, then **Add to Cursor**. 4. 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. 5. 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. Cursor: Plugins, paste the marketplace link Cursor: Tools & MCPs, log in to ditto ## 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](/guides/agent-instructions) so the agent knows when to use the tools. Pick a scope: ```bash theme={null} # 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: ```json theme={null} { "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): ```json theme={null} { "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](https://forum.cursor.com/t/cursor-fails-to-fall-back-from-streamable-http-to-sse-transport-for-remote-mcp-servers/154390) 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: ```json theme={null} { "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: ```json theme={null} { "mcpServers": { "ditto": { "serverUrl": "https://api.dittowords.com/v2/mcp" } } } ``` After saving, Windsurf prompts you to log in to Ditto and approve access. ```bash theme={null} 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): ```toml theme={null} [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](https://github.com/openai/codex/issues/31573); use an API key instead (below). Tools appear in Codex sessions started after the server was added. 1. From the chat box, select **Add context**, hover over **Connectors**, then choose **Manage**. 2. Open the **Created by you** tab and click **Create**. Name the connector "Ditto". 3. Enter `https://api.dittowords.com/v2/mcp` and click **Create**. 4. Click **Connect**. Figma Make opens a browser tab where you log in to Ditto and approve access. 5. 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`](https://github.com/geelen/mcp-remote). It runs the OAuth flow for you and opens a browser tab on first use. ```json theme={null} { "mcpServers": { "ditto": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.dittowords.com/v2/mcp"] } } } ``` ## Verify the connection Ask the agent: ```text theme={null} 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](https://github.com/openai/codex/issues/31573) 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. The steps are in [API authentication](/api-reference/authentication#create-an-api-key). The header value is `token `. If the same pipeline also runs the CLI, keep the key in the `DITTO_TOKEN` environment variable, which the [CLI](/cli-reference/authentication#in-ci-or-anywhere-without-a-browser) and the [Ditto Specs CLI](/ditto-specs-cli-reference/setup) read. ```bash theme={null} claude mcp add --transport http ditto https://api.dittowords.com/v2/mcp --header "Authorization: token " ``` For project scope, reference the environment variable so the committed file stays free of secrets: ```bash theme={null} claude mcp add --scope project --transport http ditto https://api.dittowords.com/v2/mcp --header 'Authorization: token ${DITTO_TOKEN}' ``` Equivalent `.mcp.json`: ```json theme={null} { "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`): ```json theme={null} { "mcpServers": { "ditto": { "url": "https://api.dittowords.com/v2/mcp", "headers": { "Authorization": "token " } } } } ``` VS Code (`~/.vscode/mcp.json` or `.vscode/mcp.json`): ```json theme={null} { "servers": { "ditto": { "type": "http", "url": "https://api.dittowords.com/v2/mcp", "headers": { "Authorization": "token " } } } } ``` Windsurf: ```json theme={null} { "mcpServers": { "ditto": { "serverUrl": "https://api.dittowords.com/v2/mcp", "headers": { "Authorization": "token " } } } } ``` Do not commit a file that contains a literal key. In `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.ditto] url = "https://api.dittowords.com/v2/mcp" http_headers = { Authorization = "token " } ``` 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: ```toml theme={null} [mcp_servers.ditto] url = "https://api.dittowords.com/v2/mcp" env_http_headers = { Authorization = "DITTO_MCP_AUTH" } ``` ```bash theme={null} export DITTO_MCP_AUTH="token $DITTO_TOKEN" ``` Do not use `bearer_token_env_var`: it sends `Authorization: Bearer `, 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 `. ```json theme={null} { "mcpServers": { "ditto": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.dittowords.com/v2/mcp", "--header", "Authorization: token " ] } } } ``` ## 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: ```yaml theme={null} 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](/mcp-reference/overview#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](/guides/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](/ditto-specs-cli-reference/overview) 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](/mcp-reference/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 `, 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](/mcp-reference/tools).