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 is the part of WPAgently that runs on your website. It gives your assistant clearly limited tools. An *Ability* is simply one allowed action, for example creating a new draft or checking a post.
With Free, you can start after activation. You need no account or license key. If you bought Paid, open Tools > WPAgently license, paste the license key from Polar, and select “Activate license”.
Power is not included in Companion and is not needed for this guide. Do not install it “just in case”. The normal Companion covers blog posts, pages, and landing pages.
After activation, open WPAgently. The control center shows the system status and leads you to Connect agent. Still check Settings > Permalinks for "Plain". With "Plain", the /wp-json/ route used here does not work. On a new site that is not yet public, you can select “Post name” and save. If your website is already public, do not change its permalink structure without a redirect plan. Ask the person responsible for your website or your hosting provider for help.
On WordPress 7.0 or newer, you can also use WPAgently > Chat and Preview. First configure your own AI provider under Settings > Connectors. Write suggestions always appear as a plan first. You approve them one by one.
You do not need the complete list of abilities at the beginning. Find it in the Abilities reference later, when you need a specific advanced feature.
This step is complete when the plugin shows as “Active” and Tools > WPAgently license reports “Free active” or “Paid.” With Free, verify the connection next through the read task and test draft in the quickstart. With the Paid CLI, check the connection and a test draft under First workflows.
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.
Only for a local test installation without https, add this to wp-config.php:
define( 'WP_ENVIRONMENT_TYPE', 'local' );Without HTTPS or this line, the “Application Passwords” menu item does not appear in the profile.
With Paid and the CLI, follow the instruction for your assistant under WPAgently > Connect agent. Claude Code and Codex show a short registration command there. For ChatGPT, Cursor, and Visual Studio Code, use the displayed MCP URL. Your assistant opens the WordPress sign-in on the first connection. Select the new Editor there and approve access. No password is written to a configuration file.
With Free, select your assistant and follow the recommendation WordPress shows. ChatGPT connects directly through OAuth. Cursor and Visual Studio Code can also use this browser flow directly. For Claude Code, Claude Desktop, Codex, and other assistants, WordPress offers a downloadable connection file when that client supports this method.
A downloaded file contains a separate Application Password. This is a revocable credential for this connection only. The plugin never stores its plaintext. Never commit the file or send it to another person. You can revoke the credential later in the agent user's profile.
For the Paid CLI, you do not need an additional Application Password in the recommended flow. It uses browser OAuth in step 4. Select this exact Editor there and approve access. Use an Application Password only when WPAgently > Connect agent explicitly offers it as a fallback for your assistant.
If you later work with forms, enable their permissions separately. Form responses can contain personal data. Do not give them blanket access for an assistant.
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)
This browser OAuth route through the WPAgently CLI belongs to Paid. First install the CLI as described in the CLI guide. With Free, use the method from the connection guide.
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 opens your browser and waits for your approval. Sign in to WordPress there, select the Editor from the connection guide, and approve access. The CLI can then renew the connection on your own computer. Your regular WordPress password and the Editor password are not passed to or stored by the CLI.
If the browser cannot open automatically, wp-agent login --site "$WP_AGENT_SITE" --no-open prints an address that you can open yourself. Use wp-agent logout --site "$WP_AGENT_SITE" to disconnect later. Use --force only when your site is permanently unreachable. It then removes only the local record.
An Application Password remains the technical fallback. Use it only when browser OAuth is not possible, and never enter credentials in a shared terminal or shared file. You do not need wp-agent init for this normal CLI login. For the other route, use the connection file from the connection guide.
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)
Choose only one of the following routes. With Free, follow the recommendation shown in WordPress. With Paid, you can also choose the CLI with browser OAuth.
When WordPress offers a connection file
Open WPAgently > Connect agent in WordPress, choose your assistant, and download the offered file. Then follow the instruction WordPress shows for that assistant.
For Claude Code, place .mcp.json in your project folder and restart Claude Code. For Claude Desktop, open the downloaded .mcpb file with Claude Desktop and approve the extension. For Codex, paste the content of codex-mcp-wp-agent.toml into ~/.codex/config.toml or the .codex/config.toml of a trusted project. The Codex configuration asks before write actions.
The downloaded file contains a credential for your agent user. Treat it like a password: do not email it, put it in a public place, or commit it to Git. You can revoke the credential later in the WordPress profile of the agent user.
Paid only: CLI and browser OAuth
If you use Paid and the CLI, you can register Claude Code in user scope without a static WordPress password:
wp-agent init --agent claude --scope user --site "$WP_AGENT_SITE" --i-approveThen open /mcp in Claude Code and approve access in the browser. No fixed WordPress password is stored in a configuration file.
Register Codex through the same route:
wp-agent init --agent codex --scope user --site "$WP_AGENT_SITE" --i-approveThen run the codex mcp login <name> command shown in the output and approve access in the browser. WPAgently does not overwrite a different existing configuration.
More clients
For Cursor, Windsurf, Visual Studio Code, Gemini CLI, OpenCode, Cline, Roo Code, Kilo Code, Zed, GitHub Copilot, Amazon Q, and Antigravity, you do not need the CLI for your first connection. Select the assistant under WPAgently > Connect agent and follow the instruction shown there. Depending on the app, you either approve access in the browser or import a downloaded file once.
wp-agent init can create comparable files, but it already needs an intentionally configured local agent user and an Application Password. It is not an additional sign-in route. For your first connection, the instruction in WordPress is simpler and safer.
ChatGPT without the CLI
As of 6 September 2026, OpenAI's Developer mode documentation lists Developer mode as available to Pro, Plus, Business, Enterprise, and Education accounts on the web. It provides MCP tools for reading and writing. In ChatGPT, open Settings > Security and login and enable Developer mode.
Then open ChatGPT Plugins, choose the plus button, and create a Developer mode app with the MCP URL from WPAgently > Connect agent. Select OAuth authentication and approve WordPress access in the browser. ChatGPT then connects directly to your WordPress site. WPAgently actions marked manual_only in tools/list remain manual.
Then confirm in the respective assistant that tools/list shows the wp-agent-* tools. With Free, this and the read task from the quickstart are your connection check. With the Paid CLI, wp-agent doctor has already checked the server.
Paid only: install Skills
Skills are short guides for Claude Code or Codex. They help your assistant use the checked WPAgently workflows for articles, landing pages, and error reports. You do not need Skills just to connect.
The skills bundle wp-agent-skills-<version>.zip contains an installer. It first shows what it would do. Only the second command installs the skills after your approval:
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 are kept until you deliberately add --replace. The Power skill is never installed automatically. Leave it out for ordinary WordPress work.
The connection is complete when your assistant shows the wp-agent-* tools in tools/list. With Paid and installed Skills, it should also know 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.