MCP setup

1. Cloud — the default

Open the extension's MCP page from its header chip. Select Cloud and create an anonymous credential. The agent endpoint is https://mcp.designmode.app/mcp (Streamable HTTP). The extension and agent use the same bearer token; there is no Design Mode OAuth login, account check or subscription verification. Enter the token locally through a protected client input or securely supplied environment variable, never in AI chat, shell history, screenshots or committed configuration.

2. Local — run from source

Review and clone https://github.com/SandeepBaskaran/design-mode and run npm ci at the repository root. Configure your MCP client to launch the stdio command below with the absolute checkout path; then select Local in the extension. In JSON use command npm and args ["start", "--prefix", "/absolute/path/to/design-mode/packages/mcp-local"]. The agent CLI package is private; no published CLI installation is assumed. Clients share a bridge owner on localhost:9960. If another app owns that port, use DM_PORT and match the extension's Local port. Never kill a foreign process.

npm start --prefix /absolute/path/to/design-mode/packages/mcp-local

3. Self-hosted — your relay

Deploy packages/mcp-cloud on a Node.js host with Redis and TLS. Use the extension's Self-hosted mode with your relay's base URL, create a credential on that relay and configure the agent with https://your-relay.example/mcp. Replace the Cloud endpoint in the examples, and supply that relay's token—not the hosted Cloud credential. See https://github.com/SandeepBaskaran/design-mode/tree/main/packages/mcp-cloud for deployment prerequisites.

Claude Code — Project .mcp.json

Merge this server into .mcp.json. Set DESIGN_MODE_TOKEN locally in the environment that launches Claude Code, using protected input rather than a literal token in a shell command. Claude Code expands ${DESIGN_MODE_TOKEN} in headers. Review project-server approval, then check /mcp; restart if the new server has not loaded. Official reference: https://code.claude.com/docs/en/mcp

{
  "mcpServers": {
    "design-mode": {
      "type": "http",
      "url": "https://mcp.designmode.app/mcp",
      "headers": {
        "Authorization": "Bearer ${DESIGN_MODE_TOKEN}"
      }
    }
  }
}

Cursor — Project .cursor/mcp.json or user ~/.cursor/mcp.json

Merge this entry into your existing servers. Supply DESIGN_MODE_TOKEN through the environment used to launch Cursor; its ${env:NAME} syntax differs from Claude Code. Enable the server in Cursor's MCP settings and review each tool's arguments before approval. Official reference: https://cursor.com/docs/context/mcp

{
  "mcpServers": {
    "design-mode": {
      "url": "https://mcp.designmode.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DESIGN_MODE_TOKEN}"
      }
    }
  }
}

VS Code / Copilot — Workspace .vscode/mcp.json — local extension-host chat

Merge both servers and inputs into your configuration. VS Code prompts for the token in a masked input; do not paste it into chat. Start the server with MCP: List Servers. Interactive inputs are not forwarded to Agent Host sessions; for those, follow Microsoft's current configuration reference instead. Official reference: https://code.visualstudio.com/docs/agents/reference/mcp-configuration

{
  "servers": {
    "design-mode": {
      "type": "http",
      "url": "https://mcp.designmode.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:designModeToken}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "designModeToken",
      "description": "Design Mode bearer token",
      "password": true
    }
  ]
}

Other apps and incompatible connectors

Cloud and Self-hosted need Streamable HTTP plus a custom Authorization header. An OAuth-only connector or a client without custom-header support cannot use this bearer token directly. For Claude Desktop, use the documented local stdio configuration via Settings → Developer → Edit Config, then fully quit and restart; see https://modelcontextprotocol.io/docs/develop/connect-local-servers. For Windsurf, Cline and other apps, inspect current first-party transport and credential support rather than reusing another client's JSON. If neither HTTP with headers nor local stdio works, use Copy as Prompt from the Changes tab.

Approve access and test safely

Merge configuration without replacing unrelated servers. Review and trust the endpoint or local command, start or reload the server, and restart the app if needed. Discover tools and schemas, then call get_session_summary with {}. Confirm the actual browser/session state; an MCP chip alone is not proof. With permission to read the page, call get_changes with {}. Empty edits are a valid result. Do not modify a page, clear changes or resolve comments during this test. Keep writes separately approved and revoke an exposed credential in the extension's MCP page.

get_session_summary({})
get_changes({})

Available tools and progressive reads

All modes expose get_session_summary, get_changes, get_screenshot, export_changes, apply_changes, set_change_status, mark_comment_resolved and clear_changes. Start with the summary, then fetch changes once and select unresolved IDs locally: get_changes has no pagination, status filter or max_chars. Use get_screenshot with a returned selector, elementId or commentId (not a raw region argument). export_changes requires format css, tailwind, scss or jsx. Bound writes to explicit IDs; omitting ids in set_change_status affects all items. The icon-led reference is at https://designmode.app/mcp.

Local live rounds and the agent skill

Only Local exposes wait_for_handoff. After explicit opt-in, start with exact pageUrl and timeoutMs up to 20000; resume using the returned sessionId and after cursor. Each feedback report is an immutable Send snapshot. Stop on stopped, busy or an error. Cloud and Self-hosted use one-shot reads, not automatic background polling. Download the canonical skill at https://designmode.app/.well-known/agent-skills/design-mode/SKILL.md; its index is https://designmode.app/.well-known/agent-skills/index.json. A skill does not grant permissions or configure a connection by itself.