MCP transport contract

POM AI automatically uses the WordPress Abilities API and its bundled official MCP Adapter on WordPress 6.9+. WordPress 6.8 retains the standard transport. There is no transport toggle and no separately required adapter plugin.

The site-scoped MCP endpoint is:

/wp-json/pom-ai-mcp/v1/mcp

Use the canonical endpoint displayed by the site rather than constructing a cross-site URL in multisite.

Standard transport: HTTP methods

• GET returns readiness and connection metadata for health checks.
• POST accepts JSON-RPC 2.0 messages as a single object or a batch.
• OPTIONS supports the configured cross-origin preflight behavior.
• DELETE does not provide a session-close protocol because the server is stateless.

The transport is request/response HTTP. It does not expose server-sent events or streaming responses.

Standard transport: protocol negotiation

The current server supports MCP protocol versions 2025-06-18 and 2025-03-26; the first is the default. Clients should send the version they implement and use the negotiated protocolVersion returned by initialize. The public pom_ai_mcp_supported_protocol_versions filter can deliberately change the supported set.

initialize advertises tools, resources, and prompts with listChanged: true. Refresh their lists when the client reconnects or receives a reason to expect site capabilities have changed.

Treat the negotiated protocol and advertised capabilities as authoritative. A different MCP implementation can use the same endpoint URL while changing session requirements, supported HTTP methods, or available tools; reconnect and rediscover after an administrator changes the connection implementation.

Notifications whose method starts with notifications/ and has no ID produce no response. Unknown request methods return JSON-RPC method-not-found.

WordPress MCP Adapter transport

Native mode requires WordPress 6.9+. POM AI bundles official MCP Adapter 0.6.1 and uses the shared Jetpack autoloader for coexistence with other integrations. The loaded adapter must remain within >=0.6.1 <0.7.0. It uses the same site URL, OAuth authorization and API key settings. Missing or incompatible dependencies stop native connections without falling back to the standard transport. Update or reinstall the complete POM AI package if its runtime is incomplete.

When initializing native MCP, POM AI disables the adapter’s generic default server and exposes its explicit reviewed catalog. It does not register a generic ability executor or automatically expose third-party abilities. Other integrations can register their own custom servers, with their own authorization policies.

• POST accepts one JSON-RPC message per request. JSON-RPC batches are rejected; domain tools that accept batches still work.
• initialize negotiates a supported protocol (2025-11-25, 2025-06-18 or 2024-11-05) and returns Mcp-Session-Id. Send that session header on subsequent requests.
• GET returns 405 because this transport does not provide an SSE stream.
• DELETE terminates the session. Reinitialize after session expiry or termination.
• Responses must not be cached. Browser clients must use a configured allowed Origin.

The adapter manages protocol negotiation, sessions and tool/resource/prompt serialization. Its advertised capabilities are authoritative; the standard transport’s protocol filter does not change native negotiation. API key connections require a Service user ID with the WordPress read capability. OAuth uses the authorizing WordPress user.

The existing operation names, resource URIs, prompts, write gates and tool-specific successful payloads remain available according to the active products. Native mode additionally offers pom_get_site_context. Clients should use structuredContent when present and inspect isError before using any result. Native mode applies the declared input schemas through WordPress; send actual JSON booleans for dry_run.

Upgrades from the standard transport require clients to reconnect, initialize a session and rediscover the catalog. Existing OAuth credentials retain the same site resource identity. API key integrations on WordPress 6.9+ must configure a valid Service user ID before reconnecting. Saved values of the retired transport toggle do not override automatic selection.

Site context and account catalogs

Native pom_get_site_context includes the canonical site identity and a connection object with actor_user_id, client_id, scopes and auth_type. These describe the current authenticated connection; no credential is returned. A UUID identifies a site but does not grant access.

An account server exposes account routing tools instead of local site administration. Select an explicit connection_id from pom_account_list_sites, discover that destination’s catalog with pom_account_discover_site, and route reads or execution with pom_account_read_site or pom_account_execute_site. Check the outer tool error and the nested remote_result.isError, then any per-step statuses. Destination schemas and permissions remain authoritative. Calls can also return gateway errors before dispatch. An uncertain response is not a reason to replay a write; inspect its destination state first.

Related guides: MCP connection, error contract, and authentication.