Which abilities are served
The Dashboard serves every ability in themainwp/ namespace that sets show_in_rest to true in its meta. The tool name is the ability name without mainwp/, with hyphens turned into underscores: mainwp/acme-purge-cache-v1 becomes acme_purge_cache_v1. If two abilities produce the same tool name, neither is served.
Register your abilities in a category of your own. A mainwp/ ability in one of MainWP’s core categories (mainwp-backups, mainwp-batch, mainwp-clients, mainwp-knowledge, mainwp-sites, mainwp-tags, mainwp-updates) that MainWP’s own tier table doesn’t list is always Dashboard tier (Confirm under Hands-off), whatever its annotations or contract say.
How an ability gets its tier
The Dashboard looks for an ability’s tier in this order and uses the first match:- An audited entry. MainWP reviews the abilities of its released extensions and ships their tiers with the Dashboard. An audited tier wins over anything your extension declares. Until the extension version it was reviewed against is installed, the tool is listed under Not available yet. A few audited entries only open the unreviewed path, and a declared contract replaces those.
- A declared contract from the
mainwp_remote_mcp_extension_contractsfilter. See Declare a contract. - The ability’s annotations, from
meta.annotations:readonly: truewithdestructive: falsemakes it a Read tool, which runs directly.readonly: falsewith a booleandestructiveputs it on the unreviewed path.- Anything else, including missing annotations, lists it under Not available to AI apps, and it can’t be called.
The unreviewed path
A write ability with valid annotations and no audited entry or contract is listed in the panel under Not reviewed by MainWP. Administrators can switch the section off, or switch off each tool in it. On this path:- The tier is Dashboard, or Confirm when the connection uses Hands-off.
- The approval page carries the heading “MainWP hasn’t reviewed which sites this changes”.
- The ability’s own
dry_runis never used as a preview. The user approves the arguments the app sent. - The Dashboard keeps no runnable copy of the call. It runs only when the app calls the tool again after approval, and Run it here instead isn’t offered.
- An ability whose input schema has a
preview_tokenproperty, or adry_runorconfirmproperty that isn’t a boolean, is refused with “This tool needs a MainWP contract before AI apps can use it.”
Declare a contract
A contract tells the Dashboard how to preview your ability, which control values to send when it runs, and which sites it touches. Add contracts with themainwp_remote_mcp_extension_contracts filter. It receives an array keyed by ability name. Add your entries and return the array.
This example declares a contract for an ability that purges a cache on a list of sites. Its input schema declares site_ids_or_domains, a boolean dry_run and a preview_token string. A dry run returns the planned purge with a preview_token, and a real run needs that token back.
dry_run: true, keeps the preview_token from the result, and shows the user the preview. When the user confirms, it runs the dry run again for a fresh token, then runs the ability with dry_run: false and that token. If the sites or purge_targets fields of the new preview differ from the ones the user saw, nothing runs and the user is asked again.
Contract keys
A contract may contain only these keys.
The Dashboard validates the whole contract. An unknown key, a value of the wrong type or a malformed
preview makes it ignore the contract, and the ability falls back to its annotations as if no contract existed. That includes a tier of write or no tier at all: a declared contract can’t make an ability run without a confirmation or an approval.
One rule is enforced differently. A contract with a native_token_field must list compare_fields. Without them, the Dashboard couldn’t tell whether the action changed between the user’s confirmation and the run. Such a contract isn’t ignored: every call to the tool is refused with “This tool needs a MainWP contract before AI apps can use it.”
The preview
preview takes these keys:
kind:dry_runruns the ability itself with the previewcontrols.abilityruns a separate preview ability.planruns no preview, and the user sees the arguments only.ability: the name of the preview ability. Set it whenkindisability, and only then.arg_map: forkind: ability, which arguments to pass to the preview ability, as'argument' => 'preview argument'. Arguments not in the map aren’t passed.controls: argument values the Dashboard sets for the preview, such as'dry_run' => true. Values are scalars ornull.capture_token: the field of the preview result that holds your ability’s own confirmation token.
native_token_field needs a capture_token, and doesn’t work with kind: plan.
Pick compare_fields that describe the effect: which sites, which items, which values. A field that changes on every run, such as a timestamp, makes every confirmation look stale. The token itself is never compared.
What the app can’t send
Before your ability sees the arguments, the Dashboard keeps only the properties your input schema declares and dropsdry_run, confirm, preview_token, the names in your contract’s controls, your native_token_field and your gate_supplied fields. Those values come only from the contract and the Dashboard. An argument that holds a URL with a user name or password in it is refused.
Resolvers and adapters
The resolver reads the call’s arguments and turns them into a fixed list of sites the user can reach. The approval shows those sites, and the call runs on exactly them. If any part can’t be resolved, the call is refused rather than narrowed.
When the call runs, the Dashboard replaces the site or client argument with the resolved IDs (a
tag_id is already an ID), so a domain, an email or an empty list can’t select different sites later.
For a declared contract, use atomic, the default, which runs the ability once, or chunked_sites, which works with the site and sites resolvers and splits the sites into steps of 10. A call over more than 10 sites then runs as a background job. A contract with a native_token_field must use atomic, because a token belongs to one preview of one call. direct and updates are used by MainWP’s own tools.
Queued and deferred work
If your ability queues work instead of finishing it during the call, that work could run after the user revoked the connection. Two hooks let your worker check first.mainwp_remote_mcp_deferred_context is a filter that returns null, except while the Dashboard runs your ability for a remote AI connection. Then it returns array( 'grant_id' => int, 'policy_version' => int ) for the connection that authorized the call. Read it inside your ability’s execute callback, and store both values with the queued item.
mainwp_remote_mcp_authorization_active( $grant_id, $policy_version ) returns true while that authorization still holds. It returns false once the connection is revoked or expires, its approval policy changes, it’s changed to view only, or remote AI connections are turned off or forced off by the kill switch. Call it before every dispatch, not once when you queue.
null while the Dashboard runs your preview, and for work queued from the Dashboard’s own screens, the REST API or cron. That work needs no check. Treat a missing function as inactive: the item was queued under a remote connection, and the Dashboard can no longer confirm it.
Don’t hand remote work to MainWP’s core batch queue. If your ability answers with a core batch job, the call fails with “The Dashboard queued this work to run later instead of running it now, so this call can’t report its result.”
Credential fields
The Dashboard treats an argument as a credential when:- its name contains
pass,secret,tokenorkey, in any case. This also matches names such askeyword. - its name is
adminpassword,http_pass,http_useroruniqueid. - its schema sets
writeOnly: true, at any depth of that property’s schema, including nestedproperties,itemsandanyOf,oneOfandallOfbranches. - it’s listed in your contract’s
sensitive.
writeOnly in your input schema, so every consumer of the ability knows not to echo or store them:
credential_bearing: true, is handled without storing it:
- The credential never enters a stored approval or a background job. The call runs only when the app calls the tool again with the same arguments, and Run it here instead isn’t offered.
- It runs in one step while the app waits, never as a background job. A credential-carrying call that would need more than one step, over 10 sites, is refused.
- The approval page and the chat summary show the argument as “supplied”.
- In previews and results, credential fields at any depth show as
[redacted], and any string containing a credential value from the call has that value replaced with[redacted].
