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.
Step 2: create a dedicated Editor bot (about 3 minutes)
Open WPAgently > Connect agent and select “Create dedicated agent user.” The plugin creates an Editor with a random internal login password. We call this separate user the “bot user.” The assistant works through this account, never through your own. You can revoke the bot's access without locking yourself out.
The bot gets the Editor role, never Administrator. If your WordPress backend runs in German, this role is called "Redakteur" in the UI (the technical name stays editor, which is exactly what WPAgently checks). An admin account in the wrong hands would be the worst-case damage, so WPAgently refuses to do any work as soon as the bot carries admin rights. That's deliberate, and it protects you.
Application Passwords require HTTPS. An Application Password is a special WordPress password just for programs and tools, separate from your normal login, that you can revoke at any time. If your instance runs locally without an SSL certificate (that is, without https://), add this to the wp-config.php file instead:
define( 'WP_ENVIRONMENT_TYPE', 'local' );Without one of the two conditions (HTTPS or this line), the "Application Passwords" menu item doesn't even appear in the profile.
For an OAuth-capable client, copy only the displayed MCP URL under WPAgently > Connect agent. The client opens the WordPress login on first connection. Select the new Editor there and approve access. No password is written to a configuration file.
Only when your client does not support OAuth should you select the Editor under “Application Password fallback” and download the matching configuration once. The plugin creates a separate Application Password and never stores its plaintext. Never commit the downloaded file. You can revoke the connection later in the agent user's profile.
The CLI does not need another Application Password. Its recommended flow in step 4 uses browser OAuth. You select this exact Editor on the consent screen and approve access. Another Application Password remains an explicit fallback only when browser OAuth cannot work in your environment.
If WPForms is active, three separate permissions for forms, entries, and writes appear further down. Form reading is prepared automatically for a newly created agent user, but this does not expose any tools by itself. Entry access always stays off because submissions may contain personal data. Writes additionally require WPForms' own toggle under WPForms > Tools > AI MCP and the corresponding group under WPAgently > Overview. The agent remains an Editor throughout. No Administrator capability is added. The three permissions apply only at WPAgently's MCP endpoint. Normal WPForms admin, AJAX, and foreign REST surfaces remain closed.
If Ninja Forms is active, four separate permissions appear for form reads, sensitive submissions, form changes, and email delivery. Only form reading is prepared for a newly created agent user. The active WPAgently profile remains a separate gate for the tools themselves. Submissions, writes, and email delivery must each be enabled explicitly. The broad Ninja Forms capability nf_edit_forms is mediated only during a matching call at WPAgently's MCP endpoint and is never persisted on the user account. Eight risky deletion, settings, secret, and submission paths remain fully blocked.
Done when: the agent user has the Editor role and you either copied the OAuth MCP URL or downloaded the fallback configuration once.
Step 4: connect the CLI through the browser (about 3 minutes)
First, store only the base address of your site in the shell. Do not include /wp-json or a trailing slash:
export WP_AGENT_SITE="https://your-domain.tld"Then start the login:
wp-agent login --site "$WP_AGENT_SITE"The CLI registers its own public OAuth client, opens your browser, and waits locally for the response. Sign in to the WordPress backend, select the Editor from step 2, and approve access. The CLI then stores a short-lived access token and a rotating refresh token in your private local configuration directory. On macOS and Linux, only your user can read the directory and file. Neither your WordPress password nor the Editor's password is given to or stored by the CLI.
By default, a site stores at most 200 OAuth clients, pending sign-ins, and active connections. Large installations can adjust this server-side through wpagent_companion_oauth_max_clients. Valid values are integers from 1 through 10,000. Invalid values fall back to 200. Increasing the limit grows option storage and should be done only for a concrete capacity need.
If the browser cannot open automatically, wp-agent login --site "$WP_AGENT_SITE" --no-open prints the consent URL for manual opening. wp-agent logout --site "$WP_AGENT_SITE" revokes server access and removes the local record. Use --force only if the server is permanently unreachable. It removes the local record without claiming to have revoked the server grant.
Application Passwords remain available as a fallback. Set WP_AGENT_USER and WP_AGENT_APP_PASSWORD, or pass --user and --app-password. Explicit password credentials take precedence over stored OAuth credentials. Credential flags can be visible in process lists and shell history. The CLI does not load a .env file automatically.
wp-agent init is not required for normal CLI login. By default, it creates static MCP connection files for Claude Code, Codex, Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity and requires a separate username and Application Password for that purpose. Claude Code and Codex additionally support the user-wide OAuth registration in step 6, which needs no WordPress password. In this guided flow, you already downloaded the appropriate client file directly from WordPress in step 2.
Done when: wp-agent login reports a successful connection. The CLI automatically renews expiring tokens from then on.
Step 6: connect the agent (about 4 minutes)
Now add the connection file downloaded in step 2 to your assistant. It is separate from the CLI's OAuth login.
For Claude Code, .mcp.json is directly usable: place the file in your project directory. Claude Code detects the MCP server from it automatically on the next start. Alternatively, register the same site once in user scope without a static WordPress password:
wp-agent init --agent claude --scope user --site "$WP_AGENT_SITE" --i-approveThe command invokes the installed Claude CLI without an Authorization header. It does not overwrite an existing user entry with the same name. Then open /mcp in Claude Code and complete OAuth in the browser. If you deliberately need a project-local file instead, wp-agent init --agent claude still creates .mcp.json with a separate Application Password.
Codex can also be registered user-wide without a static WordPress password:
wp-agent init --agent codex --scope user --site "$WP_AGENT_SITE" --i-approveThe command checks an existing entry with the same name first and does not overwrite a different or secret-bound configuration. After creating an entry, it reads the saved endpoint back exactly. Then run the codex mcp login <name> command shown in the output. WPAgently does not open a browser without asking.
For Claude Desktop, do not use wp-agent init. In WordPress, open WPAgently > Connect agent, select Claude Desktop, and download the site-specific .mcpb file. Open it locally with Claude Desktop and approve the extension. The .mcpb contains a dedicated, revocable WordPress Application Password, so treat it as a secret. A direct remote entry from .mcp.json does not work in Claude Desktop.
For Codex, paste codex-mcp-wp-agent.toml into ~/.codex/config.toml or the .codex/config.toml of a trusted project. Codex connects directly to WordPress through Streamable HTTP. The generated block sets default_tools_approval_mode = "writes", so write tools require confirmation. No local bridge process or extra npm dependency is needed. Here too, wp-agent init --agent codex is only an alternative way to create the file with a separate Application Password.
The CLI also creates the same client-specific connection files for Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity. Use wp-agent init --agent cursor, windsurf, vscode, gemini-cli, opencode, cline, roo-code, kilo-code, zed, github-copilot, amazon-q, or antigravity. wp-agent init --agent all writes all fourteen supported MCP variants to the selected output directory. Merge mcpServers from the GitHub Copilot file into ~/.copilot/mcp-config.json, .mcp.json, or .github/mcp.json. For Amazon Q, use ~/.aws/amazonq/default.json or .amazonq/default.json. Depending on the installed Antigravity version, use ~/.gemini/config/mcp_config.json or ~/.gemini/antigravity/mcp_config.json. Open MCP Servers > Manage MCP Servers > View raw config to find the path that your installation actually uses. Merge the Cline file into ~/.cline/mcp.json or the extension's MCP settings file, the Roo file into the global mcp_settings.json or .roo/mcp.json, the Kilo file into ~/.config/kilo/kilo.json or .kilo/kilo.json, and context_servers from the Zed file into your Zed settings. These files contain the Application Password and therefore use private file mode 0600. Merge the relevant entry into the existing client configuration instead of overwriting unrelated server entries.
For ChatGPT, work on the web and open the Apps area. Depending on the plan, it appears in personal settings or workspace settings. In Business, only an admin or owner can enable developer mode and deploy a custom app. In Enterprise and Edu, the person creating the app needs the permission assigned by an administrator. Enter the MCP URL shown under WPAgently > Connect agent, select OAuth authentication, scan the tools, and complete the WordPress consent flow in the browser. ChatGPT connects directly to your WordPress site. Local MCP servers are not supported. Under ChatGPT's current rules, full write tools require a Business, Enterprise, or Edu workspace. ChatGPT Pro currently limits custom MCP connections to read and fetch operations.
Then confirm in the respective assistant that tools/list shows the wp-agent-* tools (tools/list is the list of tools the assistant knows from your site). wp-agent doctor in step 5 already verified this server-side; here you're only making sure the assistant itself connects cleanly. After that, wp-site-context-en selectively loads site context, the design profile, matching site skills, and relevant memories. If one design direction is active, the skill additionally loads its voice, rules, avoid patterns, and validated profile. Inactive directions remain unused. The execution skills wp-article-en, wp-landing-en, wp-reference-en, and wp-content-en guide the verified workflows. wp-feedback-en prepares a reproducible, privacy-conscious report for user review when something fails and never sends data automatically.
The skills themselves come from the included skills bundle wp-agent-skills-<version>.zip. Replace <version> with the version number from your download. The ZIP contains a dependency-free installer. The first run previews the plan. After your approval, the second applies the complete skill set as one transaction for Claude and Codex. If one skill fails, skills installed or replaced earlier in that run are rolled back:
unzip wp-agent-skills-<version>.zip -d wp-agent-skills-bundle
node wp-agent-skills-bundle/skills/install.mjs --agent both --locale en
node wp-agent-skills-bundle/skills/install.mjs --agent both --locale en --i-approveIdentical existing skills are skipped. Different local versions remain untouched unless you deliberately add --replace. The Power skill is never installed implicitly. Add --include-power when you deliberately want it. For a manual installation, the six English standard skills map to these paths:
mkdir -p ~/.claude/skills/wp-article-en ~/.claude/skills/wp-landing-en ~/.claude/skills/wp-reference-en ~/.claude/skills/wp-content-en ~/.claude/skills/wp-site-context-en ~/.claude/skills/wp-feedback-en
cp -R wp-agent-skills-bundle/skills/en/wp-article/. ~/.claude/skills/wp-article-en/
cp -R wp-agent-skills-bundle/skills/en/wp-landing/. ~/.claude/skills/wp-landing-en/
cp -R wp-agent-skills-bundle/skills/en/wp-reference/. ~/.claude/skills/wp-reference-en/
cp -R wp-agent-skills-bundle/skills/en/wp-content/. ~/.claude/skills/wp-content-en/
cp -R wp-agent-skills-bundle/skills/en/wp-site-context/. ~/.claude/skills/wp-site-context-en/
cp -R wp-agent-skills-bundle/skills/en/wp-feedback/. ~/.claude/skills/wp-feedback-en/The target paths must also include ~/.claude/skills/wp-site-context-en and ~/.claude/skills/wp-feedback-en. The installer uses ~/.codex/skills for Codex. The included docs/en/AGENTS.wp-agent.md and docs/en/agents/codex-content.md remain available as a fallback for clients without skill support. Without this bundle, the agent does not know these workflows, even if the MCP connection itself is already up.
Done when: your assistant shows the wp-agent-* tools in tools/list and knows the copied skills. From now on you can ask it to build a real article or landing page. Hardened write paths check their changed values in the background.