Connect with an API key

An API key is a shared secret sent in a header. Calls act as the configured service user, whose WordPress capabilities and the site’s write gates determine access.

Access follows the service user

OAuth scope grants apply to OAuth connections. API key calls can execute supported writes when a service user has the required capabilities and the relevant write gate is open. Schema validation and field allowlists still apply.

Prefer OAuth when each client needs its own scopes and revocation. See Choose an authentication method.

Generate one

1. Open Settings → POM AI → MCP server.
2. In the Credentials card, select Generate / rotate API key.
3. Confirm the prompt, which warns that the existing key will stop working.
4. Copy the key immediately. It is displayed once.

Only the hash is stored. The panel afterwards shows just the last four characters, so a key you did not copy cannot be recovered — generate a new one.

Keys look like pomai_mcp_ followed by a random string.

Configure the client

Send the key in this header:

X-POM-AI-MCP-API-Key: pomai_mcp_…

Most clients expose this as a custom header, often reading the value from an environment variable. Do not send it as Authorization: Bearer — a request carrying both an API key header and a Bearer header is rejected as ambiguous.

The service user

Service user ID in the MCP settings decides which WordPress user API key calls act as.

• Standard transport: without a valid service user, only operations that permit an unauthenticated WordPress actor can run; writes require a configured actor.
• WordPress MCP Adapter: a valid service user with the read capability is required even to initialize the connection.
• With a valid service user: each operation checks that user’s capabilities. Writes also require the relevant open gate.

Choose a user with only the capabilities the integration needs. Keep write gates closed for a read-only integration.

One key per site

There is a single active key per site. Generating a new one replaces the old, which stops working immediately.

On multisite, each site has its own key. A key from one site does not work on another.

Because it is shared rather than per-client, several tools using the same key are indistinguishable in the logs, and revoking affects all of them at once. That is the main operational drawback compared with OAuth.

Rotating and revoking

Generate / rotate API key issues a new key and invalidates the old one. Every client using it stops working until updated.

Revoke API key removes the key entirely with no replacement. API key authentication then fails until a new key is generated.

Rotate when the key may have been exposed — pasted into a ticket, committed to a repository, or held by someone who has left. Both actions are recorded in the MCP log.

Handling the key

• Store it in a password manager or a secrets store, never in a document or a ticket.
• Give it to the client through an environment variable rather than a config file in version control.
• Use HTTPS only; the key travels in a header on every request.
• Rotate it when anyone with access leaves.
• Turn off Enable API key auth entirely if you only use OAuth.

Verify it works

Initialize the MCP connection, then send tools/list using the required transport session headers. The list describes the registered catalog; execution permissions are checked separately. Verify an allowed read and, for a read-only configuration, verify that a write preview is refused.

Then check the MCP settings panel: the recent log should show the call with api_key as the authentication type. If the log shows nothing, the header did not arrive; run the diagnostics, which reports whether the API key header was seen.

When it fails

Next

Connect a client, then make your first read request.