Authentication

import { Aside } from ‘@astrojs/starlight/components’;

All MCPWP endpoints require an API key — except /openapi.json, which is public so OpenAPI consumers can read the schema without credentials. API keys are the working auth method today. Pass the key one of three ways:

Header (recommended)

X-API-Key: mcpwp_YOUR_KEY

Used by header-capable clients — Claude Code, Cursor, Windsurf, ChatGPT Business MCP, and the manual Claude Desktop config-file method. The key never appears in a URL, so it’s the more secure option whenever your client supports custom headers.

Bearer token

Authorization: Bearer mcpwp_YOUR_KEY

Query parameter (URL-only clients)

https://YOUR-SITE.com/wp-json/mcpwp/v1/mcp?api_key=mcpwp_YOUR_KEY

For MCP clients that only accept a URL and no custom headers — most notably Claude Desktop’s and claude.ai’s “Add custom connector” dialog.

A URL with `?api_key=` embedded is a secret — treat it like a password. It can end up in browser history, shared clipboards, or screenshots. Use a role-scoped key (not `admin`) for connector links, and revoke it immediately if it leaks. Prefer the header method above whenever your client supports it.

OAuth via mumcp.com (requires 3.7.0+)

As of MCPWP 3.7.0, sites can also authenticate claude.ai web and ChatGPT through mumcp.com, a Cloudflare-hosted OAuth 2.1 broker. The site owner enrolls once (WP Admin → MCPWP → Setup → Connect to mumcp.com); end users then connect by signing in — no key to copy — see Sign in (OAuth) for the full flow.

The broker, not each individual site, hosts the OAuth logic (Dynamic Client Registration, consent, token issuance). Your site’s role is to validate tokens the broker issues:

• Every request is checked against the broker via token introspection before it’s honored.
• Tokens are audience-bound — one issued for a given site can’t be replayed against another.
• Tokens are capped at read/write scope. Admin-level actions are not reachable over OAuth; those stay on the API-key path above.
• The site owner can revoke the enrollment at any time (Setup → Disconnect) — this is a local, instant kill-switch, independent of the broker.

Claude Desktop, Claude Code, Cursor, and Windsurf are unaffected by this — they continue to use API keys as described above.

Key format

MCPWP API keys always start with mcpwp_ followed by 48 hex characters:

mcpwp_a1b2c3d4e5f6...

Key scopes

Keys are scoped to a role at creation time. The role determines which tool categories are available.

Role	Tool categories
admin	All categories
editor	content, elementor, gutenberg, media, taxonomy, seo
designer	elementor, gutenberg, media, site
author	content, media, taxonomy

Manage keys

WP Admin → MCPWP → Setup lists active keys and lets you create, rotate, or revoke them.

Via REST:

# List keys
curl https://YOUR-SITE.com/wp-json/mcpwp/v1/api-keys \
  -H "X-API-Key: $ADMIN_KEY"

# Revoke a key
curl -X DELETE https://YOUR-SITE.com/wp-json/mcpwp/v1/api-keys/{id} \
  -H "X-API-Key: $ADMIN_KEY"

Bypass hook

Plugins can bypass API key validation for specific requests:

add_filter('mcpwp_bypass_api_key_check', function($bypass, $request) {
    // Return true to skip validation
    return false;
}, 10, 2);