Safety layer
The safety layer sits in the CLI and takes effect before and during every pipeline run.
- Bot-not-admin: before every pipeline, a preflight checks the authenticated user (GET /wp/v2/users/me in the edit context). If they carry the role administrator or super_admin, the engine hard-aborts, because any credential with Administrator privileges would be catastrophic in the event of a leak. If the Editor role is missing, a clear message follows.
- Draft by default: everything stays a draft.
--publishand--i-approveexpress the requested approval only. The currentset-post-statuswriter rejects the remote status transition with HTTP 409 andmanual_only. Publishing and further status changes happen manually in WordPress after review. - SSRF allowlist: images are fetched only from public http(s) URLs. Blocked are file:// and other schemes, localhost, loopback, link-local (including the cloud metadata IP 169.254.169.254), and private networks (RFC 1918, IPv6 ULA). Additionally, the host is resolved via DNS and every returned IP is checked (fail-closed); this protects against DNS rebinding and redirects to internal targets.
- Rate limit: a token bucket per client throttles outgoing requests. It starts full (burst up to 8), then four tokens per second; every real HTTP request costs one token. The throttling is purely time-based, without randomness and without dependencies.
- Idempotency: before creating, the pipeline searches by slug (across all relevant statuses, in the edit context). With an existing slug, it stops before any mutation and thereby prevents a duplicate because the current Companion declares remote updates
manual_only. Existing content is not overwritten. A stable slug is therefore mandatory.
BYO principle
The credentials (site, bot user, OAuth token, or Application Password) stay exclusively with the customer and come from the local client configuration or OAuth flow. WordPress stores revocable OAuth and Application Password references but no downloadable plaintext password. The CLI stores its OAuth grant at ~/.config/wp-agent/credentials.json by default, or at the path set in WP_AGENT_CREDENTIALS_FILE. On POSIX systems, it accepts only a private directory with mode 0700 and a file with mode 0600. Licence activation and daily revalidation connect directly to Polar. The plugins also read static update manifests and packages from wpagently.com. WordPress content and credentials are not transmitted in either flow. When the optional chat is used, WordPress sends the message and site data retrieved for the response directly to the AI provider configured by the Customer. WPAgently does not operate a proxy for this feature.
Production note
The mcp-adapter library is a Composer package, not a standalone plugin. In the original test it came from a host plugin (Rank Math bundles it). For the product, wp-agent-companion now bundles the library itself (vendor/, installed via the update guard), so the MCP server works without a third-party plugin.
Step 1: install the Companion plugin (about 5 minutes)
Install and activate the wp-agent-companion plugin on your site, exactly the way you install any other WordPress plugin. "Activate" simply means switching the plugin on in the WordPress backend so it starts working.
This Companion plugin (companion = helper) is the heart of the setup on the WordPress side. It registers a set of "abilities" with WordPress. An ability is a clearly bounded, verified action the assistant is allowed to perform, for example "create a post from Markdown." After activation, these abilities, among others, are registered:
wp-agent/create-post-from-markdown(the verified ARTICLE pipeline's only writer for new article content; updates are currentlymanual_only)wp-agent/upsert-pattern(landing pages built from individual sections)wp-agent/get-seo-meta(read SEO fields in a provider-neutral shape;set-seo-metacurrently only preflights and returns HTTP 409 withmanual_onlybefore any provider mutation)wp-agent/render-verify(read-only: checks effective rendering, block structure, and the documented provider traps)wp-agent/refresh-hooks(catches up on follow-up work WordPress otherwise only does on an editor save: permalink rules, post cache, sitemap)wp-agent/write-theme-file(writes a file into the active theme, only.html,.json, and.css)wp-agent/disable-power(emergency off-switch for the separate power plugin)
This guide is bundled with Skills 0.4.86 and describes the Companion 0.4.117 and Power 0.6.35 release set. Its evidenced scope contains 414 registered Companion abilities, 317 in the recommended Content profile, 440 combined Companion and Power schemas, 414 Companion tools, and 34 reviewed public paths. Free provides exactly 34 tightly bounded core abilities without a licence key, site limit, or call limit. This documentation describes capability boundaries only. It does not assert a promotion, public availability, or a particular sales or update channel. The activity log and connection setup card are administrative and onboarding features, not abilities. It also does not claim an MCP pre-execution approval hook. New Pods models and missing Pods fields fail closed with HTTP 409 before mutation. Code Snippets single use has no ability and remains a later Power path. Elementor migration still produces a preview only. Content-model migration creates only new ACF-to-ACPT Lite definitions and transfers no field values. Beaver Lite exposes no native user templates, so those paths fail closed. Its primitive global-settings map is a separate, real provider path. GenerateBlocks deliberately writes neither rich text nor arbitrary plain text. The commercial Meta Box Settings Pages value runtime and other licensed or proprietary gaps are not externally certified. Power can upload and inspect extension archives in a bounded way, but it does not extract, install, update, overwrite, or activate a generic extension. Deferred extensions are listed in the roadmap.
The complete current list is in the Abilities reference.
After plugin activation, WPAgently Free is immediately available. No account or licence key is required. If you bought an annual licence, open Tools > WPAgently Licence, paste the licence key supplied by Polar, and select “Activate licence.” The activation counts this exact website against your plan's site limit and expands the same installation to the complete Companion surface. The Power plugin must also be installed and activated separately. Its own server-side gates remain closed until you deliberately unlock them. A temporary Polar outage does not immediately block a previously confirmed paid licence. The cached proof is accepted for at most seven days. Free remains available independently.
After plugin activation, the plugin automatically sets up its own MCP server at <site>/wp-json/wp-agent/mcp. Open WPAgently > Overview to inspect the master switch, access status, active ability profile, and concrete diagnostics. The setup card checks PHP, WordPress, HTTPS, staging prerequisites, and the connection path, then gives the next safe step without exposing credentials. The Read only profile connects an agent without exposing write tools. The additional domain lock belongs to the paid licence.
For the current builder catalog, use the reference only. It records the evidenced boundaries of the Companion 0.4.117 and Power 0.6.35 release set, bundled with Skills 0.4.86. It does not assert promotion or availability. The Content profile remains usable without the broader Design or Full access profile.
For dynamic builder data, always follow the schema from tools/list. Native block attributes and supports use the closed, integrity-bound {format,json,sha256,bytes} envelope. Elementor and Beaver Builder documents deliberately use the separate {json,sha256,bytes} envelope. Do not send raw JSON objects to these fields. Values that exceed the relevant provider-path boundary or do not fit its public contract are rejected, not silently truncated.
On WordPress 7.0 or newer, you can also use the integrated chat under WPAgently > Chat and Preview. First configure your own AI provider under Settings > Connectors. The chat researches only through approved read-only Abilities. Write suggestions appear as a plan and run as the selected Editor only after you approve each action individually. Messages and retrieved site data go directly from WordPress to your AI provider, not through a WPAgently AI proxy. The preview accepts only paths on the same site and disables page scripts and forms. Use Select element to click a visible part of the page and attach it as bounded context to your next message. The selection never executes the CSS selector and is explicitly treated by the model as untrusted website content.
For visible work in the Gutenberg or Elementor editor, open WPAgently > Live Editor, choose the dedicated Editor user, and start the workspace. The assistant can then use the existing MCP connection to open pages and use their confirmed editor workspace. Gutenberg changes first exist only in the browser and become persistent only through the separately approved save command. After your individual approval, Elementor changes run through the verified server-side Elementor path with conflict protection, revision, and readback verification. Close the session when the work is finished. Bricks, Breakdance, and Oxygen still have no confirmed visual runtime workspace.
Done when: the plugin shows as “Active” and Tools > WPAgently Licence reports “Free active” or “Paid.” Everything else is verified automatically in step 5.