Prompt for your AI assistant

Paste into Cursor, Claude Code, Codex, or GitHub Copilot:

Connect my AI agent to the Dragble MCP Server so it can edit templates in real time:
1. Review documentation at https://www.dragble.com/docs/mcp-server/overview.
2. Add Dragble tools to my MCP config with my Dragble API credentials.
3. Allow the agent to call tools: add_row_with_contents, update_text, export_html.

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.

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:

  1. Open your Dragble editor and start MCP with startMCPPairing.
  2. Copy the returned 8-digit pairing code.
  3. Paste this into your AI agent chat, replacing the number with your code:
text
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:

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

OpenCode

Config file location

OSPath
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

jsonc
{
  "$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

bash
opencode
> /mcp list

Expected output:

plaintext
āœ“ dragble connected
   Dragble design tools are available

Claude Code

Quick install (CLI)

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

Manual config

OSPath
macOS / Linux~/.config/claude/config.json
Windows%APPDATA%\claude\config.json
jsonc
{
  "mcpServers": {
    "dragble": {
      "transport": "http",
      "url": "https://mcp.dragble.com/mcp",
      "headers": {
        "X-API-Key": "db_mcp_client_A1b2C3d4E5f6G7h8I9j0K1l2",
      },
    },
  },
}

Verify

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

Codex (OpenAI's coding agent)

Config file location

OSPath
macOS / Linux~/.codex/config.toml
Windows%USERPROFILE%\.codex\config.toml

Config

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

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

Verify

bash
codex --mcp-status

Cursor

Config file location

OSPath
macOS / Linux~/.cursor/mcp.json
Windows%USERPROFILE%\.cursor\mcp.json

Or open Cursor → Settings → MCP → Edit Config.

Config

jsonc
{
  "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:

OSPath
macOS / Linux~/.continue/config.json
Windows%USERPROFILE%\.continue\config.json

Config (add to mcpServers section)

jsonc
{
  "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:

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

Zed

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

jsonc
{
  "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:

OSPath
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
jsonc
{
  "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

typescript


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

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.

Live Pairing Sequence Flow 8-Digit Code Handshake
SaaS User Editor (browser) AI Agent Chat 1. Click "Connect AI" AI Pairing Code: 47289153 3. "Connect using pairing code 47289153" pair_with_editor("47289153") āœ“ Paired to live session ā˜… Live canvas updates Tool calls stream in real time over WebSocket directly to the user's active canvas.

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

plaintext
> 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:

plaintext
> 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:

plaintext
> 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:

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

A working setup shows Dragble design tools grouped by capability:

CategoryTools
Sessionpair_with_editor, begin_batch, commit_batch, rollback_batch (create_session and destroy_session are backend-key only)
Rowadd_row, update_row, delete_row, move_row, duplicate_row, get_rows, get_row_info, set_column_layout
Columnget_columns, update_column
Add contentadd_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 contentupdate_heading, update_paragraph, update_button, update_image, ...
Content CRUDdelete_content, move_content, duplicate_content, get_contents, reorder_content
Bodyupdate_body, get_body
Exportexport_html, export_json, export_section_html, export_element_html
Inspect & qualityget_session_readiness, get_stats, get_condensed, get_content_hierarchy, validate, analyze_design, template_readiness_report
Bulk and presetsadd_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:

  1. Open your editor in a browser
  2. Call sdk.joinMCP({ id: "..." }) for backend flow, or sdk.startMCPPairing({ id: "..." }) for client pairing
  3. 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: "user@email.com" — @ 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:

bash
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.