GoBuildWP CloudConnect your sites through one workspace.Explore Cloud →
GoBuildWP
Download freeDownload

OpenAI terminal agent, Native OAuth

Codex CLI WordPress MCP. A TOML table and a login.

Codex CLI WordPress MCP configuration is plain TOML: one [mcp_servers.<name>] table each, in ~/.codex/config.toml or a trusted project's .codex/config.toml. GoBuildWP writes that table for you. For OAuth you add the URL and then run codex mcp login; for a token the header goes in a nested http_headers table.

Get GoBuildWP free Setup steps

Checked against Codex CLI's documentation on 29 September 2026, entries from GoBuildWP Free 1.18.6

By GoBuildWPContent updated How we check claims

~/.codex/config.tomlOAuth 2.1
[mcp_servers.gobuildwp-your-site-com]
url = "https://your-site.com/wp-json/mcp/wppilot-oauth"

# then, in a terminal:
# codex mcp login gobuildwp-your-site-com
Config
~/.codex/config.toml
Sign-in
codex mcp login <name>
Diagnose
/mcp verbose

Connect screen

The Codex CLI entries GoBuildWP writes

The OAuth entry is two lines: the table header and url. The Connect screen adds the terminal alternative, codex mcp add with --url, followed by codex mcp login. The token entry adds [mcp_servers.<name>.http_headers] with the Bearer value. The Application Password entry is a stdio table that runs the npx bridge with the credentials in an env table.

OAuth 2.1url in the table, then codex mcp login. codex mcp add also detects OAuth and starts the flow itself.
Access tokenAn http_headers table with Authorization. To keep it out of the file, bearer_token_env_var names an environment variable instead.
Application Passwordcommand = "npx" with @automattic/mcp-wordpress-remote and an env table. Needs Node.js.

Endpoints on your site: /wp-json/mcp/wppilot-oauth for OAuth, /wp-json/mcp/wppilot for tokens and passwords. Through the optional GoBuildWP Cloud instead, every client uses https://app.gobuildwp.com/mcp with the server name gobuildwp, and a personal Cloud token is read from GOBUILDWP_TOKEN where the client supports environment variables.

~/.codex/config.tomlAccess token
[mcp_servers.gobuildwp-your-site-com]
url = "https://your-site.com/wp-json/mcp/wppilot"

[mcp_servers.gobuildwp-your-site-com.http_headers]
Authorization = "Bearer wpp_YOUR-ACCESS-TOKEN"

Setup

Configure Codex for a WordPress site

Codex loads a project's .codex/config.toml only when you have marked the project trusted, so a repository-level server is ignored until then.

  1. Add the server

    Either paste the generated table into ~/.codex/config.toml, or run codex mcp add with the name and --url. The command writes to the global file and reports that it added a global MCP server.

  2. Log in

    If Codex detects OAuth it starts the browser flow on its own; otherwise run codex mcp login with the server name. The callback returns to a loopback address on your machine.

  3. Keep tokens in the environment

    For a token, prefer bearer_token_env_var = "GOBUILDWP_TOKEN" in the table over a literal header, and export the variable. codex mcp add has no --header flag, only --bearer-token-env-var.

  4. Tune the timeouts for your host

    startup_timeout_sec defaults to 10 and tool_timeout_sec to 60. A slow shared host or a long audit may need more; raise them per server.

  5. Decide approvals per tool

    default_tools_approval_mode on the server, or tools.<tool>.approval_mode for one tool, takes auto, prompt, writes or approve. writes is a good fit while you learn what the site exposes.

Verify the connection before allowing changes

Select Read Only explicitly; the default is Production Safe. Use a dedicated identity with manage_options on a single site, or superadmin on multisite. Match the named tool call, site URL and returned record ID against WordPress.

First connection checkRead Only
Use the gobuildwp-your-site-com MCP server in Codex CLI. Do not change anything.

1. Report the active GoBuildWP safety profile.
2. List the abilities this connection can see.
3. Call wppilot/get-site-settings and report the site URL and locale.
4. Call wppilot/list-content for the five newest pages,
   then wppilot/get-content on one of them.
5. Name every ability you called and each WordPress ID you read.

These setup instructions are not a recorded live-client test. Keep credentials out of repositories, logs and shared files.

First task

A first task that fits a coding session

Codex is usually open in a plugin or theme repository. This prompt asks it to relate that code to the live site and to stop at a report.

Codex CLI promptReads only
Use the WordPress MCP server. Read only.

1. Call wppilot/system-status: PHP, WordPress and
   GoBuildWP versions.
2. Call wppilot/list-extensions and find any plugin
   whose folder matches this repository.
3. Compare its installed version with the version in
   this repo's main plugin file.
4. Call wppilot/site-health-tests and list anything
   that mentions this plugin.

Inside Codex CLI

Checking the server from inside Codex

codex mcp list shows configured servers and codex mcp get prints one. Inside the TUI, /mcp lists the servers and their tools, and /mcp verbose adds diagnostics such as the startup error when a server failed to start or authenticate.

enabled_tools and disabled_tools on the table narrow what Codex offers the model without touching the site. That is useful when you only want the content abilities in a coding session. GoBuildWP's own per-ability switches still apply underneath, so a tool Codex offers can still be refused by the site.

OAuth credentials are stored according to mcp_oauth_credentials_store: auto, file or keyring. On a shared machine, keyring keeps the WordPress grant out of a readable file. codex mcp logout removes it.

Signs it worked

  • codex mcp list shows the server enabled
  • /mcp lists wppilot/ tools
  • /mcp verbose reports no startup error
  • A read works and a write asks for approval

Troubleshooting

Codex CLI errors and their causes

SymptomCause and fix
Codex ignores the project's .codex/config.tomlThe project is not trusted. Trust it, or move the table to ~/.codex/config.toml.
Startup timeout on the first runThe default is 10 seconds. Raise startup_timeout_sec for this server; a cold WordPress host can take longer to answer the first request.
codex mcp add rejects --headerThere is no such flag. Use --bearer-token-env-var, or edit http_headers in config.toml.
Tools appear but calls fail with 401 after an hourExpiry or refresh failure is one possible cause. Inspect the actual OAuth error, clock, endpoint and header or policy evidence. Use codex mcp login as a recovery step after checking the failure; its success does not establish the root cause.
An old log file is missingCurrent Codex releases remove the legacy codex-tui.log at startup. Use /mcp verbose for MCP diagnostics instead.

Codex CLI beyond the first login

Ship a plugin change, then let Codex inspect staging

The natural Codex CLI loop is code first, site second. You change a plugin or theme in the repository, deploy it to a staging site the usual way, and then ask Codex, in the same session, to look at what the site now does. Keep the WordPress table on Read Only for this and leave Codex's approval mode at writes, so any attempt to change the site is both refused on the server and surfaced in the terminal.

Useful reads at this stage are wppilot/verify-rendered-page on the pages your change touches, which fetches them as a visitor gets them and reports PHP errors, unrendered shortcodes and empty containers, and wppilot/site-health-tests filtered to the tests that matter. If the change is visual, wppilot/capture-page before and after the deploy, then wppilot/compare-captures, gives Codex something concrete to compare instead of a guess. Captures are taken by a logged-in wp-admin tab, the Visual Runtime page, so keep it open while Codex asks for them.

  • "Call wppilot/verify-rendered-page on the home page and the checkout page. Quote any PHP notice that reaches the visitor."
  • "Compare the two captures of /pricing and tell me which sections moved. Do not edit anything."
  • "List the plugins with wppilot/list-extensions and confirm the version of ours matches the tag I just deployed."

A narrow token for unattended Codex runs

Your own sessions should use OAuth through codex mcp login. A run nobody watches, such as a nightly check, should not inherit that grant. Create an access token on the GoBuildWP Connect screen for it, give it an expiry, cap it at Read Only and limit it to the abilities the job reads, then reference it with bearer_token_env_var so the secret lives in the job's environment rather than in config.toml. The site enforces the cap even if someone later edits the Codex table. Reads are not written to the change ledger, so check that the job ran from the token's last-used time on the Connect screen and the AI clients panel on GoBuildWP's home screen; any write a token makes does carry its name in the ledger.

Pair the token with enabled_tools on the Codex side. The site already hides abilities outside the token's scope, but listing the same few tools in the table keeps the model's context short and makes the configuration readable to whoever maintains the job.

Many sites from one Codex table

A direct table reaches one WordPress site, so an agency working across client staging sites ends up with one table and one login per site. GoBuildWP Cloud lists Codex among the apps that sign in once with OAuth: you add the Cloud MCP link as a single server, log in to Cloud, and choose which connected sites Codex may reach. Calls still run on each site under its own profile. Cloud reaches sites over the internet, so a site on localhost stays a direct connection.

FAQ

Codex CLI questions

Where does Codex CLI keep MCP servers?

In ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows), or in .codex/config.toml inside a trusted project. Each server is a [mcp_servers.<name>] table.

Does the Codex desktop app use the same WordPress server?

OpenAI documents that the desktop app, the CLI and the IDE extension share MCP configuration on the same machine, so a server added in one appears in the others.

Should I use OAuth or a token with Codex?

OAuth for your own interactive use. A token referenced through bearer_token_env_var for scripted or CI runs, limited to the abilities the job needs and given an expiry.

Does Codex support SSE servers?

OpenAI documents stdio and Streamable HTTP. GoBuildWP serves Streamable HTTP, so no SSE setting is needed.

Related

Related OpenAI and terminal guides

Every client guide (26)

Codex CLI documentation read on 29 September 2026

Put the site next to the code in Codex.

One TOML table, one login, and approvals set to writes until you trust what the site allows.

Get GoBuildWP free See Pro pricing