MCP Bridge

This page shows you how to connect external AI tools — like Claude, ChatGPT, or any MCP-compatible client — to the block editor through the MCP Bridge.

What the MCP Bridge does

The built-in AI chat (Unbot) works directly inside the editor. The MCP Bridge extends that — it lets external AI tools control the same editor, using the same underlying operations.

You start a session in the editor. The external AI connects to that session. It can read your block tree, insert blocks, change styles, update content — anything the built-in AI can do.

Prerequisites

The MCP Bridge requires the WordPress MCP Adapter — the official WordPress plugin that exposes abilities as MCP tools. Install it alongside the Abilities API:

composer require wordpress/abilities-api wordpress/mcp-adapter

Or install both as plugins from their GitHub releases. Once active, Unblock's abilities are automatically available on the default MCP server — no extra configuration needed.

Start an MCP session

1. Open the AI chat panel in the editor
2. Click "Or start an MCP session" at the bottom of the empty chat screen
3. A session ID appears with a green pulsing dot — the session is live
4. Click the copy button next to the session ID

Give the session ID to your external AI tool. It uses this ID to target your specific editor tab.

To stop the session, click the stop button (square icon) next to the session ID. The session also stops automatically when you close or navigate away from the editor tab.

Connect your AI client

Configure your MCP client (Claude Desktop, VS Code, Cursor, etc.) to connect to WordPress. Two transport options are available:

Local sites (STDIO)

For local development environments with WP-CLI access:

{
  "mcpServers": {
    "wordpress": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}

Replace /path/to/your/wordpress with your WordPress root directory and admin with your WordPress username.

Remote sites (HTTP)

For remote or hosted WordPress sites, use the HTTP proxy:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "https://your-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password"
      }
    }
  }
}

Create an application password in Users → Profile → Application Passwords in your WordPress admin.

Combine with other MCP servers

MCP clients can connect to multiple servers at once. This means you can give your AI tool access to WordPress and other tools in the same session.

Example: Figma + Unblock

The official Figma MCP server gives AI tools access to your designs — layout structure, colors, typography, spacing, and screenshots. It returns design data, not HTML or CSS. The AI translates that data into Unblock blocks and styles.

Connect both servers in your MCP client config:

{
  "mcpServers": {
    "wordpress": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    },
    "figma": {
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

With both servers connected, the AI sees tools from Figma (read designs, extract variables) and from Unblock (insert blocks, create styles). You don't need to tell it which tools to use — it figures that out. But you do need to tell it where to look and what to build:

"Get the hero section from this Figma file: https://www.figma.com/design/abc123. Read its layout, colors, and typography. Then build it in the WordPress editor using the Unblock tools — start an MCP session first."

The AI calls Figma's get_design_context to read the design, then uses unblock/get-instructions to learn Unblock's conventions, and builds the section with unblock/insert-blocks and unblock/create-styles.

Available tools

Once connected, the external AI has access to these operations through the WordPress Abilities API:

Tool	What it does
unblock/list-sessions	List all active editor sessions
unblock/get-instructions	Get Unblock conventions and CSS guidelines
unblock/get-context	Read the current block tree, CSS variables, breakpoints, fonts
unblock/insert-blocks	Add new blocks from HTML markup
unblock/replace-blocks	Replace a block's inner content
unblock/update-attributes	Change HTML attributes or tag name on a block
unblock/update-content	Update text content or Twig expressions
unblock/update-script	Add, update, or remove block JavaScript
unblock/create-styles	Import CSS for class selectors
unblock/move-blocks	Reorder blocks
unblock/remove-blocks	Delete blocks

All tools except list-sessions and get-instructions require a session_id parameter.

tip

Call get-instructions once at the start of a session. It returns Unblock's CSS naming conventions, HTML structure patterns, and tool usage rules — the same guidelines the built-in AI follows.

Common mistake

The session ID is tied to a single browser tab. If you reload the page or navigate away, the session ends and the ID becomes invalid. Start a new session after reloading.

How it works

The MCP Bridge uses the WordPress Abilities API to expose tools that external AI clients can discover and call. The connection flows entirely through your WordPress site — no external servers involved.

External AI tool
    ↓  calls ability (e.g. unblock/insert-blocks)
WordPress REST API
    ↓  writes command to database
SSE stream (browser)
    ↓  picks up command, executes in editor
Browser POSTs result back
    ↓
WordPress returns result to AI tool

The browser keeps an open SSE (Server-Sent Events) connection to unblock/v1/mcp/stream. Commands flow through the wp_options table as a lightweight IPC mechanism — no WebSocket server, no external dependencies.

Session lifecycle

• Heartbeat: The SSE stream sends a keepalive every 20 seconds. Sessions without a heartbeat for 120 seconds are marked stale and filtered out of list-sessions.
• Reconnect: If the SSE connection drops (network hiccup, server restart), the bridge reconnects automatically after 2 seconds.
• Cleanup: Closing the editor tab deregisters the session via beforeunload. If the browser crashes, the stale timeout handles cleanup.

Next steps

• AI Assistant Overview — learn the built-in chat features
• Agents — how Builder, Designer, and Writer agents work
• Skills — extra capabilities for the built-in AI