Royal MCP Documentation

Getting Started

Royal MCP enables AI platforms like Claude, ChatGPT, and Google Gemini to securely interact with your WordPress content through the Model Context Protocol (MCP). This allows AI assistants to read your posts, create content, manage media, and understand your site structure.

What is MCP?

Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI assistants to external data sources. It provides a secure, standardized way for AI platforms to read and interact with your applications.

Requirements

• WordPress 5.8 or higher
• PHP 7.4 or higher
• HTTPS enabled (required for Claude Desktop integration)

Installation

From WordPress.org (Recommended)

Manual Installation

Configuration

Basic Setup

The main Royal MCP settings page showing API key and endpoint configuration

Adding and configuring AI platforms with API keys and model selection

Claude Desktop Integration

Royal MCP includes a native OAuth connector for Claude Desktop. When you add your site as a connector, Claude handles the entire authentication flow automatically — no API keys or config files needed.

Setup Steps

1. Enable Royal MCP

In your WordPress admin, go to Royal MCP → Settings and toggle "Enable Royal MCP Integration" on. This activates the MCP endpoint and OAuth server that Claude needs to connect.

2. Copy your Remote MCP Server URL

Scroll down to "Claude Connector Settings" and copy the Remote MCP Server URL. It will look like: https://yoursite.com/wp-json/royal-mcp/v1/mcp

3. Add the connector in Claude Desktop

Open Claude Desktop, go to Settings → Connectors, click "Add custom connector", enter a name (e.g., "My WordPress Site"), paste the URL, and click "Add".

4. Authorize in your browser

Claude Desktop will open your browser to your WordPress site. Log in with your WordPress credentials if prompted, then you'll see an authorization screen asking to allow Claude to connect. Click "Authorize".

The OAuth consent screen — click "Authorize" to grant Claude access to your WordPress site

5. Return to Claude Desktop

After authorizing, your browser will prompt you to open Claude Desktop. Click "Open Claude" (or similar) to return to the app. Claude will complete the connection automatically and your site's 41+ MCP tools will be available immediately.

Claude Desktop showing Royal MCP connector with all 37 WordPress tools and permission controls

Alternative: Connect via Config File

If the Connectors method doesn't work, you can connect Claude Desktop directly using the config file with your API key. This bypasses OAuth entirely and connects immediately.

{
  "mcpServers": {
    "my-wordpress-site": {
      "url": "https://yoursite.com/wp-json/royal-mcp/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Example Commands

Once connected, try asking Claude:

• "Summarize my last 10 blog posts"
• "List all draft posts on my site"
• "Create a new post about [topic]"
• "What categories do I have?"

Real proof of Royal MCP working with Claude - successful site info retrieval

OAuth 2.0 Connector (Native Claude Desktop Setup)

Royal MCP includes a complete OAuth 2.0 authorization server for Claude Desktop's native “Add Connector” flow. Instead of copy-pasting an API key, you click a button in Claude, log in with your WordPress account, approve the permissions on a consent screen, and you’re connected.

How it Works

When Claude Desktop adds Royal MCP as a connector:

1. Claude calls Royal MCP’s OAuth metadata endpoint at /.well-known/oauth-authorization-server to discover the auth flow.
2. Claude registers itself dynamically (RFC 7591 Dynamic Client Registration). No manual app creation required.
3. Claude redirects you to your WordPress login (PKCE-secured authorization code flow per MCP spec 2025-11-25).
4. You approve a consent screen showing the permissions Claude is requesting.
5. Royal MCP issues an access token (SHA-256 hashed at rest) and a refresh token.
6. Claude uses the access token in the Authorization: Bearer ... header for all subsequent MCP requests.

Setup Steps

The consent screen Claude Desktop shows during OAuth setup

Security Properties

• Access tokens are SHA-256 hashed — the raw token only exists in Claude Desktop, never on disk on your server.
• Authorization codes are single-use with a 10-minute expiry.
• PKCE (S256) is required on every authorization request.
• Redirect URI validation enforces localhost or HTTPS only.
• Daily cleanup of expired OAuth tokens via WordPress scheduled event.

If OAuth Setup Fails

OAuth depends on Claude reaching three URLs on your site — /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, and /wp-json/royal-mcp/v1/mcp. On most hosts this just works. On a few managed hosts (notably SiteGround), nginx-level rules and edge caches can short-circuit those URLs before WordPress sees them, and Claude shows a generic “Couldn’t connect” or “Authorization failed” error. We have dedicated troubleshooting articles for each known failure mode:

• OAuth Fails on Managed Hosts (SiteGround, o2switch, LiteSpeed) — edge caches poisoning the OAuth endpoints. Symptom: authorize fails immediately, cache-hit headers appear on /.well-known/* URLs.
• SiteGround Returns 404 for /.well-known/ — SiteGround’s nginx layer reserves the path prefix and returns 404 before WordPress sees the request. Symptom: tiny nginx 404 with no X-Httpd header on the OAuth metadata URL.
• Fix /.well-known/ Content-Type with a Cloudflare Transform Rule — static files return 200 but with text/plain; strict MCP clients reject the metadata. Free Cloudflare Transform Rule overrides the response Content-Type at the edge in ~2 minutes.
• OAuth Discovery Returns HTML Instead of JSON — a membership plugin (ARMember, MemberPress, Restrict Content Pro) or theme template is intercepting the request and serving its own login or access-denied page. Symptom: /.well-known/oauth-authorization-server returns 200 with an HTML body. Auto-detected by Royal MCP 1.4.22+.
• Web Server 301-Redirects /register to /register/ — Nginx mod_dir, Apache mod_dir, or .htaccess canonicalization adds a trailing slash and OAuth clients don’t follow 301 on POST. Symptom: POST to /register returns 301 with Location: /register/. Auto-detected by Royal MCP 1.4.22+.
• Connect Claude Desktop via API Key (Skip OAuth) — if you only need Claude Desktop, the mcp-remote bridge with an Authorization: Bearer header sidesteps the entire OAuth flow.

AI Code IDEs & Other MCP Clients

Royal MCP works with any MCP-compliant client, not just Claude Desktop. The same API key + URL pattern works in every IDE and CLI that supports MCP servers.

Supported IDEs and Clients

Common Configuration Pattern

Most clients want the same three values — the server URL, your API key, and a header name. The exact JSON shape varies by client but the values are identical:

{
  "name": "Royal MCP",
  "url": "https://yoursite.com/wp-json/royal-mcp/v1/mcp",
  "headers": {
    "Authorization": "Bearer your-api-key-here"
  }
}

For OAuth-capable clients, drop the headers block and the client will negotiate the access token via the OAuth metadata endpoint instead.

LM Studio Setup

LM Studio added native MCP support in version 0.3.x. It expects a config file called mcp.json in your LM Studio config directory.

Config file location:

• macOS: ~/.lmstudio/mcp.json
• Windows: %USERPROFILE%\.lmstudio\mcp.json
• Linux: ~/.lmstudio/mcp.json

Option 1 — direct HTTP (recommended for LM Studio 0.3.x+):

{
  "mcpServers": {
    "royal-mcp": {
      "url": "https://example.com/wp-json/royal-mcp/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Option 2 — mcp-remote bridge (works on every LM Studio version, also a fallback for any stdio-only MCP client):

{
  "mcpServers": {
    "royal-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/wp-json/royal-mcp/v1/mcp",
        "--header",
        "Authorization:Bearer your-api-key-here"
      ]
    }
  }
}

After saving the file, restart LM Studio (or use the “Reload MCP servers” button in newer versions). Royal MCP’s tools should appear in the model’s available-tools list.

Ollama Setup

Recommended frontends that pair Ollama with MCP servers:

If you want the simplest “Ollama + Royal MCP” path: install Continue in VS Code or JetBrains, point it at your local Ollama install for the model, and use the same mcpServers config from the LM Studio section above.

Supported AI Platforms

Royal MCP supports multiple AI platforms. Each can be configured independently.

Platform Resources & Documentation

Official documentation and developer resources for each supported AI platform:

MCP Protocol Resources

Learn more about the Model Context Protocol standard:

Managing API Keys

WordPress API Key

This key authenticates requests to your WordPress site from AI platforms.

• Auto-generated when plugin is activated
• Click "Regenerate" to create a new key (invalidates the old one)
• Keep this key secure - anyone with it can access your site via API

Platform API Keys

These keys authenticate requests from your site to AI services.

• Obtain from each platform's developer console
• Enter in the corresponding platform card in settings
• Keys are stored securely in your WordPress database

MCP Tools Reference

Royal MCP exposes 126 tools to AI platforms (67 WordPress core + 59 conditional plugin integrations), organized by category.

Posts

Pages

Media

Taxonomies

Site & System

Elementor Integration

When Elementor is active on your site, Royal MCP automatically registers 6 additional MCP tools for reading page structures, cloning pages, managing the template library, and bulk text/image replacements. No configuration is required — the tools appear as soon as Elementor is detected.

Use it for: AI-assisted Elementor page building, cloning existing pages as starting templates, bulk text or image swaps across pages, template library management, and programmatic content updates from any MCP-compatible AI client.

Available Tools

Example Queries

Things you can ask Claude or another MCP-compatible AI agent:

• “What sections and widgets are on the /pricing page?”
• “Clone the homepage as a starting template for a new spring-sale landing page.”
• “Replace every ‘Buy Now’ button label with ‘Get Started’ on the homepage.”
• “Swap the hero image on the /about page with the new team photo I uploaded yesterday.”
• “List all saved Elementor templates so I can see what’s available to reuse.”
• “Import the template I exported from staging and create a new About page from it.”

WooCommerce Integration

When WooCommerce is active on your site, Royal MCP automatically registers 9 additional MCP tools for managing products, orders, customers, and store stats. No configuration is required — the tools appear as soon as WooCommerce is detected.

Use it for: AI-assisted product creation, natural-language order status updates, customer lookup, store analytics queries, and bulk inventory adjustments.

Available Tools

Example Queries

Things you can ask Claude or another MCP-compatible AI agent:

• “What were my top 5 best-selling products last month?”
• “List all orders that have been processing for more than 7 days.”
• “Create a new simple product called ‘Premium Coffee Beans’ for $24.99 with 100 units in stock.”
• “Update order #1234 to completed status.”
• “What’s my average order value compared to last month?”
• “Find customers who have spent more than $500 lifetime.”

GuardPress Integration

When GuardPress (the Royal Plugins WordPress security plugin) is active, Royal MCP registers 7 additional tools for monitoring site security, viewing scan results, and reviewing the audit log from any AI client.

Use it for: daily security check-ins, on-demand vulnerability scans, blocked-IP review, failed-login analysis, and audit-log queries.

Available Tools

Example Queries

• “What’s my current security score?”
• “Run a vulnerability scan and tell me what it finds.”
• “Show me all failed login attempts from the last 24 hours.”
• “List the IPs blocked in the past week and the reason for each block.”
• “Are there any plugins on this site with known CVEs?”
• “Summarize the security audit log for high-severity events this month.”

SiteVault Integration

When SiteVault (the Royal Plugins backup & restore plugin) is active, Royal MCP registers 6 additional tools for triggering backups, listing backup history, and reviewing schedules.

Use it for: pre-update backup automation, backup health checks, “is the latest backup complete yet?” status polling, and schedule audits.

Available Tools

Example Queries

• “Trigger a full backup before I install this plugin update.”
• “When was the last successful backup, and how big was it?”
• “Is the backup that’s currently running complete yet?”
• “Run a database-only backup right now.”
• “Show me my backup schedules and when each one runs next.”
• “What’s the total size of all my backups on disk?”

Advanced Custom Fields Integration

When Advanced Custom Fields (free or Pro) is active, Royal MCP registers 4 additional tools for reading and writing ACF fields. Added in v1.4.24.

Why a dedicated integration when wp_get_post_meta already returns custom-field data: WordPress’s meta API returns the raw stored value — serialized arrays for repeaters, raw IDs for relationships, raw attachment IDs for image fields. ACF’s get_field() / update_field() respect each field’s Return Format and hydrate values per field type, the same view a human editor sees in the ACF UI. AI agents interacting with ACF want the formatted view, not the raw serialized one.

Available Tools

Example Queries

• “List the ACF field groups on this site and the fields in each one.”
• “Read all ACF fields for post ID 142 and show me their values.”
• “Get the subtitle field value for the post titled ‘Launch Announcement’.”
• “Update the featured_quote field on post 142 to ‘...’.”
• “Which ACF field groups apply to the Product post type?”

API Reference

Endpoints

Authentication

All API requests require authentication via the WordPress API key:

Activity Log

Royal MCP logs all API interactions for security and debugging purposes.

Accessing the Log

Navigate to Royal MCP > Activity Log in your WordPress admin.

Log Information

• Timestamp - When the request occurred
• MCP Server - Which AI platform made the request
• Action - The MCP tool that was called
• Status - Success or error
• Request/Response - Detailed data (expandable)

Activity log showing all AI interactions with timestamps, actions, and status

Troubleshooting

Common failure patterns & where to fix them

Match your symptom to the right doc:

• OAuth consent completes, then Claude says “Couldn’t reach the MCP server” with an ofid_* code — Cloudflare blocking Anthropic’s backend at the edge. See How Cloudflare’s “Block AI Bots” Breaks MCP Connections.
• Token exchange fails with mcp_token_exchange_failed on an Apache shared host — managed security (Imunify360, mod_security with UA rules) blocking python-httpx. See Apache python-httpx 429 fix.
• Activity Log empty + curl returns 406 with “Mod Security” in the body — cPanel ModSecurity bot-fingerprinting. See ModSecurity 406 fix.
• Discovery returns JSON but issuer points to auth.<subdomain> — Cloudflare Zero Trust hijacking /.well-known/ discovery. See Cloudflare Zero Trust hijack fix.
• Discovery returns HTML instead of JSON — a membership plugin or theme template is intercepting the request. See OAuth discovery HTML fix.
• /.well-known/ returns 404 — nginx (commonly SiteGround) blocking the path prefix. See SiteGround /.well-known/ 404 fix.
• POST to /register gets redirected with a trailing slash — web-server canonicalization breaking OAuth POSTs. See Trailing-slash 301 fix.
• Managed host edge cache serving stale OAuth responses (SiteGround Dynamic Cache, o2switch PowerBoost, LiteSpeed) — see OAuth Fails on Managed Hosts.
• Just want to connect Claude Desktop without debugging OAuth — the API key bypass skips OAuth entirely. Two-line config change, no /.well-known/ discovery required.

For a deeper protocol-level walkthrough of the diagnostic curl probes (4-probe sequence, dual-UA testing, response header reading, paste-ready bash + PowerShell script), see Diagnose Royal MCP Connection Failures with curl.

Claude Desktop requires HTTPS

Claude Desktop will not connect to sites on plain HTTP or localhost. For local development, use ngrok or a similar tunnel that provides an HTTPS endpoint.

API key not working

• Ensure you’re using the WordPress API key, not a platform API key
• Check that the key hasn’t been regenerated since you configured it
• Verify the plugin is activated and integration is enabled in Royal MCP → Settings

Connection test fails on the Royal MCP settings page

• Verify the platform API key is correct
• Check that your server can make outbound HTTPS requests
• Some hosts block external API calls — contact your host if needed
• If the test returns 404, the model dropdown may be set to a model Anthropic has retired. Switch to Claude Sonnet 4.6 (Latest, Recommended) and re-test — this affects only the Test Connection button, not actual Claude usage.

Tools not appearing in Claude

1. Run the troubleshooting start-here checklist first — most “tools missing” reports resolve there. The conflict test in particular often surfaces a security or caching plugin filtering MCP responses before they reach Claude.
2. Disconnect and reconnect the MCP connector in Claude (delete the existing one, wait 30 seconds, re-add it fresh).
3. Check Royal MCP → Activity Logs for errors around the time of the failed connection.
4. Ensure your site’s SSL certificate is valid — expired or self-signed certs fail silently in some MCP clients.

Frequently Asked Questions

Is my data secure?

Yes. All API endpoints require authentication via API key. Activity logging tracks every request. No data is sent to external services without your explicit configuration. HTTPS is required for production use.

Can AI assistants modify my content?

Yes, with proper authentication. The plugin provides tools for creating, updating, and deleting content. All write operations require valid API credentials and are logged.

Does this slow down my site?

No. Royal MCP only activates when an AI platform makes an API request. It does not affect front-end performance or page load times for regular visitors.

Can I use multiple AI platforms?

Yes. You can add and configure as many AI platforms as needed. Each has independent settings and can be enabled/disabled individually.

What happens if I deactivate the plugin?

Your settings are preserved when you deactivate. AI platforms will no longer be able to access your site until you reactivate. Uninstalling completely removes all settings and logs.

Does Royal MCP work with Claude Code, VS Code, Cursor, Windsurf, or other AI IDEs?

Yes. Any MCP-compliant client can connect to Royal MCP. See the AI IDEs & Clients section for the full supported list and the common configuration pattern. Claude Desktop additionally supports the native “Add Connector” OAuth flow — documented in the OAuth 2.0 Connector section.

Does Royal MCP work with custom fields, ACF, MetaBox, JetEngine, Pods, or CPT UI?

Yes. Royal MCP exposes WordPress’s standard wp_get_post_meta, wp_update_post_meta, and wp_delete_post_meta tools, which read and write any custom field — including Advanced Custom Fields (ACF), MetaBox, JetEngine, Pods, CPT UI, and Custom Field Suite. AI agents can populate ACF fields, set repeater rows, update flexible content blocks, and read computed fields just like a human editor working in the WordPress admin.

Does Royal MCP work on WordPress multisite networks?

Yes, on a per-site basis. Each site in a multisite network has its own API key, its own activity log, and its own settings. AI clients connect to a specific site’s MCP endpoint — Royal MCP does not bridge requests between sites in the network.

Does Royal MCP work with WPML, Polylang, or TranslatePress for multilingual content?

Yes. Translated posts appear as separate WordPress posts (each with its own ID and language meta) and are readable or writable via the standard wp_get_posts, wp_create_post, and wp_update_post tools. AI agents can list posts in a specific language by filtering on the language meta key, or translate a post and write the corresponding translation by ID.

Can I limit which posts, pages, or post types AI can access?

Yes. The wp_get_posts and wp_create_post tools accept a post_type parameter and validate it against registered public post types, so private or internal post types are not exposed. Plugin authors can disable specific tools entirely with the royal_mcp_disabled_tools filter, or scope the option-write allowlist with royal_mcp_writable_options. WordPress’s standard capability checks also apply to every tool call.

How do I monitor what AI is doing on my site?

Every authenticated MCP request is logged to the activity log with timestamp, client IP, tool name, parameters (sensitive values redacted), and response status. The log is filterable by time range, client, tool, or status code, and exportable to CSV. The log page refreshes via AJAX so you can watch active sessions in real time.