Protocol

Endpoint

POST /wp-json/ballesdev/mcp (or /?rest_route=/ballesdev/mcp on sites without pretty permalinks). It uses the MCP Streamable HTTP transport without sessions: each POST gets one JSON response. GET and DELETE return 405.

Authentication

The endpoint uses WordPress REST authentication; in practice, an Application Password over HTTP Basic auth. The user needs the edit_pages capability by default (see ballesdev_mcp_capability).

Requests with an Origin header are accepted only from the site’s own origin (scheme, host and port), which blocks browser pages on other sites.

Protocol versions

Version	Methods
2026-07-28	server/discover, tools/list, tools/call
2025-11-25, 2025-06-18	initialize, ping, tools/list, tools/call

The version is chosen per request: the MCP-Protocol-Version header or params._meta. Requests on 2026-07-28 must send MCP-Protocol-Version, Mcp-Method and Mcp-Name headers that match the body. Other versions get error -32022 with the list of supported ones. Batches aren’t supported.

Errors

• A tool that runs but fails (for example content_conflict) returns a result with isError: true and the error code in brackets, so the AI can read it and correct course.
• Protocol problems (an unknown tool or method, invalid parameters) return JSON-RPC errors.
• An unexpected failure inside a tool returns a generic message; the details go to WordPress’s debug.log when WP_DEBUG is on.