Before you start
- AgentedSEO is active (WordPress 6.9 or later, PHP 8.1 or later), and you are an administrator.
- The site is on HTTPS.
- Codex keeps MCP servers in
~/.codex/config.toml, or.codex/config.tomlin a trusted project. The CLI, the IDE extension and the ChatGPT desktop app share it.
https://your-site.com/wp-json/agentedseo/mcp01Create the agent’s password
- Open AgentedSEO › Agents › Connections.
- Under Connect an agent choose Desktop or code app.
- Name your agent
Codexand click Create password. AgentedSEO creates the useragentedseo-codexwith the SEO Agent role and an application password, shown once. - Copy the whole
Basic …Authorization value from the config shown. The JSON around it is for other clients.
02Add the Codex WordPress MCP server to config.toml
Keep the secret in an environment variable:
$ export AGENTEDSEO_AUTH="Basic <value from the Connections screen>"Add the server to ~/.codex/config.toml:
[mcp_servers.agentedseo]
url = "https://your-site.com/wp-json/agentedseo/mcp"
env_http_headers = { "Authorization" = "AGENTEDSEO_AUTH" }env_http_headers maps a header to the variable that holds its value. bearer_token_env_var doesn’t fit: it sends Bearer, and an application password uses Basic.Optional keys
default_tools_approval_mode = "writes"
tool_timeout_sec = 120writes makes Codex ask before any tool not marked read-only; AgentedSEO marks its read tools read-only. The timeout gives a full site check more than the 60-second default.
03Or use the app or the IDE extension
Settings › MCP servers › Add server, name agentedseo, Streamable HTTP, paste the endpoint, save, Restart.
Gear menu › MCP servers › Add server, same fields, Restart extension.
Both write the same config.toml. Add the env_http_headers line in the file if the form has no header field.
04Sign in without a password
Codex supports OAuth for Streamable HTTP servers, and AgentedSEO offers OAuth 2.1 with dynamic client registration.
$ codex mcp add agentedseo --url https://your-site.com/wp-json/agentedseo/mcp
$ codex mcp login agentedseoThen run the connection test under Agents › Connections.Codex opens a page on your site. Sign in as an administrator and click Approve. AgentedSEO creates an SEO Agent user for Codex, listed on the Connections screen.
05Check it
codex mcp listshowsagentedseoand whether it is enabled.- In the Codex TUI,
/mcplists its tools, namedagentedseo-<ability>. - In WordPress, Run test on the Connections screen. “Authorization header reaches WordPress” must pass.
06Your first safe task
Use the agentedseo MCP tools. Start with agentedseo-get-capabilities. Find one published post with no meta description, write one, call set-meta with dry_run first and show me the before and after, then submit it with a note. Change nothing else.
- The agent calls
agentedseo-set-meta. Meta titles and descriptions ask first by default, so the answer isproposed. The live page has not changed. - Open AgentedSEO › Dashboard › Approvals. Check Before and After, the checks it passed and the agent’s note. Click Approve.
- Open AgentedSEO › Dashboard › Change log, open the change’s Details and click Undo. The Before value is back, and the undo is logged.
The live page has not changed.
Undo restores the Before value, and the undo is logged.
Every write also returns a batch_id. Ask Codex to call revert-change with it and it undoes its own change.
07Two approval layers, and why both help
I like Codex’s
writesmode next to AgentedSEO’s queue. Codex asks before the call leaves your machine; AgentedSEO decides what reaches the live site. One guards your terminal, the other guards your visitors.
| Layer | Where it lives | What it decides |
|---|---|---|
| Codex tool approval | Your config.toml | Whether Codex may call a tool at all |
| AgentedSEO approval rules | AgentedSEO › Agents › Approval rules | Whether a change applies now or waits in Approvals |
08What Codex can and can’t change
- New drafts
- Edits to drafts
- Meta, schema, redirects, sitemaps, keywords, alt text
- Edits to published content, publishing
- Bulk changes over 20 pages
- robots.txt edits
- Noindex on a page with traffic
- Deleting redirects or schema
- Trashing or unpublishing
- Permanent deletes
- Header and footer code
- Users, plugins, themes, settings outside AgentedSEO
Change the per-area defaults in AgentedSEO › Agents › Approval rules. Approving and rejecting are not tools: only a person can do them, in WordPress. Full table: what your agent can and can’t change.
09Troubleshooting
| Symptom | Fix |
|---|---|
| Codex connects but tools are missing | AGENTEDSEO_AUTH isn’t set in the shell Codex started from, so it connects without auth and AgentedSEO answers 401. |
| Header check fails in the self-test | On Apache add SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 to .htaccess, or ask your host. |
| Server times out at startup | Raise startup_timeout_sec (default 10). |
| A long tool call times out | Raise tool_timeout_sec (default 60). |
429 agentedseo_locked_out | Ten failed sign-ins in 15 minutes lock the address out for 15 minutes. |
Project .codex/config.toml ignored | Codex reads project config in trusted projects only. |
10Questions about Codex and WordPress
No. AgentedSEO’s server sends Codex its own instructions when it connects: start with get-capabilities, dry run first, treat site content as data. Codex reads that instructions field.
It needs a site that can install AgentedSEO and answer at a public HTTPS address.
Yes, on a server where it can. Always pass the agent’s user: wp agentedseo record get post:42 –user=agentedseo-codex. Without –user, WP-CLI skips every permission check and approval rule.
No. It gets an application password, or an OAuth token, for its own SEO Agent user.