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.

Background execution

Catalog tools, resource reads and prompt generation execute through WordPress scheduled events. Submitting a task and reading its status with pom_get_task are synchronous: the HTTP request returns after saving or reading the receipt, without waiting for cron. Authentication, protocol negotiation, catalog discovery and site identity also remain short HTTP requests.

Each destination site can have one next task ready for its cron runner, while later tasks for that site wait. The configured runner determines when a ready task starts. Only one heavy operation executes at a time across the installation. Recovery restores missing events, and new submissions do not postpone recovery that is already due.

Site and network discovery advertise contract_version: 3 for this asynchronous result contract. Reconnect and refresh discovery when updating an integration that previously expected immediate operation results.

A tool submission returns a receipt with task_id, status, phase, terminal, blog_id, created_at, started_at and expires_at. Pending receipts include poll_after_seconds, and submission identifies poll_tool: pom_get_task. Call pom_get_task with the same task_id on the same authenticated connection after the indicated delay. For network tasks, keep polling through the originating main-site connection.

Use the delay from each pending receipt, which increases from five to thirty seconds as a task ages. Repeat status reads while terminal is false; stop automatic polling when it is true. created_at identifies submission time, and started_at is populated when execution starts. The phase explains progress without changing the established status values.

A slow operation remains running while its worker is active. Elapsed time alone does not make a task terminal; keep following its polling delay until completion or a confirmed failure is reported.

A completed task returns the original operation response in result. Network operation results retain their inner blog_id, isError and result; inspect the inner error even when the outer task completed. A completed preparation task can contain a pending write review, which still requires user approval.

Never resubmit a queued or running operation to check progress, and never automatically replay an uncertain write. A queued task has one hour to start. Once it finishes, its result is retained for up to one hour from completion. When receipt or storage capacity is needed for new work, the oldest terminal receipts can be removed sooner; queued and running tasks are never removed to make room. Save results when received.

expires_at is the latest retention deadline for a terminal receipt, the start deadline for a queued task, and null while running. Terminal receipts include a retention reminder. If the receipt is missing or has expired, inspect the destination before another write: losing the receipt does not prove that the operation never ran.

The built-in post tools read and write through WordPress functions; they do not send HTTP requests to /wp-json/wp/v2/posts or open pages in a browser. Reading their task status with pom_get_task does not repeat the post operation. Separately opening a page in a browser can trigger that page's normal analytics, including visits from browser-based previews.

Resource reads return the receipt as JSON text in the resource envelope. Prompt requests return it as a text message. Poll pom_get_task to retrieve the complete original resource or prompt response. MCP clients must follow this asynchronous workflow.

Standard transport: HTTP methods

• GET returns readiness and connection metadata for health checks.
• POST accepts JSON-RPC 2.0 messages as a single object. JSON-RPC batches are rejected.
• OPTIONS supports the configured cross-origin preflight behavior.
• DELETE clears the optional form-elicitation session when one was negotiated.

The transport normally uses request/response HTTP. Compatible clients advertising form elicitation and accepting text/event-stream can receive a short POST stream containing a review dialog request and the pending tool result. The stream closes immediately; the authenticated response POST records the user’s decision. Use the returned web review link if the client cannot complete this exchange.

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.

Admission limits

Both transports accept one JSON-RPC message per request, up to 1 MiB. Task submissions and status reads have separate per-minute quotas and can proceed while a heavy task runs. Public requests do not take the shared heavy worker; queue admission remains bounded and heavy execution remains serialized. A refused submission returns a quota or queue-admission error without starting its operation. Check tool errors as well as HTTP status. See MCP rate limiting for exact limits and retry behavior.

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.