MCP authentication

POM AI accepts one authentication mechanism per request: OAuth Bearer or the MCP API key header. Sending both returns pom_ai_mcp_ambiguous_auth.

OAuth

OAuth with PKCE is the normal interactive connection. The access token is bound to:

• a WordPress user;
• a client ID;
• approved scopes;
• the canonical MCP resource;
• an expiration and revocation state.

The server sets that WordPress user as the actor for capability checks. Disabled OAuth returns pom_ai_mcp_oauth_disabled; an invalid or expired token returns pom_ai_mcp_invalid_token.

Token exchanges preserve the registered redirect URI through WordPress login and validate PKCE before issuing credentials. An exchange competing with client revocation can return HTTP 503 with temporarily_unavailable; retry the exchange only while its authorization remains valid. An already consumed authorization code requires a new authorization flow. A revoked refresh credential returns invalid_grant and requires fresh consent.

MCP API key

The administrator can enable API key authentication, generate a key, and optionally map it to a service user. The key is stored as a password hash; only its last characters are displayed after creation.

API key calls use the mapped service user’s WordPress capabilities. OAuth scope grants apply to OAuth connections; they do not make API key calls read-only. Supported writes require a configured actor, the relevant open gate and accepted arguments. WordPress MCP Adapter also requires the actor to hold read when initializing the connection. The standard transport permits some reads without a service user.

Disabled or invalid keys return pom_ai_mcp_api_key_disabled or pom_ai_mcp_invalid_api_key. Missing credentials return pom_ai_mcp_missing_auth.

Use TLS, store tokens in the client’s secret storage, never put them in prompt text, and revoke credentials when a client is no longer trusted.

Related guides: connect an MCP client, authentication troubleshooting, and authorization.