MCP requirements

These requirements describe an independent site connection. Delegated multisite destinations need POM AI active but no local license or MCP setup; the main site owns the authorized connection.

Check these before connecting a client. Most failed MCP setups are a missing prerequisite rather than a client problem.

On the site

Pretty permalinks matter more than people expect. With plain permalinks, /.well-known/oauth-protected-resource and /pom-ai-mcp/oauth/* do not resolve, so discovery and the whole OAuth flow fail while the MCP endpoint itself still answers. Set a permalink structure under Settings → Permalinks first.

You will not have to guess at this. When permalinks are plain, the MCP settings panel shows an error above the endpoint list saying so, and the status endpoint reports permalinks_enabled: false.

Optional products

Tool groups appear only when their product is present:

• POM Theme active — theme settings, content model and template tools.
• WooCommerce active — product, variation, attribute and coupon tools.
• POM Cache active — cache status and purge tools.

A missing product removes its tools from the list rather than causing errors. The status endpoint reports which were detected.

Infrastructure

The server sets Cache-Control: no-store on its responses, and the paths involved must reach WordPress intact.

If a CDN, reverse proxy or WAF sits in front of the site, these paths must not be cached or challenged:

/wp-json/pom-ai-mcp/v1/*
/pom-ai-mcp/oauth/*
/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server

And these request headers must be forwarded rather than stripped:

Authorization
X-POM-AI-MCP-API-Key
Mcp-Session-Id
MCP-Protocol-Version
Content-Type
Accept
Origin
Cookie
Host

Authorization is the one most often stripped, by Apache configurations and by security plugins. When it is, OAuth appears to fail for no reason: the token is sent and never arrives.

The diagnostics in the MCP settings panel report whether the Authorization and API key headers were seen, which settles that question quickly. See Check the server status.

On the client

• An MCP-compatible client that supports Streamable HTTP transport.
• Support for OAuth with PKCE S256, or the ability to send a custom header for API key mode.
• Network access to your site.

The server supports MCP protocol versions 2025-06-18 and 2025-03-26, defaulting to the first. A client asking for anything else is refused with an explicit error.

Decide before you connect

Which authentication method. OAuth acts as the authorizing WordPress user and supports per-client scopes; API keys act as the configured service user and can write when capabilities and gates permit. See Choose an authentication method.

Which WordPress user. With OAuth, the assistant inherits the capabilities of whoever approves the authorization. Approving as an administrator grants administrator reach. Consider a dedicated user with only the capabilities the work needs.

Whether any writes are needed at all. All four write gates are off by default, and read-only is a legitimate permanent configuration.

Where you are doing this. Structural work — content models, templates, theme settings, bulk changes — belongs on staging first.

Before the first write

• Take a backup you can actually restore.
• Enable only the write gate the task needs.
• Confirm the acting user is the one you intended.

See Enabling writes.

Verify readiness

1. Settings → POM AI → AI Tools shows POM AI MCP enabled.
2. The MCP server tab shows the three endpoint URLs.
3. Run diagnostics reports the self-tests as OK.
4. The status endpoint returns JSON in a browser.
5. The detected products match what you expect.

Then continue with Find the MCP server URL.