Agent Connections

Agents talk to Onumia through a single MCP server that Onumia registers inside WordPress. Connecting an agent is mostly a matter of giving it a WordPress identity to act as, pointing its MCP client at the right URL, and letting Onumia’s capabilities take it from there. Because the agent inherits the roles and permissions of the WordPress user it authenticates as, connecting an agent is as much an exercise in choosing the right user as it is in configuring a client.

The MCP Endpoint

Onumia exposes its MCP server under the WordPress REST namespace at:

/wp-json/onumia/mcp

For a remote agent, give the full site URL so the client knows which WordPress install to reach:

https://example.com/wp-json/onumia/mcp

Authentication

The MCP transport only responds to authenticated WordPress users; an anonymous request gets nothing. Agents authenticate with a WordPress Application Password created for the specific user they should act as. That choice of user is the single most important security decision when connecting an agent, because the user’s WordPress roles determine its effective Onumia capabilities and therefore everything the agent is allowed to do. Match the user to the task: if a job only needs to inspect the site, connect as a user whose roles grant read access and nothing more, and avoid handing out an administrator Application Password when a lower-privilege user would do the work just as well.

Setting Up A Connection

Bringing a new agent online follows a short, repeatable sequence. Start by creating or choosing the WordPress user the agent will represent, and assign it the WordPress role that reflects how much access the task should have. In Onumia Settings, confirm that role’s capabilities are what you intend, adjusting them if the task needs more or less than the defaults provide. Then create an Application Password for that user and configure the agent’s MCP client to connect to the Onumia MCP URL with those credentials. Finally, ask the agent to load Onumia’s resources before it does anything else, so it begins with an accurate picture of the execution model it is working within.

How An Agent Should Work

A well-behaved Onumia session has a predictable shape, and steering an agent toward it produces safer, more reviewable results. The agent should orient itself first by calling load_resources or reading the onumia://context resource, then create a sandbox to work in. With a sandbox selected it runs discovery commands through execute to understand the site, and it confines every change it makes to that sandbox. When the work is ready it generates a preview URL and reports back what changed and what it believes should be promoted. Promotion itself comes last and only on your approval, never as an automatic consequence of having finished the work.

Every Execute Needs A Sandbox

The execute tool requires a sandbox_id on every call, without exception. This is a deliberate constraint rather than an inconvenience: it forces the agent to choose a workspace explicitly before running anything, which rules out ambiguous commands that have no clear target and keeps every action attributable to a specific sandbox. An agent that has not yet created or selected a sandbox simply cannot run commands.

Discovering Available Commands

An agent does not have to guess at what it can run. Inside a sandbox it can ask Onumia and WP-CLI directly for their command lists:

on help
wp help
on help rg

on help lists Onumia’s own commands in the reserved on namespace, wp help lists the WP-CLI commands available on the site, and a more specific request such as on help rg describes a single command in detail. Encouraging an agent to discover commands this way, rather than assuming a fixed vocabulary, keeps it aligned with what the current site and sandbox actually support.

The Context Resource

Onumia publishes a single context resource that every agent should read before it starts working:

onumia://context

This resource lays out the current Onumia execution model, the available tools, how to discover commands, the hard boundaries the agent must respect, and the details of the current authenticated WordPress session. Reading it first means the agent operates from Onumia’s own description of what is possible rather than from assumptions, which reduces wasted commands and avoids attempts to cross boundaries that will only be rejected.

Connecting Agents Safely

The safest connections come from restraint in how you provision them. Prefer a dedicated WordPress user for each agent so its activity is easy to identify and revoke, and grant that user’s role only the Onumia capabilities the task genuinely requires. Be especially conservative with execute_eval, since it is the most powerful command surface, and grant it only when a task truly needs it. Keep preview links private, treating them as the review-only artifacts they are. When you need to understand what an agent has done, the audit logs are the place to look, and for the same reason you should avoid passing secrets through agent commands unless you are comfortable with those values being stored in Onumia’s logs.