MCP Tools

Onumia exposes a custom MCP server that agents connect to over WordPress Application Passwords. The server publishes a small, deliberate set of tools for working with sandboxes and never exposes a raw host shell. Each tool maps to a single, well-defined action, and every call is governed by your WordPress role capabilities and recorded in Onumia’s audit log.

The server is mounted through the WordPress MCP Adapter at a single endpoint:

/wp-json/onumia/mcp

Access to the transport requires an authenticated WordPress user. From there, what each tool will actually let you do is decided by your effective Onumia capabilities, so connecting and being authorized to act are two distinct steps.

The Tool Surface

The tools fall into three groups. A small core handles the sandbox lifecycle, one tool runs commands, and a set of database merge tools handle selective promotion of sandbox database changes. Everything an agent does flows through these.

Tool	Purpose
create_sandbox	Create an isolated sandbox for a task.
execute	Run one command inside an existing sandbox.
preview_sandbox	Mint a fresh browser preview URL for an active sandbox.
promote_sandbox	Promote code, and optionally database changes, toward live.
discard_sandbox	Discard a sandbox and invalidate its preview state.
load_resources	Load Onumia MCP context resources.
scan_database_merge	Compute the current disposable database merge scan.
update_database_merge_selection	Replace the staged change group selection.
preflight_database_merge	Validate the selection and build a rollback preview.
apply_database_merge	Apply staged database changes to live with guards.
rollback_database_merge	Roll back a prior database merge operation.

create_sandbox

This is where work begins. create_sandbox provisions a fresh, isolated workspace for a task and returns the identifier you pass to every other tool. Both inputs are optional: label attaches a human-readable description so the sandbox is easy to recognize later, and ttl sets a lifetime in seconds.

Field	Required	Notes
label	No	Human-readable task label.
ttl	No	Lifetime in seconds.

Creating a sandbox requires an authenticated user with the create_sandbox capability. The response carries the new sandbox_id, the sandbox status, your effective capabilities, a preview_url, and a created_at timestamp.

execute

execute runs exactly one command inside a sandbox using Onumia’s pure-PHP bash runtime. It is the workhorse of the toolset, and it is the only tool whose required capability changes based on what you ask it to do.

Field	Required	Notes
command	Yes	Command string interpreted by Onumia’s PHP bash runtime.
sandbox_id	Yes	The sandbox to run in.
cwd	No	Virtual working directory, defaults to /.

Access to the target sandbox is always required. Beyond that, every command needs execute_read, commands that write the sandbox filesystem or database additionally need execute_write, and wp eval or wp eval-file need execute_eval. The tool classifies the command first and enforces the matching capability before running anything; the command runtime documentation describes that model in full.

The response is structured: it returns the sandbox_id, your capabilities, the command classification, the resolved cwd, and the command’s stdout, stderr, and integer exit_code. Surface meaningful stderr and non-zero exit codes rather than discarding them.

preview_sandbox

preview_sandbox mints a fresh browser preview URL for an active sandbox. It takes only the sandbox_id and requires access to that sandbox, returning the sandbox_id and a new preview_url. A preview lets a human see the sandbox state in a browser; it grants no command, promotion, or admin rights on its own.

Field	Required
sandbox_id	Yes

promote_sandbox

promote_sandbox runs the promotion path that moves approved changes toward the live site. It can include code, database changes, or both, and it defaults to a dry run so you can confirm readiness before anything is applied for real.

Field	Required	Default
sandbox_id	Yes	None
include_code	No	true
include_db	No	false
dry_run	No	true

Promotion is capability-gated by what it touches. Including code requires promote_code, and including database changes requires promote_database, both in addition to access to the sandbox. A dry run reports promotion readiness without changing live state, which makes it the safe default for an agent to call first.

discard_sandbox

discard_sandbox ends a sandbox you no longer need. It marks the sandbox inactive and invalidates its preview state, ensuring discarded work never reaches live. Active, promoted, and promotion-failed sandboxes can be discarded when the current user owns the sandbox or can manage all sandboxes.

Field	Required
sandbox_id	Yes

load_resources

load_resources returns Onumia’s MCP context resources, which give an agent grounding about the current environment. You may pass a list of uris; if you omit it, Onumia loads its default resource set.

Field	Required
uris	No

The current resource is the context document:

onumia://context

Database Merge Tools

Promoting database changes deserves more care than copying files, so Onumia separates it into a staged, reviewable workflow rather than a single blunt operation. The merge tools let you scan a sandbox’s current database changes, choose exactly which change groups to promote, validate that saved selection, apply it under row-level guards, and roll it back if needed. All of these tools require access to the sandbox and the promote_database capability.

The durable state is the staged selection for the sandbox. A scan is only a current view of the live, base, and sandbox databases; if it is missing or stale, call scan_database_merge again. Preflight and apply both recompute before acting, then apply the saved staged selection to that fresh scan.

1. scan_database_merge computes the current change groups without writing live rows.
2. update_database_merge_selection replaces the sandbox’s staged change group selection.
3. preflight_database_merge recomputes, validates the selection, and produces a rollback preview.
4. apply_database_merge recomputes again and applies the staged selection to live with guarded row preconditions.
5. rollback_database_merge reverses all or part of a prior merge, and is used only when needed.

apply_database_merge accepts an optional retention field. The default is keep, so MCP callers preserve the active sandbox unless they explicitly pass promote. Passing promote matches the Workspace default and moves the sandbox into the Promoted scope after a successful live apply.

rollback_database_merge accepts optional operation_ids, a list of source operation IDs from the stored rollback artifact. Omitting it reverts the whole promotion. Supplying it requests a subset; Onumia resolves that subset to change-group granularity when promotion display data is available, skips rows already reverted, and still blocks drift unless force is explicitly true.

Audit Logging

Every MCP tool call is recorded. Onumia logs who acted, the tool and sandbox involved, the inputs and outputs, and any errors. This trail is what lets a site owner answer, after the fact, exactly what an agent did and under whose identity.

Because inputs and outputs are stored, treat the log as a place secrets can land. Do not pass credentials, tokens, or other sensitive values through MCP tools unless you are comfortable with those values being written to Onumia’s audit log.