MCP authentication fails
Authentication errors occur before tool authorization. Match the public code to the connection problem.
| Error code | Action |
|---|---|
pom_ai_mcp_missing_auth |
Configure one supported credential. |
pom_ai_mcp_ambiguous_auth |
Send OAuth Bearer or API key, never both. |
pom_ai_mcp_oauth_disabled |
Enable OAuth or use the approved read-only API-key profile. |
pom_ai_mcp_invalid_token |
Refresh or reconnect; the access token is invalid, expired, or revoked. |
pom_ai_mcp_api_key_disabled |
Enable API-key auth before using that profile. |
pom_ai_mcp_invalid_api_key |
Generate or copy the current key again. |
OAuth checks
Verify the canonical MCP resource URL, client registration, redirect URI, PKCE exchange, token expiration, and requested scopes. Pretty permalinks are needed for rewrite-dependent discovery and OAuth endpoints.
The MCP resource uses the site's configured address, including its HTTP or HTTPS scheme, both in browser requests and background execution. Use the same canonical endpoint in the client. Changing the site's address requires reconnecting against the new resource.
Access tokens last one hour; clients should renew them silently. Each renewal gives the refresh token another 30-day window. A lost refresh response can be recovered by repeating the same request within 30 seconds, provided that pair has not been superseded or revoked. Normal token renewal keeps the same authorization for pending tasks, work sessions and their results. Revocation, changed permissions or an expired authorization still stop access. If a queued operation reports pom_ai_mcp_task_access or pom_ai_mcp_network_grant_denied, check the connection's current authorization and, for delegated work, its network scopes and super-administrator access. A rejected background authorization is not a request to approve the proposed content again.
Tasks and reviews created with an earlier authorization binding may become unavailable after updating. Inspect the destination before requesting a fresh preview for any confirmed remaining changes. Do not replay a write whose outcome is unknown.
API-key checks
Use the exact MCP API-key header expected by the client configuration. A key is shown only when generated; stored keys are hashed. The optional service user affects permitted reads but does not make API-key authentication writable.
Never test credentials by placing them in the JSON-RPC body. If a key or token was exposed while debugging, revoke or rotate it after restoring the connection.
Related guides: MCP authentication contract, connect a client, and client cannot connect.