When to Use API Key Auth Instead of OAuth

Royal MCP supports both OAuth 2.0 (the standard MCP flow) and a simpler static API key. Both give Claude the same level of access; they just differ in how Claude proves who it is on each request.

The API key path is the better choice when:

OAuth fails on your host — SiteGround and similar managed-WordPress hosts block /.well-known/* at the nginx layer, breaking RFC 8414 OAuth discovery. The static-file workaround works for some clients but not all (Claude Desktop / mcp-remote can be picky about Content-Type on those files).
You want a deterministic, scriptable setup — deploying Claude Desktop config across machines via a tool like Ansible / Salt / Configuration Profiles. API key auth is one config file edit; OAuth requires a browser-based consent flow per machine.
You don’t need per-user audit trails — OAuth tokens are issued per user-consent event, which lets you revoke a single Claude installation’s access. API keys are global. If you’ll only ever connect from your own Claude Desktop, this distinction doesn’t matter.

OAuth is still recommended for multi-user agency setups, sites with strict audit requirements, or anywhere you want Claude.ai web (browser-based) connector support. This API key path is specifically for Claude Desktop and other clients that use the mcp-remote bridge.

Security Note

Treat your API key like a password

The Royal MCP API key grants the same level of access as a successful OAuth login: any Claude Desktop instance with the key can read, create, update, and delete content via every enabled MCP tool. Don’t paste it into chat logs, Git repos, screenshots, or shared config files. If you suspect it’s leaked, regenerate it from WP Admin → Royal MCP → Settings (this immediately invalidates the old key) and update your Claude Desktop config.

The key is stored in your WordPress database (the royal_mcp_settings option) and only ever transits as an HTTP request header over HTTPS. It never appears in URLs, query strings, or server access logs.

Setup

Total time: about 2 minutes. You’ll need admin access to the WordPress site and write access to your local Claude Desktop config file.

Get your API key from WordPress

Log into wp-admin on the site you want to connect, then navigate to Royal MCP → Settings. Scroll to the API Key field and copy the value. It’s a 32-character random string. If the field is empty, click Regenerate first.

Make sure the Enable MCP Server toggle at the top of the same page is on. Royal MCP rejects every request when disabled, regardless of which auth method you use.

Locate your Claude Desktop config file

Claude Desktop reads its MCP server list from a JSON file at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

If the file doesn’t exist yet, create it — Claude Desktop will read it on next launch. If it exists with other entries, you’ll be merging into the mcpServers object.

Add the Royal MCP entry

Replace the placeholders below with your actual values:

YOUR-SITE.com → the domain of your WordPress site
YOUR_API_KEY_HERE → the 32-character key from step 1
my-site (the connector name) → whatever you want it to appear as in Claude Desktop’s tool list (lowercase, hyphens, no spaces)

{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-SITE.com/wp-json/royal-mcp/v1/mcp",
        "--header",
        "X-Royal-MCP-API-Key: YOUR_API_KEY_HERE"
      ]
    }
  }
}

Save the file. If you already have other MCP servers configured, merge this entry into your existing mcpServers object — don’t replace the whole file.

Restart Claude Desktop

Quit Claude Desktop completely (don’t just close the window — on macOS use Cmd+Q, on Windows right-click the system tray icon → Quit). Reopen it. The first launch after a config change can take 10–30 seconds while npx downloads mcp-remote on demand — subsequent launches are instant.

Verify the connection

Open any chat in Claude Desktop and click the tools icon (the slider next to the input box). You should see your connector listed by the name you used in step 3, with a list of tools underneath (around 67 tools as of Royal MCP 1.4.14).

For a more direct test, type: “What WordPress site am I connected to?” — Claude will call wp_get_site_info and reply with your site URL, name, and a few other fields. If the call succeeds, you’re connected.

API Key vs OAuth — Quick Comparison

Attribute	API Key	OAuth 2.0
Setup steps	Edit one config file, restart Claude Desktop	Add connector in Claude UI, click Authorize, log into WP, consent
Requires `/.well-known/` reachable	No	Yes (RFC 8414)
Works on SiteGround / managed hosts	Yes — always	Sometimes (depends on nginx config)
Works in Claude.ai web connector	No (web connector is OAuth-only)	Yes
Per-Claude-instance revocation	Regenerate the key (revokes all instances)	Revoke a single token from WP admin
Token expiry / rotation	Manual (regenerate when desired)	Automatic via refresh tokens
Recommended for	Single-user setups, scripted deploys, fallback when OAuth is blocked	Multi-user agencies, audit-heavy environments, Claude.ai web

Troubleshooting

Claude Desktop says “Server failed to start” or doesn’t list the connector at all

The config file isn’t being read, or the JSON is invalid.

Validate your JSON in any online JSON validator. A trailing comma or unquoted key will silently fail.
Confirm the file path matches your OS exactly (the macOS path uses Application Support with a space).
Check Claude Desktop’s log at ~/Library/Logs/Claude/mcp.log (macOS) or %APPDATA%\Claude\logs\mcp.log (Windows) for the actual error.

“npx: command not found” or similar

Node.js isn’t installed on your machine, or it’s installed but not on PATH.

Install Node.js from nodejs.org (any LTS version 18+). The npx command ships with it.
On macOS, if you installed via Homebrew, you may need to restart Claude Desktop (or your shell) so PATH picks up the new install.

Connector loads but every tool call returns “Authentication required”

Royal MCP is rejecting the API key.

The most common cause: the key was copied with leading/trailing whitespace from the WP admin field. Re-copy carefully.
Confirm Royal MCP’s Enable MCP Server toggle is on (Royal MCP → Settings).
If the key looks correct and the toggle is on, regenerate the key in Royal MCP settings, update your Claude Desktop config, and restart Claude Desktop. Sometimes a paste copies a stale value from the clipboard.

Connection works once, then fails after a while

Network or rate-limiting issue, not auth.

Royal MCP rate-limits MCP requests per IP. Heavy bursts (e.g. Claude looping over many tool calls) can trip it. Check WP Admin → Royal MCP → Activity Log for entries around the failure time.
If your host has aggressive WAF rules (Wordfence, iThemes, GuardPress), POSTs to the MCP endpoint might be blocked sporadically. Add /wp-json/royal-mcp/* to the WAF allowlist.

When to Switch Back to OAuth

If your host eventually fixes the underlying issue (for example, SiteGround granting an exception for /.well-known/oauth-*), or you want to add Claude.ai web as a second connection method, switch back to OAuth by removing the "--header" arguments from your Claude Desktop config:

{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR-SITE.com/wp-json/royal-mcp/v1/mcp"]
    }
  }
}

Restart Claude Desktop. mcp-remote will detect the missing auth header, fetch /.well-known/oauth-protected-resource, walk through the standard OAuth flow, and store a token locally. From there it behaves exactly like a Claude.ai web connection.

Still Stuck?

If you’ve worked through the troubleshooting above and Claude Desktop still won’t connect, contact support@royalplugins.com with:

Information We’ll Need

Your operating system (macOS / Windows / Linux) and Node.js version (node --version)
Royal MCP version from WP Admin → Plugins (1.4.14 or newer recommended)
The relevant section of mcp.log — redact the API key before sharing
Output of curl -s -o /dev/null -w "%{http_code}\n" -H "X-Royal-MCP-API-Key: YOUR_KEY" https://YOUR-SITE.com/wp-json/royal-mcp/v1/mcp -X POST -H "Content-Type: application/json" -d '{}' — if this returns 200/202/400, the API key is reaching WordPress correctly and the issue is Claude-Desktop-side. If it returns 401, the key isn’t being accepted

Replies typically within one business day.

Connect Claude Desktop via API Key (Skip OAuth)

The fastest path to a working connector