Royal MCP API Keys — Universal Reference

Every Royal MCP install ships with a WordPress API key that authenticates any MCP client to your site. Same key works with Claude Desktop, ChatGPT, Cursor, VS Code, Windsurf, Claude Code, Zed, LM Studio, and any other AI IDE or CLI that supports the Model Context Protocol. This page covers where to find it, how to send it, when to use it instead of OAuth, and how to rotate it safely.

What the WordPress API key is

The WordPress API key is a long random token generated by Royal MCP when you activate the plugin. It authenticates HTTP requests from any AI client to your WordPress site’s MCP endpoint at /wp-json/royal-mcp/v1/mcp. The key belongs to the WordPress user who generated it, so every tool call runs with that user’s WordPress capabilities.

Two authentication paths exist for Royal MCP. Both work with the same tools; the choice comes down to which your client prefers:

OAuth 2.0 (recommended for Claude Desktop and any browser-based flow) — the client negotiates a short-lived access token on demand. No manual key handling required. Automatic per-user consent.
API key (this page) — a static token sent as an HTTP Authorization header. Works with every MCP client, including those that don’t implement OAuth, and every stdio-only client via the mcp-remote bridge.

Finding your API key

Open wp-admin

Log into your WordPress site as an administrator.

Go to Royal MCP settings

Left sidebar → Royal MCP. The API key section is on the settings screen alongside other authentication options.

Copy the key

Click the show/copy control next to your key. Store it in a password manager the moment you copy it. This is the last time you’ll see the full key in that session; navigating away masks it again.

How to send the API key in a request

The API key goes in the HTTP Authorization header using the Bearer scheme:

Authorization: Bearer <your-api-key>

Every MCP client accepts this pattern, though the JSON config shape varies. The three common formats:

Standard MCP config (Claude Desktop, LM Studio, most native clients)

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

Cursor / VS Code / Windsurf MCP settings

Same three values, entered through the client’s Settings UI: URL, header name (Authorization), header value (Bearer <your-api-key>).

Stdio-only clients via mcp-remote bridge

For clients that only support stdio transport, the mcp-remote npm bridge converts HTTP to stdio. Note the no space after the first colon in the --header argument:

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

mcp-remote splits its --header argument on the first colon, so a space after that colon breaks the parse. The actual HTTP request still goes out with the standard Authorization: Bearer VALUE spacing.

Direct HTTP testing (curl / Postman / Bruno)

curl https://yoursite.com/wp-json/royal-mcp/v1/mcp \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

API key vs OAuth: when to use which

Use API key when…	Use OAuth when…
Client doesn’t implement OAuth (LM Studio, older Continue, some stdio-only IDEs)	Client offers “Add connector” or OAuth flow (Claude Desktop, Claude.ai Web)
Host blocks the OAuth discovery endpoint and won’t stop (aggressive WAF, hardened managed hosting)	You want per-session tokens without embedding secrets in a config file
Machine-to-machine testing, CI pipelines, curl scripts	Multiple people share the site and each should authenticate as themselves
You want a single stable token that survives client reinstalls	You want automatic token rotation and expiry

Rotating and revoking keys

The Royal MCP settings screen has a Regenerate button next to the API key. Clicking it:

Generates a fresh random key and stores it.
Invalidates the previous key immediately.
Every client using the old key gets 401 Unauthorized on the next request.

Rotate on a regular cadence (every 90 days is a common rhythm), and always rotate if you suspect the key leaked: pasted into a public chat, committed to a git repo, or logged by a client with verbose debug output.

Regeneration is not undo

Regenerating the key doesn’t just invalidate whoever leaked it. It invalidates every client using it, including your own. Have the new key ready to paste back into each client before you press the button.

Security considerations

Treat the key like a password. Anyone with it can invoke any Royal MCP tool as the user that generated it, up to that user’s WordPress capabilities.
Store in a password manager or the client’s secure storage. Never in a git repo, never in a public gist, never pasted into a chat.
Prefer HTTPS. The Authorization header is only as safe as the transport. Every MCP client uses HTTPS by default, and Royal MCP requires it in production.
Scope with WordPress capabilities. If you don’t want an AI client to delete posts, generate the key from a user account that lacks delete_posts. WordPress’s standard capability checks apply on every tool call.
Rotate after any suspected exposure. A leaked key is a full-site backdoor for the user it was generated for.

Troubleshooting authentication failures

401 Unauthorized: key is wrong, expired (regenerated on WP side), or the user was deleted. Copy a fresh key from wp-admin.
403 Forbidden: key valid, but the underlying WordPress user lacks capability for the tool being called. Grant the missing role, or generate the key from a user that already has it.
404 on /wp-json/royal-mcp/v1/mcp: WordPress pretty permalinks are set to Plain. Change to Post Name (or anything else) and flush rewrite rules.
Client not passing header: run curl -v against the endpoint to confirm the header goes out as expected. See the diagnose-with-curl guide linked below.