Connecting Royal MCP to Claude

First — Install and Enable Royal MCP

Before connecting anything to Claude, Royal MCP needs to be running on your WordPress site. Three small steps:

Choose Your Surface

Pick where you’ll be using Claude. The setup steps differ by surface, but the underlying connection is the same Royal MCP server in all three cases.

claude.ai (Browser) and Claude Desktop — Identical Setup

Anthropic has unified the connector flow across claude.ai in the browser and the Claude Desktop app. The UI is identical, the steps are identical, and the OAuth handshake is identical. Whichever you use, follow the same instructions below.

The first time you connect, you’ll see the OAuth consent screen. Every time after that — on the same Claude account — Claude reconnects silently in the background, no consent prompt, no extra clicks. The two videos below cover both cases.

First-time setup — OAuth consent flow

This is what you’ll see the first time you add Royal MCP to a fresh Claude account: paste the URL, click Connect, approve the one-time consent screen.

Open Settings → Connectors in Claude

In claude.ai (browser): click your profile in the bottom-left → Settings → Connectors. In Claude Desktop: Settings (gear icon) → Connectors. Both land on the same screen.

Click “Add custom connector”

At the top of the Connectors list, click Add custom connector. A small panel opens asking for a name and a URL.

Paste your MCP server URL

Name it whatever you like (e.g. My Site MCP). For the URL, paste your WordPress site’s MCP endpoint:

https://example.com/wp-json/royal-mcp/v1/mcp

Leave the Advanced Settings (Client ID / Client Secret) completely empty. That signals Claude to use auto Dynamic Client Registration, which is the recommended path.

Click Connect — approve consent

Claude opens the OAuth consent screen from your WordPress site. You’ll see your site name and the requested scope (mcp:full). Click Authorize. Claude exchanges the code for a token, stores it, and marks the connector as Connected.

Verify in a new chat

Open a new conversation. Click the + button next to the input box → Connectors and confirm your Royal MCP connector toggle is on. Then ask Claude: “Do we have an open connector to example.com?” (replace with your actual site). Claude will call wp_get_site_info against that specific connector and reply with the site’s URL and name. Anchoring on your specific domain is better than a generic “list my recent posts” — if you have multiple sites connected, the generic question will list every connector or pick one ambiguously.

Claude → + button → Connectors. Toggle Royal MCP on per-conversation. Same flow in claude.ai web and Claude Desktop.

Coming back later — silent reconnect

Once you’ve completed the consent screen once, Claude stores the OAuth token. Every subsequent reconnect on the same Claude account skips the consent step entirely — you click the connector, it goes Connected, you’re back in business. This is what you’ll see day-to-day.

Fallback: connect via API key (when OAuth is blocked by your host)

The OAuth flow above works for the vast majority of customers. The exception is hosts that block Anthropic’s OAuth backend — usually Cloudflare Bot Fight blocking python-httpx, cPanel ModSecurity returning 406, Imunify360 returning 429, or a managed-host WAF. In those cases the OAuth dance fails at the server-to-server token exchange and you need a different path.

Copy your API key from WordPress

Go to WP Admin → Royal MCP → Settings → General Settings. The WordPress API Key field has the key pre-generated and visible — click Copy. If you want a fresh key (or the field is empty), click Regenerate first; that immediately invalidates the old one. Also confirm the Enable Royal MCP Integration toggle is on.

WP Admin → Royal MCP → Settings → General Settings. Copy the WordPress API Key value, or click Regenerate for a fresh one.

Add the connector with API key auth

In Claude (browser or Desktop), open Settings → Connectors → Add custom connector. Paste your MCP server URL (same as the OAuth path). In the Advanced / Authentication section, choose API Key (or paste it into the Custom Headers field as Authorization: Bearer your-api-key, substituting your actual 32-character key from step 1, depending on which version of the Claude UI you’re on).

Click Connect — no consent screen

Because you’re using an API key, there’s no OAuth dance, no consent prompt, no browser redirect. Claude tests the key against your MCP endpoint and marks the connector Connected.

Verify in a new chat

Same as the OAuth path — open a new conversation, enable the connector, ask Claude to do something WordPress-related.

Claude Code (Terminal / CLI)

Claude Code is the official Anthropic CLI that runs in your terminal, VS Code, or JetBrains IDE. Connecting Royal MCP to it is a single command. No browser config, no Settings UI — everything happens at the command line.

With OAuth (recommended)

Add the Royal MCP server as a connector with one command. Claude Code will pop open your default browser for the one-time OAuth consent, then store the token in your local config for future sessions.

claude mcp add --transport http royal-mcp https://example.com/wp-json/royal-mcp/v1/mcp

Replace example.com with your actual WordPress site. Then start a Claude Code session, and on the first MCP call your browser will open with the OAuth consent screen. Click Authorize. The terminal session receives the token and the connector becomes active.

Without OAuth — API key path

Same as the browser case — use this when OAuth is blocked by your host. Copy your API key from WP Admin → Royal MCP → Settings → General Settings → WordPress API Key, then pass it via the --header flag:

claude mcp add --transport http royal-mcp https://example.com/wp-json/royal-mcp/v1/mcp \
    --header "Authorization: Bearer your-api-key-here"

No browser, no consent screen, no OAuth state. Claude Code attaches the header to every request.

Verify your connection with /mcp

Inside any Claude Code session, type /mcp and press Enter. You’ll see the Manage MCP servers screen — every connector you have registered, grouped by scope (Project MCPs, User MCPs, claude.ai), with each one showing its connection state and tool count.

Claude Code /mcp output: every registered connector with status, grouped by scope.

Use the up/down arrow keys to navigate. Each connector shows one of these states:

• ✓ connected — working; tool count is shown next to the status
• ▵ needs authentication — OAuth token is stale, expired, or was never completed
• × failed — the server didn’t respond or returned an error; run claude --debug to see logs

Hover over any connector (green ✓ or red × or yellow ▵) and press Enter to get connector-specific options like Authenticate or Disable. Esc backs out at any level.

If you prefer a non-interactive view, you can also list servers from the shell:

claude mcp list

Re-authenticate a stale connector

When a connector shows ▵ needs authentication or × not authenticated, you don’t need to remove and re-add it. Just refresh the OAuth token in place:

1. Run /mcp in any Claude Code session.
2. Arrow down to the affected connector and press Enter.
3. You’ll see the connector detail screen with Status, Auth state, URL, Config location, and options:

Per-connector options when a connector needs re-authentication. Arrow down to Authenticate and press Enter.

4. Select Authenticate and press Enter.
5. Claude Code opens your default browser for the OAuth consent screen — same flow as the initial setup. Click Authorize.
6. The terminal receives the fresh token and the connector flips back to ✓ connected.

After You Connect — First Things to Try

Royal MCP exposes the full WordPress data model to Claude: posts, pages, media, users, comments, taxonomies, WooCommerce products and orders (if WooCommerce is active), plus the Royal Plugins-specific tools (GuardPress security data, SiteVault backups, ForgeCache controls, etc.) for any premium plugins you have installed.

Try a few of these in your first conversation. Anchor each prompt with your site domain — if you have multiple sites connected, this tells Claude exactly which connector to use:

• “On example.com, show me my five most recent posts and their categories.”
• “On example.com, create a draft post titled ‘Notes from today’ with this content: [paste].”
• “Which pages on example.com have the most internal links pointing at them?”
• “Search example.com’s media library for images of [topic] uploaded this year.”
• “What plugins are installed on example.com and which ones have updates available?”

If a request fails, the first place to look is WP Admin → Royal MCP → Activity Log. Every Claude request lands there with the exact tool name, parameters, and result — that’s your single source of truth for what happened on the server.

If Something Goes Wrong

If a connector won’t connect or a tool keeps failing, work through this short list before opening a support thread:

1. Run the Step 0 30-second edge probe. Almost every “Claude won’t connect” issue traces back to your hosting edge (Cloudflare, managed-host WAF, ModSecurity, SiteGround nginx). Step 0 tells you in 30 seconds whether the problem is your host or your plugin.
2. Check your Activity Log. If you see oauth:authorize rows but no oauth:token, the token exchange is failing — usually a host blocking python-httpx. If you see nothing at all, the request isn’t reaching WordPress.
3. Confirm plugin version. The latest Royal MCP includes fixes for several common setup issues. Check Plugins → Updates for a newer version before troubleshooting further.
4. Restart your Claude surface. Stale OAuth tokens are the second-most-common cause of “suddenly stopped working.” Sign out of claude.ai / quit Claude Desktop / restart your terminal session, then reconnect.

For deeper diagnostics including curl probes you can run yourself, see the curl deep-dive guide.

Still Stuck? Two Support Paths

If you’ve worked through the checklist and your connection still fails:

Community Support (free) — wp.org Plugin Forum

Post a new thread at wordpress.org/support/plugin/royal-mcp/. The Royal Plugins team monitors the forum regularly. Include the diagnostic info below.

Premium Support (paid) — direct one-on-one help

For priority response (24-hour SLA) and hands-on diagnostic help, our Premium Support tier is $149/year. Direct email, full refund if we can’t resolve your issue.