Version: Latest

AI Client Setup

Connect any MCP-compatible AI client or coding IDE to Dragble. Once configured, the AI calls editor tools like add_row, update_heading, export_html directly — no JSON hallucination, no broken designs, no prompt-engineering tricks.

:::tip After MCP setup: connect your AI agent to the live editor

MCP config only gives your AI client access to Dragble tools. To make it control the editor canvas, connect with MCP using a pairing code:

Open your Dragble editor and start MCP with startMCPPairing.
Copy the returned 8-digit pairing code.
Paste this into your AI agent chat, replacing the number with your code:

Connect with Dragble MCP using pairing code 47289153

The AI agent should call pair_with_editor automatically and connect to the live editor session.

If your client exposes manual tool calls, run pair_with_editor 47289153 directly. Backend-managed live flows use backend mcp_key directly with the sessionId your frontend created.

:::

Prerequisites:

Generate a Client MCP Pairing Key from your dashboard (db_mcp_client_...)
Save it as an environment variable: export DRAGBLE_MCP_CLIENT_KEY=db_mcp_client_...
Pick your AI client below

OpenCode

Config file location

OS	Path
macOS	`~/.config/opencode/opencode.json`
Linux	`~/.config/opencode/opencode.json`
Windows	`%APPDATA%\opencode\opencode.json` (e.g. `C:\Users\YourName\AppData\Roaming\opencode\opencode.json`)

Config

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dragble": {
      "type": "remote",
      "url": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
      },
      "enabled": true,
    },
  },
}

Verify

opencode
> /mcp list

Expected output:

✓ dragble connected
   Dragble design tools are available

Claude Code

Quick install (CLI)

claude mcp add dragble --transport http \
  --url https://mcp.dragble.com/mcp \
  --header "X-API-Key: db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2"

Manual config

OS	Path
macOS / Linux	`~/.config/claude/config.json`
Windows	`%APPDATA%\claude\config.json`

{
  "mcpServers": {
    "dragble": {
      "transport": "http",
      "url": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
      },
    },
  },
}

Verify

claude mcp list
# Expected:
#   dragble  https://mcp.dragble.com/mcp  connected

Codex (OpenAI's coding agent)

Config file location

OS	Path
macOS / Linux	`~/.codex/config.toml`
Windows	`%USERPROFILE%\.codex\config.toml`

Config

[mcp_servers.dragble]
transport = "http"
url = "https://mcp.dragble.com/mcp"

[mcp_servers.dragble.headers]
"X-API-Key" = "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2"

Verify

codex --mcp-status

Cursor

Config file location

OS	Path
macOS / Linux	`~/.cursor/mcp.json`
Windows	`%USERPROFILE%\.cursor\mcp.json`

Or open Cursor → Settings → MCP → Edit Config.

Config

{
  "mcpServers": {
    "dragble": {
      "url": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
      },
    },
  },
}

Verify

In Cursor, open the chat panel and check the "MCP Tools" indicator at the bottom. It should show the Dragble MCP server as connected.

VS Code (Continue extension)

The Continue extension supports MCP.

Config file location

Open Continue settings → "Configure MCP Servers" → edit:

OS	Path
macOS / Linux	`~/.continue/config.json`
Windows	`%USERPROFILE%\.continue\config.json`

Config (add to `mcpServers` section)

{
  "mcpServers": [
    {
      "name": "dragble",
      "url": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
      },
    },
  ],
}

Reload VS Code window. The Continue chat panel will list Dragble tools.

Windsurf

Edit Windsurf settings → MCP Servers → Add server:

{
  "mcpServers": {
    "dragble": {
      "serverUrl": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
      },
    },
  },
}

Zed

Edit ~/.config/zed/settings.json:

{
  "assistant": {
    "mcp_servers": {
      "dragble": {
        "url": "https://mcp.dragble.com/mcp",
        "headers": {
          "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
        },
      },
    },
  },
}

Claude Desktop

Use Dragble's hosted endpoint as a remote Streamable HTTP MCP server if your Claude Desktop build supports remote HTTP MCP configuration. Edit:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "dragble": {
      "transport": "http",
      "url": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2"
      },
    },
  },
}

Restart Claude Desktop. If your Desktop build only supports stdio MCP servers, use Claude Code or another client with remote HTTP MCP support, or run your own local stdio adapter that targets https://mcp.dragble.com/mcp.

Custom MCP client (programmatic SDK integration)

For Python / Node / Rust apps that integrate the MCP protocol directly without using a coding IDE, choose the key by flow: third-party-style pairing uses DRAGBLE_MCP_CLIENT_KEY; backend-managed orchestration uses DRAGBLE_MCP_KEY with a frontend-created sessionId.

Node.js / TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.dragble.com/mcp"),
  {
    requestInit: {
      headers: { "X-API-Key": process.env.DRAGBLE_MCP_CLIENT_KEY! },
    },
  },
);

const client = new Client(
  { name: "my-app", version: "1.0.0" },
  { capabilities: {} },
);
await client.connect(transport);

const pairResult = await client.callTool({
  name: "pair_with_editor",
  arguments: { code: "47289153" },
});
const { sessionId } = JSON.parse(pairResult.content[0].text as string);

// Use tools
await client.callTool({
  name: "add_row",
  arguments: { sessionId, cells: [50, 50] },
});

Python

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import os, json

async with streamablehttp_client(
    url="https://mcp.dragble.com/mcp",
    headers={"X-API-Key": os.environ["DRAGBLE_MCP_CLIENT_KEY"]},
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        pair_result = await session.call_tool("pair_with_editor", {"code": "47289153"})
        session_id = json.loads(pair_result.content[0].text)["sessionId"]

        await session.call_tool("add_row", {
            "sessionId": session_id,
            "cells": [50, 50],
        })

Two workflow patterns

After your AI client is configured, you have two ways to use it:

Pattern A — Live pairing with the editor (real-time canvas updates)

The user works in your Dragble-embedded SaaS, clicks "Connect AI", gets an 8-digit pairing code, and types a pairing prompt into their AI agent chat. Mutations stream live to the editor canvas. Best for interactive design copilots.

SaaS user                 Editor (browser)              AI agent chat
─────────                 ────────────────              ───────────────────
clicks "Connect AI"
                          sdk.startMCPPairing({ id })
                          shows pairing code:
                          ┌────────────────────┐
                          │ AI Pairing Code:   │
                          │     47289153       │
                          │ stored per session │
                          └────────────────────┘
copies "47289153"

                                                        > Connect with Dragble MCP
                                                          using pairing code 47289153
                                                          [AI calls pair_with_editor]
                                                        ✓ Paired to session sess_xyz

                                                        > Make a Black Friday email
                                                          with hero, 3 product cards,
                                                          and CTA at the bottom
                                                        [AI calls add_row, add_heading,
                                                         add_button, update_body, ...]
                          ★ each tool call appears
                            live on the canvas

Most AI clients can infer the tool call from a normal chat prompt:

> Connect with Dragble MCP using pairing code 47289153

Use that exact wording in OpenCode, Claude Code, Codex, Cursor, or any MCP-aware agent. The AI client should call pair_with_editor automatically and return the live editor sessionId.

If your client supports explicit tool entry, the pair tool is available as pair_with_editor:

> pair_with_editor 47289153

Use this when you want users to watch the AI build the design in real time.

Pattern B — Backend-managed live editor orchestration

Your frontend starts the MCP session in the live editor, then sends the sessionId to your backend. Your backend connects with backend mcp_key, injects that sessionId into every tool call, and MCP routes each action to the editor canvas.

Then call tools with the live editor sessionId:

> add_row with cells [100]
> add_heading "Monthly Update" h1
> add_paragraph "Here's what's new..."
> add_button "Read more" href "https://acme.com/blog"
> export_json
> export_html
< returns editable JSON and full HTML

You can keep the user in the editor while your backend drives the AI loop. Persist the design from editor-side onChange or SDK export methods in your own application.

Verifying the connection

After configuring your client, ask it to list available tools:

> What MCP tools do you have access to from dragble?

A working setup shows Dragble design tools grouped by capability:

Category	Tools
Session	`pair_with_editor`, `begin_batch`, `commit_batch`, `rollback_batch` (`create_session` and `destroy_session` are backend-key only)
Row	`add_row`, `update_row`, `delete_row`, `move_row`, `duplicate_row`, `get_rows`, `get_row_info`, `set_column_layout`
Column	`get_columns`, `update_column`
Add content	`add_heading`, `add_paragraph`, `add_button`, `add_image`, `add_divider`, `add_spacer`, `add_menu`, `add_social`, `add_html`, `add_video`, `add_table`, `add_timer`, `add_form`, `add_carousel`
Update content	`update_heading`, `update_paragraph`, `update_button`, `update_image`, ...
Content CRUD	`delete_content`, `move_content`, `duplicate_content`, `get_contents`, `reorder_content`
Body	`update_body`, `get_body`
Export	`export_html`, `export_json`, `export_section_html`, `export_element_html`
Inspect & quality	`get_session_readiness`, `get_stats`, `get_condensed`, `get_content_hierarchy`, `validate`, `analyze_design`, `template_readiness_report`
Bulk and presets	`add_row_with_contents`, `bulk_update_style`, `apply_palette`, `apply_typography`, `add_preset_section`, `search_preset_sections`, `apply_mobile_overrides`

Troubleshooting

`MCP_KEY_REQUIRED`

MCP access requires an mcp_client_key (db_mcp_client_*) credential for third-party AI client connections. editor_key cannot be used.

Third-party AI clients only accept mcp_client_key (db_mcp_client_xxx). If you are passing an editor_key (db_xxx) or backend MCP key (db_mcp_xxx), generate a Client MCP Pairing Key from the dashboard and use that instead.

`Invalid MCP key`

The key was rotated or revoked. Generate a new Client MCP Pairing Key in the dashboard and update your client config.

`MCP_NOT_ENABLED_FOR_PROJECT`

Project's plan doesn't include Design AI. Upgrade in the Dragble dashboard → Billing.

Connection succeeds but no tools appear

Check the project status in the dashboard:

Project must be Active (not paused or disabled)
AI features must be Enabled
Plan must include Design AI feature

Tool calls succeed but editor doesn't update

There is no editor connected to the session. MCP tools require a live editor WebSocket. Start or rejoin an editor session first:

Open your editor in a browser
Call sdk.joinMCP({ id: "..." }) for backend flow, or sdk.startMCPPairing({ id: "..." }) for client pairing
Pair an AI client with the code, or have your backend use the frontend-provided sessionId

`INVALID_MCP_SESSION_ID`

The id you provided didn't match the format:

Length: 8–128 characters
Allowed chars: a-z A-Z 0-9 - _

Common mistakes:

id: "abc" — too short (3 chars)
id: "has spaces" — space not allowed
id: "session/123" — slash not allowed
id: "[email protected]" — @ and . not allowed

Pick something like "acme-user-42-doc-99", crypto.randomUUID(), or a hash of your domain entities.

Pairing code not found

Pairing codes are stored on the active MCP session and do not have a separate TTL. If the AI client cannot pair with a code:

Show the current code again from the editor with sdk.getPairingCode()
Confirm the MCP session is still active and has not been disconnected
Or use your backend-managed live flow instead: skip pairing, share the frontend-created sessionId with your backend

Behind a corporate firewall / HTTP MCP blocked

Some corporate networks block unfamiliar developer endpoints. Test Streamable HTTP reachability:

curl -X POST https://mcp.dragble.com/mcp \
  -H "X-API-Key: db_mcp_client_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"ping","method":"ping"}'

If blocked, contact your IT team to allowlist mcp.dragble.com over HTTPS.

My IDE / agent isn't listed here

Any client that implements the Model Context Protocol standard (Streamable HTTP transport or stdio transport) can connect. The configuration pattern is identical:

URL: https://mcp.dragble.com/mcp
Header: X-API-Key: db_mcp_client_...

Common variations in config syntax:

mcpServers (Claude Code, Cursor, Continue)
mcp_servers (Codex TOML, Zed)
mcp (OpenCode)
serverUrl vs url vs httpUrl (vendor naming)

If your IDE supports MCP but uses a different schema, consult its documentation. The Dragble side accepts standard MCP Streamable HTTP — the only Dragble-specific requirement for third-party AI clients is the X-API-Key header set to your mcp_client_key.

OpenCode​

Config file location​

Config​

Verify​

Claude Code​

Quick install (CLI)​

Manual config​

Verify​

Codex (OpenAI's coding agent)​

Config file location​

Config​

Verify​

Cursor​

Config file location​

Config​

Verify​

VS Code (Continue extension)​

Config file location​

Config (add to mcpServers section)​

Windsurf​

Zed​

Claude Desktop​

Custom MCP client (programmatic SDK integration)​

Node.js / TypeScript​

Python​

Two workflow patterns​

Pattern A — Live pairing with the editor (real-time canvas updates)​

Pattern B — Backend-managed live editor orchestration​

Verifying the connection​

Troubleshooting​

MCP_KEY_REQUIRED​

Invalid MCP key​

MCP_NOT_ENABLED_FOR_PROJECT​

Connection succeeds but no tools appear​

Tool calls succeed but editor doesn't update​

INVALID_MCP_SESSION_ID​

Pairing code not found​

Behind a corporate firewall / HTTP MCP blocked​

My IDE / agent isn't listed here​

OpenCode

Config file location

Config

Verify

Claude Code

Quick install (CLI)

Manual config

Verify

Codex (OpenAI's coding agent)

Config file location

Config

Verify

Cursor

Config file location

Config

Verify

VS Code (Continue extension)

Config file location

Config (add to `mcpServers` section)

Windsurf

Zed

Claude Desktop

Custom MCP client (programmatic SDK integration)

Node.js / TypeScript

Python

Two workflow patterns

Pattern A — Live pairing with the editor (real-time canvas updates)

Pattern B — Backend-managed live editor orchestration

Verifying the connection

Troubleshooting

`MCP_KEY_REQUIRED`

`Invalid MCP key`

`MCP_NOT_ENABLED_FOR_PROJECT`

Connection succeeds but no tools appear

Tool calls succeed but editor doesn't update

`INVALID_MCP_SESSION_ID`

Pairing code not found

Behind a corporate firewall / HTTP MCP blocked

My IDE / agent isn't listed here