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.

Access tokens last one hour. Refresh credentials have a sliding 30-day lifetime. If a refresh response is lost, the client can retry the same refresh request within 30 seconds to recover the same issued pair. This recovery does not extend its lifetime and stops working after another rotation or revocation. Transient renewal storage failures return HTTP 503 instead of asking the client to discard a valid authorization. Token renewal preserves active work sessions, but does not extend their separately approved duration.

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.