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.

Using Claude Code, Claude Desktop, or Cursor? Installing the agent setup package is the recommended way to get started — you get the MCP server, along with always-on instructions and skills, in one step. If you only want to install the MCP server without any of the built-in skills, follow the setup instructions for the agent that you use.

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.

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.

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.

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.

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

Agent Setup Package

MCP Reference

Ditto Specs CLI Reference

Additional Tools

Legacy

Installation

Before you start

Claude Code

Local scope (default)

Project scope

User scope

Log in

Cursor, VS Code, Windsurf

Codex

Add the server

Log in

Figma Make

Other clients

Authenticating with an API token

​Before you start

​Claude Code

​Local scope (default)

​Project scope

​User scope

​Log in

​Cursor, VS Code, Windsurf

​Codex

​Add the server

​Log in

​Figma Make

​Other clients

​Authenticating with an API token

Before you start

Claude Code

Local scope (default)

Project scope

User scope

Log in

Cursor, VS Code, Windsurf

Codex

Add the server

Log in

Figma Make

Other clients

Authenticating with an API token