MCP Server

MCP Server

OpenWP includes a built-in Model Context Protocol (MCP) server that exposes WordPress operations as tools for external AI agents like Claude Code, Cursor, and other MCP clients.

Protocol Version

MCP Protocol: 2025-06-18 Server Version: 0.1.0

Architecture

MCP Client (Claude Code, etc.)
    │
    ├── SSE Transport (/mcp/v1/sse + /mcp/v1/messages)
    │   └── Real-time bidirectional via Server-Sent Events
    │
    └── HTTP Transport (/mcp/v1/http)
        └── Stateless JSON-RPC over HTTP (recommended)

Components

Component	File	Purpose
MCP_Server	inc/MCP/MCP_Server.php	Route registration and request handling
MCP_Auth	inc/MCP/MCP_Auth.php	Bearer token authentication
MCP_Session	inc/MCP/MCP_Session.php	Session ID management
MCP_Message_Queue	inc/MCP/MCP_Message_Queue.php	Message queue for SSE transport
MCP_SSE_Transport	inc/MCP/MCP_SSE_Transport.php	SSE streaming transport
MCP_HTTP_Transport	inc/MCP/MCP_HTTP_Transport.php	Streamable HTTP transport
Tool_Registry	inc/MCP/Tool_Registry.php	Registers and lists MCP tools
Tool_Executor	inc/MCP/Tool_Executor.php	Executes MCP tool calls

Authentication

MCP endpoints use Bearer token authentication:

Authorization: Bearer <YOUR_TOKEN>

The token is configured in OpenWP settings and stored encrypted. Rate limiting is applied to the authenticated WordPress user.

JSON-RPC Methods

initialize

Returns server capabilities.

{
    "protocolVersion": "2025-06-18",
    "serverInfo": {"name": "OpenWP - Site Name", "version": "0.1.4"},
    "capabilities": {"tools": {}, "resources": {}, "prompts": {}}
}

tools/list

Returns all available MCP tools with their schemas.

tools/call

Execute a tool by name with arguments.

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "wp_list_posts",
        "arguments": {"per_page": 10}
    }
}

resources/list / prompts/list

Return empty arrays (reserved for future use).

Notifications

• notifications/initialized - Acknowledged silently
• notifications/cancelled / openwp/kill - Kills the SSE session

Tool Modules

MCP tools are organized into 6 modules, each toggleable independently:

Module	Tools	Requires	Description
core	39	Always available	Posts, pages, users, media, taxonomy, options
woo	25	WooCommerce	Products, orders, customers, coupons
plugin	13	Always available	Plugin lifecycle management
theme	13	Always available	Theme lifecycle management
db	1	Always available	Raw SQL queries (through SQL Guard)
polylang	11	Polylang	Multilingual content operations

Module Classes

Module	Class	File
Core	CoreTools	inc/MCP/Modules/CoreTools.php
WooCommerce	WooTools	inc/MCP/Modules/WooTools.php
Plugins	PluginTools	inc/MCP/Modules/PluginTools.php
Themes	ThemeTools	inc/MCP/Modules/ThemeTools.php
Database	DatabaseTools	inc/MCP/Modules/DatabaseTools.php
Polylang	PolylangTools	inc/MCP/Modules/PolylangTools.php

All modules implement ToolModuleInterface.

MCP Bridge Actions

When the Agent Engine needs to call MCP tools, it routes through risk-stratified bridge actions:

Bridge Action	Risk	Approval	Backup	Use Case
mcp_read_tool	low	No	No	Read-only operations
mcp_write_tool	medium	Yes	No	Write operations
mcp_admin_tool	high	Yes	Yes	Destructive operations

The LLM is told which bridge to use per tool via the MCP_TOOL_CATALOG in the system prompt.

Client Setup

Claude Code

claude mcp add --transport http my-site https://example.com/wp-json/mcp/v1/http \
  --header "Authorization: Bearer <YOUR_TOKEN>"

JSON Configuration

{
    "transport": "streamable_http",
    "url": "https://example.com/wp-json/mcp/v1/http",
    "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
    }
}

Quick Test (curl)

# Initialize session
curl -X POST 'https://example.com/wp-json/mcp/v1/http' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"test","version":"1.0"}}}'

# List tools
curl -X POST 'https://example.com/wp-json/mcp/v1/http' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

File Uploads

MCP supports file uploads via one-time upload tokens:

• POST /mcp/v1/upload/{token} - Upload file with a one-time token
• Tokens are generated by the Tool_Executor for tools that accept file inputs