OPERATIONS MANUAL
Everything you need to install AgenticWP, wire it into your AI agent, and start driving WordPress through MCP. No dev environment required. If you can paste into WP Admin and edit a JSON file, you are qualified.
Installation
Four steps. Sequential. Each one verifies before the next begins.
agenticwp.zip, upload via WP Admin → Plugins → Add New → Upload Plugin, activate.Plugins → Add New → Upload Plugin → Choose File → agenticwp.zip → Install Now → Activate
valid within 2 seconds.manage_options capability.Users → Profile → Application Passwords → Name: "AgenticWP MCP" → Add New → Copy the generated password (shown exactly once)
agenticwp-mcp.zip, extract, run the installer.unzip agenticwp-mcp.zip cd agenticwp-mcp chmod +x install.sh ./install.sh
cd agenticwp-mcp install.bat
~/MCP/AgenticWP/, installs mcp + aiohttp, prompts for your WP URL, username, and app password, and generates a ready-to-use .mcp.json.Configuration
Three environment variables. That is the entire configuration surface.
https://. e.g. https://example.commanage_options. Usually your main account, or a dedicated agent user for audit clarity.define('AGENTICWP_READONLY', true) to wp-config.php. Every mutation endpoint will short-circuit and return {success:true, readonly_mode:true, would_save:{…}} instead of writing — perfect for demos and first-run verification.AI Client Setup
The ZIP ships pre-made config files for the six most common clients. Copy, paste, restart.
.mcp.json in project root~/.cursor/mcp.json~/.codeium/windsurf/mcp_config.json.vscode/mcp.jsonserver.py with 3 env vars{
"mcpServers": {
"agenticwp": {
"type": "stdio",
"command": "python3",
"args": ["/path/to/agenticwp-mcp/server.py"],
"env": {
"WP_URL": "https://your-site.com",
"WP_USER": "admin",
"WP_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
}
}
}
}Usage
Talk to your agent in plain English. It picks the right tools.
update_option(blogname), update_option(blogdescription)get_elementor_page, build_elementor_section(hero), insert_elementor_element, update_elementor_pagefind_products, bulk_update_productsseo_audit, update_postmeta_multiTroubleshooting
Everything that has gone wrong before, and how to fix it.
MCP tools return 401 Unauthorized
Application password is wrong or the user lacks manage_options. Re-check by opening https://your-site.com/wp-json/agenticwp/v1/status in a browser — if it asks for Basic Auth, the endpoint is live. Paste the exact WP_USER and WP_APP_PASSWORD into the browser prompt. If that works, the problem is in your .mcp.json.
Elementor edits save but the frontend still shows the old version
You called the standard WP REST API instead of update_elementor_page. Elementor stores rendered HTML and CSS separately from _elementor_data — only the AgenticWP endpoint calls Document::save(), which regenerates all three atomically. Fix: use update_elementor_page (whole page) or update_elementor_element (single widget).
“Payload too large” (HTTP 413) when saving a big Elementor page
You hit the 500 KB safety ceiling for update_elementor_page. Use update_elementor_element for the specific widget you changed, or insert_elementor_element for additions. The ceiling is filterable via agenticwp_update_page_max_bytes if you really need to push whole-page writes.
“Lock held” (HTTP 409) on an Elementor save
Another agent (or another window of the same agent) is mid-save on the same post. The lock auto-releases after 30 seconds. Retry once, or check who holds it via data.lock in the error response.
License shows “invalid” even though I just paid
Check the billing email — the license key is included in the confirmation. Paste it into Settings → AgenticWP with spaces preserved. If it still fails, the license server may be unreachable from your host — the plugin has a 7-day grace window and will auto-retry hourly.
WP CLI / cron errors mention “AGENTICWP_READONLY”
Read-only mode is enabled. Remove define('AGENTICWP_READONLY', true) from wp-config.php, or delete the agenticwp_readonly option via delete_option, or remove the agenticwp_readonly filter from your code.
Python version too old (MCP server won’t start)
MCP requires Python 3.10+. Check with python3 --version. Upgrade via your system package manager or python.org.
Agent says “I don’t have that tool”
The MCP server isn’t registered or didn’t start cleanly. Check the agent’s MCP server list in its UI or logs. Restart the agent fully (not just the window). If it’s still missing, run python3 server.py directly — it should print MCP handshake JSON. If you see a Python traceback, that’s your real error.
System ready
Loaded: loaded (agenticwp.php; enabled)
Active: active (running) since 2026-04-23
Tasks: 35+ endpoints, 38+ MCP tools
Memory: negligible (pure REST API)
License: valid
# your move.