Connect an MCP client
The whole setup, in order. Most of it is done by the client; the parts that need you are marked.
Before you start
- POM AI MCP enabled under Settings → POM AI → AI Tools.
- Pretty permalinks configured.
- The site on HTTPS.
- Diagnostics passing. See Check the server status.
Included WordPress integration
Install the complete POM AI plugin package. On WordPress 6.9 or later, POM AI automatically uses the core Abilities API and its bundled official MCP Adapter. You do not need another plugin, Composer, a local WordPress installation or a transport toggle. WordPress 6.8 retains the standard POM transport; account routing and multisite delegation require 6.9+.
Open Settings → POM AI → MCP server, leave Enable OAuth enabled, and save. API key connections on WordPress 6.9+ additionally require an existing Service user ID with the WordPress read capability. OAuth uses the person authorizing the connection and needs no service user or generated MCP API key.
After updating from the standard transport, reconnect your client once so it initializes a session and rediscovers tools. The MCP URL and OAuth credentials retain their identity. The retired transport setting is ignored, including saved disabled values. The settings panel reports the active transport and dependency problems. See the transport contract for sessions and protocol details.
1. Get the server URL
From Settings → POM AI → MCP server, copy the MCP URL:
https://example.com/wp-json/pom-ai-mcp/v1/mcpCopy it rather than typing it — it doubles as the OAuth resource identifier and is compared exactly. See Find the MCP server URL.
2. Add the server to the client
In the client's custom MCP server form:
| Field | Value |
|---|---|
| Name | Something identifying the site |
| Transport | Streamable HTTP |
| URL | The MCP URL |
| Bearer token | Leave empty for OAuth |
| Headers | Leave empty for OAuth |
For API key mode instead, set a header X-POM-AI-MCP-API-Key to your key, ideally from an environment variable. Never configure both a Bearer token and an API key — a request carrying both is rejected.
3. Let it discover and register
On first connection the client receives a 401 pointing at the protected resource metadata, follows it to the authorization server metadata, and registers itself. No action from you.
If the flow never starts, the discovery URLs are probably 404ing because permalinks are not configured.
4. Approve the authorization — your step
The client opens the authorization page. If you are not logged in, WordPress asks you to log in first.
Log in as the user whose capabilities the assistant should have. This is the decision that matters most in the whole setup. An administrator approval gives administrator reach; a dedicated limited user gives limited reach.
Read the scopes on the consent screen, then approve. See The authorization endpoint and OAuth scopes.
5. Confirm the connection
The client should now list the tools. Check two things:
- In the client: the tool list is populated. Its size reflects the active products and transport. Discovery is not permission to execute every listed operation.
- In WordPress: the MCP settings panel's recent log shows the authorization and MCP discovery call, with the acting user.
If the client shows no tools, check its connection errors, the selected transport and required dependencies before reconnecting.
6. Read before you write
Ask the assistant for something harmless — how many published posts there are, or the details of one page by ID. See Make your first read request.
Only then consider enabling a write gate. All four are off by default and that is the right starting state. See Enabling writes.
Multisite
For one main-site connection that manages network pages, follow Manage multisite pages. Delegated subsites need only POM AI active; do not configure a local license, MCP key or OAuth connection for delegation.
For a subsite with its own direct connection, activate POM AI there, save its own domain-authorized license under Settings → POM AI → License, enable POM AI MCP, and follow the steps above using that subsite's displayed URL. Authorize with that subsite's intended WordPress user. Its connection never inherits the main site's network grant. A standalone installation follows these same steps with its own license and URL.
An eligible POM AI Unlimited account can instead provide one account connection for explicitly enrolled websites, including independent installations and multisite subsites. In My Account → POM AI Management → AI site connections, connect each website and approve its WordPress OAuth consent. Every destination requires native adapter mode, OAuth and an already authorized license domain. Configure the displayed Account MCP URL once in the agent using OAuth. Ask it to list sites and select the intended domain before reading or writing.
Account discovery and reading require mcp:read plus account:sites:read. Execution additionally requires mcp:write, account:sites:execute, a write-enabled site connection and the destination’s own capabilities/write gates. This account grant also covers websites you enroll later; it never grants administration of the account website. A domain appearing on your license alone does not connect it.
Check the Blog ID line on the settings panel to confirm which site you are configuring.
Multilingual sites
Configure the canonical URL shown on the settings screen. When POM Translate prefixes URLs with a language code, the server also accepts localized OAuth and discovery paths, so a redirect through a translated URL does not break the flow.
When it does not connect
| Symptom | Check |
|---|---|
| Client cannot reach the server | The URL, HTTPS, and that the status endpoint returns JSON |
| OAuth flow never starts | Pretty permalinks |
| Authorization completes, calls still 401 | Whether the Authorization header survives — the diagnostics report this |
invalid_resource |
The configured URL against the settings screen, character by character |
invalid_client after it previously worked |
Someone used Reset OAuth; reconnect |
| Rate limited during setup | Registration and token requests allow 5 per minute; wait |
| Tools list is empty | Transport dependencies, connection errors and whether the products are active |
| HTML instead of JSON | A security plugin, WAF or cache intercepting the paths |
Run the diagnostics before investigating the client; it answers most of these directly.
Disconnecting
- Reset OAuth revokes every client and token for the site at once.
- Revoke API key stops API key access.
- Disabling the POM AI MCP tool removes the server entirely.
Reset OAuth remains all-or-nothing. A protocol client can revoke its individual grant using the advertised revocation endpoint. For an account-enrolled website, Disconnect in AI site connections removes that website from the account and requests revocation of its site grant while other website connections remain available. If the site cannot confirm revocation, the account reports this explicitly. An operation already dispatched may still finish.