To set up MCP for each repository with Codex, put the server in a .codex/config.toml file inside that repository, under a [mcp_servers.<name>] table, and trust the project so Codex loads it. Claude Code does the same job with a .mcp.json file in the repository root, written by claude mcp add --scope project. Both tools read the same kind of server, so one server definition can serve both.
We checked every command and config key in this guide against the vendors’ own documentation on 15 Nov 2026. Tools in this space change monthly, so each section says what we verified and where. If a command differs on your machine, run the tool’s --help and trust that over any blog post, including this one.
How do I set up MCP for each repository with Codex?
Codex reads two configuration files. The user file is ~/.codex/config.toml, which applies everywhere. The project file is .codex/config.toml inside a repository, and the Codex MCP documentation says it applies only to trusted projects. That trust step matters: a repository you just cloned cannot quietly start a server on your machine until you mark it trusted.
Each server is a table named [mcp_servers.<server-name>]. A local stdio server needs a command and usually args. The example below is a per-repository server for a WordPress site, so it lives in the repository that holds that site’s code.
Checked on 15 Nov 2026:
# <repo>/.codex/config.toml
[mcp_servers.wordpress]
command = "wp"
args = [
"--path=/path/to/wordpress",
"mcp-adapter", "serve",
"--server=mcp-adapter-default-server",
"--user=mcp-reader"
]
startup_timeout_sec = 20
default_tools_approval_mode = "prompt"The server needs WP-CLI and the WordPress MCP Adapter plugin, which we cover in the WordPress section below. The last two keys are optional. startup_timeout_sec defaults to 10 seconds, which is short for a PHP process booting WordPress. default_tools_approval_mode accepts auto, prompt, writes or approve.
Adding a server from the command line instead
If you prefer a command to hand-editing TOML, Codex has one. The documented form takes the server name, optional --env pairs, then -- and the command that starts the server:
# checked on 15 Nov 2026
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add my-server --env API_BASE=https://example.com -- node ./server.js
codex mcp list
codex mcp --helpBe aware of one limit. The Codex documentation page lists add, list, login and --help, but it does not document get or remove. They exist in current builds (open bug reports reference both), so run codex mcp --help to see what your installed version supports. Also note that codex mcp add writes to your user config. For a per-repository setup, write the project file by hand.
An older version of this post showed codex mcp add wp-blog --scope user. The Codex documentation does not list a --scope flag for that command, so we removed it. If you copied that line, delete the flag.
Which MCP config file does each client read?
The three clients people ask about use three different files, and mixing them up is the most common reason a server “does not show up”. This table is the short version.
Client | Per-repository file | User-wide file | Format |
|---|---|---|---|
Codex CLI (and the IDE extension) |
|
| TOML, |
Claude Code |
|
| JSON, |
Claude Desktop | None. One file per machine. |
| JSON, |
Per the Codex MCP documentation, the ChatGPT desktop app, the Codex CLI and the IDE extension share the same configuration, so a server added in one place appears in the others. Claude Desktop is different: it has no project concept, so you cannot give one repository its own Desktop-only server. Use Claude Code for that.
How do Claude Code scopes work: local, project and user?
Claude Code stores a server in one of three scopes, chosen with --scope. Local is the default. According to the Claude Code MCP reference, the scopes differ in where they load and who sees them:
Scope | Loads in | Shared with team | Stored in |
|---|---|---|---|
local (default) | The current project only | No |
|
project | The current project only | Yes, through version control |
|
user | All your projects | No |
|
If the same server name is defined in more than one place, the highest-precedence definition wins and the fields are not merged. The order is local, then project, then user, then plugin-provided servers, then claude.ai connectors. That means a stale local entry can silently override the project file your team committed, which explains many “it works for them” reports.
Checked on 15 Nov 2026:
# Remote server over HTTP, shared with the team through .mcp.json
claude mcp add --transport http --scope project docs https://example.com/mcp
# Local stdio server, private to you in this project (local scope is the default)
claude mcp add --transport stdio --env API_KEY=YOUR_KEY mytool -- npx -y example-mcp-server
# Inspect and manage
claude mcp list
claude mcp get mytool
claude mcp remove mytool
# inside a session
/mcpThe -- separator matters. Everything before it is an option for claude, everything after it is the command that starts the server. --env takes several KEY=value pairs, so put another option between it and the server name, as above, or it will swallow the name.
The project file Claude Code writes
Project scope creates or updates .mcp.json. You can also write it yourself. It supports environment variable expansion in command, args, env, url and headers, using ${VAR} or ${VAR:-default}. That is how a committed file stays free of secrets.
{
"mcpServers": {
"wordpress": {
"type": "stdio",
"command": "wp",
"args": [
"--path=${WP_PATH}",
"mcp-adapter", "serve",
"--server=mcp-adapter-default-server",
"--user=${WP_MCP_USER:-mcp-reader}"
]
},
"docs": {
"type": "http",
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
}
}
}Two details from the documentation are worth knowing. First, an entry with a url but no type is read as stdio and skipped, so always write "type": "http" for remote servers. Second, if a variable is unset and has no default, the file still loads with the literal ${VAR} text and shows a warning instead of failing. Read the warning.
Claude Code asks for approval before it uses a project-scoped server from .mcp.json in an interactive session. You can reset those answers with claude mcp reset-project-choices. In non-interactive runs such as claude -p there is no prompt, and project servers load without asking, so block anything you do not want with disabledMcpjsonServers in settings or start with --strict-mcp-config.
How do I set up MCP in Claude Desktop?
Claude Desktop uses one JSON file for the whole machine. Open Settings from the Claude menu, go to the Developer tab, and click Edit Config. That creates the file if it does not exist. The paths are in the table above, and the MCP guide for local servers gives the rest of the steps.
Checked on 15 Nov 2026:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop"
]
}
}
}Quit Claude Desktop completely and reopen it after every edit, because it reads the file at startup. Use absolute paths, not relative ones. If a server does not appear, the guide points to the logs: ~/Library/Logs/Claude on macOS, where mcp.log covers connection failures and mcp-server-NAME.log holds each server’s stderr output. Run the same command by hand in a terminal first. If it fails there, the problem is the server, not Claude.
Moving a Claude Desktop block into Claude Code
You do not have to retype it. Claude Code’s reference describes the conversion: pass the object inside mcpServers to claude mcp add-json. For the filesystem entry above, that looks like this.
# checked on 15 Nov 2026
claude mcp add-json filesystem '{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/Users/username/Desktop"]}'Which MCP transport should I use: stdio or HTTP?
Use stdio for a server that runs on your own machine and Streamable HTTP for a server someone else hosts. The current MCP specification, version 2026-07-28, defines exactly two standard transports. Stdio is newline-delimited messages over the standard streams of a subprocess your client launches. Streamable HTTP sends each message as an HTTP POST to a single endpoint, and the reply arrives as a JSON object or a request-scoped event stream.
What about SSE? The older HTTP+SSE transport is not one of the two standard transports in the current specification. Claude Code’s reference marks --transport sse as deprecated and says to use HTTP where available. Version 2.1.265 and later tries HTTP first and falls back to SSE when a server refuses it. Codex’s documentation lists only stdio and Streamable HTTP. If a vendor still hands you an /sse URL, ask for the /mcp one.
Transport | Runs where | Codex key | Claude Code flag | Use it for |
|---|---|---|---|---|
stdio | A process your client starts |
|
| Local tools, repo scripts, WP-CLI |
Streamable HTTP | A server URL |
|
| Hosted services, shared team servers |
SSE (legacy) | A server URL | Not documented |
| Only a server that offers nothing else |
For a hosted server on Codex, the table keys look like this. Notice that the token is read from an environment variable and never written into the file.
Checked on 15 Nov 2026:
[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_TOKEN"
# optional
enabled_tools = ["search", "fetch"]
tool_timeout_sec = 60The default for auth on HTTP servers is oauth, and codex mcp login <server-name> starts that sign-in. Add --no-browser on a machine with no browser, then paste the redirect URL back into the terminal.
Can I connect WordPress to Codex and Claude over MCP?
Yes, and there is an official path. WordPress 6.9 added the Abilities API to core, which lets plugins register named actions with input schemas and permission checks. The WordPress MCP Adapter is a separate package from the WordPress project that turns those abilities into MCP tools. It is a plugin you install, not part of core. The developer announcement and the GitHub repository describe it. The latest release we found was 0.7.1, published on 16 Oct 2026.
The adapter registers a default server named mcp-adapter-default-server with three meta-tools: one to discover abilities, one to read an ability’s details and one to execute it. Abilities are private by default. A plugin author opts one in by setting a flag in the ability’s registration arguments.
That flag changed name recently, so check which one your plugins use. The announcement shows meta.mcp.public set to true. A core post from 4 Aug 2026 describes WordPress 7.1 adding a unified public flag under meta, which defaults to false, and says the adapter will respect it in its next release. Existing show_in_rest registrations keep working. The adapter’s README accepts both meta.public and meta.mcp.public.
Checked on 15 Nov 2026:
wp_register_ability( 'my-plugin/site-summary', array(
'label' => 'Site summary',
'description' => 'Read-only summary of site counts.',
'category' => 'site',
'execute_callback' => 'my_plugin_site_summary',
'permission_callback' => static function () {
return current_user_can( 'edit_posts' );
},
'meta' => array(
'public' => true,
'show_in_rest' => true,
),
) );We did not run this snippet against a live site for this refresh. We checked the flag names against the two sources above, so treat the argument list as a pattern and confirm it against your WordPress version. The permission callback is the part you should never skip.
Two ways to reach the site
The announcement describes two connections. For local development, use stdio through WP-CLI. For a public site, use HTTP through the @automattic/mcp-wordpress-remote proxy, which authenticates with a WordPress application password. In Codex, the HTTP route is a stdio server that happens to be a proxy.
# checked on 15 Nov 2026 - HTTP route through the proxy
[mcp_servers.wp_remote]
command = "npx"
args = ["-y", "@automattic/mcp-wordpress-remote@latest"]
env_vars = ["WP_API_PASSWORD"]
[mcp_servers.wp_remote.env]
WP_API_URL = "https://yoursite.example/wp-json/mcp/mcp-adapter-default-server"
WP_API_USERNAME = "mcp-reader"Here the password is forwarded from your shell through env_vars, so it never lands in a committed file. Pinning the proxy version instead of @latest is a sensible step once it works, because you are running downloaded code on every start.
For more WordPress-specific choices, including builder-specific servers and a rule for picking between them, read our comparison of four ways to connect an AI agent to WordPress. If you want to write your own server, we have a tutorial for building a WordPress MCP server. Plugin authors planning ahead should read what the 7.3 plan for MCP, Abilities and OAuth means for them.
How do I test that a server actually works?
Test in three steps, in this order. Each one rules out a different failure.
- Run the server command by hand in a terminal. A stdio server should start and wait for input. If it exits or prints an error, fix that before touching any client.
- List what the client sees. Use
codex mcp listorclaude mcp list, and/mcpinside a Claude Code session. A listed server is configured; it is not yet proven to work. - Ask the assistant to call one read-only tool and report the raw result. A structured answer proves the whole chain: config, launch, handshake and tool listing.
Step three exists because a server can connect and still fail to list its tools, and the client may show the failure only in its status screen. One open Claude Code bug report describes exactly that: the error reaches the status views but never the model. If your assistant says it has no such tool, open /mcp before you rewrite your prompt.
How do I use one server in both Codex and Claude without drift?
Keep one source of truth for the launch command, and let each client’s file point at it. The simplest version is a tiny wrapper script committed in the repository, such as scripts/mcp-wordpress.sh, that sets the path and starts the server. Then .codex/config.toml and .mcp.json both call that script.
#!/usr/bin/env bash
# scripts/mcp-wordpress.sh - one launch command for every client
set -euo pipefail
exec wp --path="${WP_PATH:?set WP_PATH}" mcp-adapter serve \
--server=mcp-adapter-default-server --user="${WP_MCP_USER:-mcp-reader}"When Codex and Claude disagree about results, the cause is almost always a different command, a different server version or a different environment, not a protocol difference. The wrapper removes the first two. For the third, remember that a command launched from a desktop app may not see the environment variables your shell exports.
If you only want an overview of what the protocol is and how an agent connects to external tools, our MCP protocol explainer covers that, and our list of MCP servers worth installing for WordPress workflows has concrete servers to try.
How do I keep MCP safe: least privilege, secrets and untrusted servers?
Treat every MCP server as code that runs with your permissions, because it is. The MCP specification says tools represent arbitrary code execution and must be treated with caution, and that descriptions of tool behavior, such as annotations, should be considered untrusted unless they come from a trusted server. Claude Code’s reference opens with the same warning: verify that you trust each server, because servers that fetch external content can expose you to prompt injection.
Least privilege
- Give a WordPress connection its own user with the lowest role that does the job. A read-only reporting task does not need an administrator. Create a dedicated application password for it so you can revoke it alone.
- Limit the tool list. Codex supports
enabled_toolsas an allow list anddisabled_toolsas a deny list, applied after the allow list, plusdefault_tools_approval_modeand a per-tooltools.<tool>.approval_mode. Start withpromptand relax it only for read-only tools. - On the WordPress side, expose only the abilities you mean to. They are private by default, and each carries its own permission callback.
- Keep a staging site for experiments. Point the production entry at a separate, narrower user.
Secrets
- Never write a token or password into a committed file. Use
bearer_token_env_varorenv_varsin Codex, and${VAR}expansion in.mcp.json. - Know what is stored where. Codex stores an OAuth client secret in
config.tomlif you supply one, and its documentation says to keep that file private and out of version control. - Claude Code blanks credential variables such as
ANTHROPIC_API_KEYwhen they appear in a remote server’surlorheaders, so a project file cannot send those credentials to a server it names. Do not rely on that for your own secrets. - Revoke before you remove. Removing a remote server in Claude Code deletes the locally stored OAuth tokens but does not revoke them at the provider. Run
claude mcp logout <name>first.
Untrusted servers and untrusted repositories
- A cloned repository that ships a
.mcp.jsonor a.codex/config.tomlis asking you to run its commands. Read the file before you approve or trust the project. - Pin versions.
npx -y some-server@latestruns whatever was published most recently. Pin an exact version once you have vetted it. - Remember non-interactive modes. Claude Code loads project servers without a prompt in
claude -pruns, so a CI job that checks out untrusted code needs--strict-mcp-configor an explicit block list. - Assume tool output can contain instructions. A server that returns web pages or user comments can carry text meant to steer your assistant. Keep write and publish tools behind approval so injected text cannot act alone.
Common mistakes people report
These are recurring problems from the public issue trackers, paraphrased. Each links to the report, and all were open when we checked on 15 Nov 2026. Open means the behavior may have changed since, so use these as things to watch for rather than permanent facts.
- A broken
.mcp.jsonshows no error. A reported Claude Code bug says an unparseable file, or a reserved server name, produces an empty server list with no message. If your project servers vanish, validate the JSON first. See issue 107289. - Re-adding a Codex server resets it. Users report that running
codex mcp addagain for an existing name silently resets that server’s other settings, and that add and remove rewrite every[mcp_servers.*]entry, dropping comments and unknown keys. Keep the TOML in version control and edit it by hand. See issue 60927 and issue 45432. - A bearer token the shell has, but the client does not. One report says
bearer_token_env_varwas flagged as unset even though the variable existed in the parent shell. Check which process actually launches the client, and what environment it inherited. See issue 41378. - Connected, but no tools. A server can connect and then fail when listing tools, with the error visible in
/mcpandclaude mcp listbut not shown to the model. See issue 99733. - Removing a server leaves its sign-in alive. A report notes that
claude mcp removeleaves a remote server’s OAuth grant active at the provider, whileclaude mcp logoutrevokes it. See issue 105134. - Every server fails at once. A Codex report describes all servers failing together with a “connection closed: initialize response” handshake error. For a stdio server, run the command by hand and check what it prints before it starts. See issue 6020.
What can MCP actually do for a team?
The benefit is not that an assistant can call tools. It is that the tool contract lives in one place, so the assistant, the permissions and the audit trail can change independently. Three jobs show the value most clearly.
- Content operations. An assistant lists posts, creates a draft, attaches tags and runs a pre-publish check, and a person reads the result and approves it. Drafts are reversible, which is why this is a good first job.
- Repository chores. With a server that exposes CI status or dependency data, Codex or Claude Code can read the state, propose a change and run the tests in the repository. The per-repository config files above keep each project’s tools local to it.
- Reporting. A server that reads analytics or search data lets an assistant gather figures and draft a weekly summary. Keep it read-only.
A pattern that holds up across all three is read, act, verify. Read-only tools run freely. Write tools make reversible changes, such as drafts. A verification step checks the result before anything irreversible, such as publishing, and a person approves that last step. Rolling out to a team is mostly deciding which tools sit in which of those three groups.
A rollout checklist
- Pick one server and one repository. Write down who owns it and which account it uses.
- Commit the project config (
.codex/config.tomland.mcp.json) with no secrets in either file. - Document the environment variables each person must set, and where to get the values.
- Start with read-only tools. Add a write tool only after a week of clean read-only use.
- Set approval to prompt for anything that changes data, and remove tools nobody uses.
- Review the config in pull requests like any other code that runs on developer machines.
A prompt that names the stages keeps a run predictable. We use one shaped like the block below with both Codex and Claude, and it works because it states what must not happen as clearly as what should.
Goal: create a draft post about topic X.
Steps: 1) read existing posts for tone, 2) create a DRAFT, 3) suggest tags,
4) run the audit and report the result.
Constraints: do not publish. Stop and ask if the audit fails.Frequently asked questions
Can I run MCP workflows on staging first?
Yes, and you should. Register the staging site as a separate server entry with its own user and test every workflow there before pointing the same tools at production.
Do I need to restart after changing MCP config?
Usually. Claude Desktop reads its file at startup, so quit it fully. For Codex and Claude Code, start a new session after editing a config file. If you changed only a server’s own code, restarting that server is enough.
What if Codex and Claude return different results?
Compare the launch command, the server version and the environment each client passes. Use the wrapper script approach above so the command is identical, then check the environment next.
Is SSE still supported?
Claude Code still accepts it but marks it deprecated, Codex documents only stdio and Streamable HTTP, and the current MCP specification lists only those two as standard transports. Prefer Streamable HTTP wherever the server offers it.
Which MCP specification version is current?
Version 2026-07-28 is the latest dated revision in the specification repository. Earlier dated versions include 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Clients and servers negotiate, so an older server usually still works with a newer client.
Can a repository carry its own MCP servers safely?
It can, as long as you read the config before trusting the project. A committed .codex/config.toml or .mcp.json is a list of commands your machine will run. Treat it like a build script from a stranger.
Sources, all checked on 15 Nov 2026: the Codex MCP documentation, the Claude Code MCP reference, the MCP specification, the local servers guide, the WordPress MCP Adapter announcement, the WordPress 7.1 public flag post and the MCP Adapter repository.





No comments yet