Registering a WordPress Ability solves one part of the problem: it defines a unit of functionality with a name, description, input and output schemas, an execution callback, and a permission check. It does not automatically turn that Ability into a WebMCP tool that a browser agent can discover on the outer WordPress Playground page. They are two registries and two different exposure paths.
In Playground, the distinction is easier to see because WordPress runs through a chain of iframes. The agent observes the top-level page, while a plugin tool is registered in the inner WordPress document. Playground’s built-in WebMCP proxy exists to carry the tool description out of the iframe and route the call back in when the agent decides to execute it. The implementation was merged into the project on September 3, 2026, and the Playground team published its explanation of the flow on September 5.
Ability, tool, and proxy are three different pieces
| Piece | Where it lives | What it describes | How it reaches the agent |
|---|---|---|---|
| WordPress Ability | The WordPress Abilities API registry | A reusable capability with schema, execution, and permissions | Through internal PHP or, when exposed, the Abilities REST API and other adapters |
| WebMCP tool | The web document’s document.modelContext | An action the browser can present to agents, with a name, description, input schema, and execution function | Through WebMCP discovery in the page context |
| Playground proxy | The outer page, Playground client, and frame bridge | Mirrors tools registered inside WordPress and forwards calls | Re-registers those tools on the page the agent can observe |
The practical consequence is straightforward: an Ability can be the business implementation behind a tool, but it is not the tool itself. Playground’s official article explicitly states that registering an Ability alone does not automatically make it appear through the WebMCP proxy.
The request → proxy → iframe → plugin path
- The plugin registers a WebMCP tool inside WordPress. The inner document now has a tool descriptor with a name, description, and input schema, plus the function that will execute it.
- The iframe bridge detects the tool list. Playground’s implementation tracks registrations, removals, and navigation changes in the WordPress document.
- The proxy advertises those tools again on the outer page. This top-level page is what the browser agent can inspect to discover available tools.
- The agent sends the tool arguments. The call moves through the Playground client and the bridge between frames.
- Execution happens in the WordPress document. The plugin runs the local logic and the result travels back along the same path to the agent.
The pull request describes the conceptual flow as: agent → Playground page WebMCP context → Playground client → remote frame → WordPress document → plugin execution. This is why the proxy is more than a networking detail: it solves a discovery and lifecycle boundary between documents.
Conceptual example: the same action in two layers
Imagine an events plugin that needs to create a draft. In the Abilities API, it could register something like my-plugin/create-event, define an input containing a title and date, validate the output, and use a permission_callback to require that the current user can edit content.
If the goal is for a browser agent to see a “Create event draft” action among Playground’s Site tools, the plugin still needs a WebMCP tool. That tool can be thin: it accepts the same arguments, calls the Ability, and returns the result. This design keeps business rules, validation, and permissions centralized in the Ability while the WebMCP layer handles discovery and the agent-facing contract.
Put another way, the Ability answers “what WordPress knows how to do and under which rules”; the tool answers “how this action is offered to the agent in this web document.”
The public flag does not remove the need for a WebMCP tool
In WordPress 7.1, the Abilities API documentation uses the high-level public metadata flag to indicate that an Ability is intended for external clients such as REST, MCP, or AI agents. That signal seeds defaults for individual channels; for REST, for example, it affects show_in_rest. It still does not by itself create a registration in document.modelContext inside Playground.
HTTP consumption uses a different path. Abilities exposed through the REST API appear under /wp-json/wp-abilities/v1/ and can be discovered and executed through dedicated endpoints. The official documentation also states that these endpoints require an authenticated user and that execution remains subject to the Ability’s permission_callback.
Inside Playground, an agent can use the existing playground_request tool to make requests to WordPress and, through that route, discover or execute an Ability that is exposed through the REST API. This is different from the Ability appearing directly as a named WebMCP tool that the agent discovers on the page.
When to use a WebMCP tool and when to use the Abilities REST API
| Need | Most direct path | Why |
|---|---|---|
| The action should appear as an explicit tool to the agent working in Playground | WebMCP tool, potentially wrapping an Ability | Provides native page-context discovery and an agent-specific interface |
| The same capability must serve HTTP integrations, automation, or clients outside the browser | Ability exposed through the REST API | Provides a stable endpoint, authentication, and execution independent of a WebMCP session |
| You already have a well-defined Ability and want to expose it as a Site tool too | Thin WebMCP wrapper around the Ability | Avoids duplicating business logic and separates transport from implementation |
| The agent only needs generic access to an exposed Ability | playground_request + Abilities REST API | A dedicated tool is unnecessary when a generic request is enough |
This last route is especially useful for experimentation or administrative capabilities that were already designed as an API. A dedicated tool becomes more valuable when its name, description, and schema need to guide the agent’s choice clearly, or when the action should be part of the browser’s Site tools experience.
Current limits that affect the design
- WebMCP is still an incubating specification. The Web Machine Learning Community Group report published on September 15, 2026 still states that WebMCP is not a W3C Standard and is not on the Standards Track. Implementations and API names can still evolve.
- Browser or agent-environment support is required. The proxy can cross the iframe boundary, but final discovery still depends on a WebMCP implementation the agent can use.
- Tools belong to the document that registered them. In Playground’s proxy, navigation starts with a fresh list; the system tracks late registrations and withdraws tools that no longer exist.
- Not every WordPress route produces a document with tools. The proxy pull request names REST responses, static files, and admin-ajax.php as examples that do not advertise tools. The login screen is also not covered by the default flow at present.
- Reserved names matter. A plugin tool colliding with an internal playground_* tool is skipped by the proxy so it cannot replace a Playground action.
- Exposure does not replace authorization. The Ability should still protect execution with appropriate permission rules. Making something public for discovery should not be treated as authorization for every operation.
Checklist for a plugin that wants to work with agents
- Model the core action as an Ability when it makes sense as a reusable WordPress capability.
- Define input and output schemas and keep permission checks in the business layer.
- Decide whether the capability needs REST; if it does, configure exposure according to the WordPress version and desired channel.
- If the action should appear directly to the agent in Playground, register a WebMCP tool that maps to the Ability or equivalent logic.
- Test navigation, wp-admin, and public pages separately because tool lifecycle follows the active document.
- Treat the proxy as part of the discovery architecture: it advertises outward, forwards inward, and withdraws tools when the context changes.
