Using MCP Tools with Codex and Claude: Setup, Benefits, and Use Cases

Set up MCP per repository with Codex and Claude Code: config files, scopes, transports, WordPress MCP Adapter and security. Checked 15 Nov 2026.

Two config file cards, repo/.codex/config.toml and repo/.mcp.json, each defining a WordPress MCP server

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 --help

Be 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)

.codex/config.toml (trusted projects only)

~/.codex/config.toml

TOML, [mcp_servers.name] tables

Claude Code

.mcp.json in the repo root (project scope)

~/.claude.json (user and local scopes)

JSON, mcpServers object

Claude Desktop

None. One file per machine.

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows

JSON, mcpServers object

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

~/.claude.json, under the project path

project

The current project only

Yes, through version control

.mcp.json in the project root

user

All your projects

No

~/.claude.json

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
/mcp

The -- 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

command, args, env

--transport stdio or no flag, then --

Local tools, repo scripts, WP-CLI

Streamable HTTP

A server URL

url, bearer_token_env_var

--transport http

Hosted services, shared team servers

SSE (legacy)

A server URL

Not documented

--transport sse, deprecated

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 = 60

The 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.

  1. 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.
  2. List what the client sees. Use codex mcp list or claude mcp list, and /mcp inside a Claude Code session. A listed server is configured; it is not yet proven to work.
  3. 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_tools as an allow list and disabled_tools as a deny list, applied after the allow list, plus default_tools_approval_mode and a per-tool tools.<tool>.approval_mode. Start with prompt and 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_var or env_vars in Codex, and ${VAR} expansion in .mcp.json.
  • Know what is stored where. Codex stores an OAuth client secret in config.toml if 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_KEY when they appear in a remote server’s url or headers, 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.json or a .codex/config.toml is asking you to run its commands. Read the file before you approve or trust the project.
  • Pin versions. npx -y some-server@latest runs 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 -p runs, so a CI job that checks out untrusted code needs --strict-mcp-config or 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.json shows 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 add again 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_var was 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 /mcp and claude mcp list but not shown to the model. See issue 99733.
  • Removing a server leaves its sign-in alive. A report notes that claude mcp remove leaves a remote server’s OAuth grant active at the provider, while claude mcp logout revokes 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

  1. Pick one server and one repository. Write down who owns it and which account it uses.
  2. Commit the project config (.codex/config.toml and .mcp.json) with no secrets in either file.
  3. Document the environment variables each person must set, and where to get the values.
  4. Start with read-only tools. Add a write tool only after a week of clean read-only use.
  5. Set approval to prompt for anything that changes data, and remove tools nobody uses.
  6. 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.

Varun Dubey

Written by

Varun Dubey

Varun Dubey runs Wbcom Designs, the WordPress studio he founded in India in 2009. He has spent sixteen years building on WordPress and BuddyPress, shipping client work and products such as Reign, BuddyX, Jetonomy and MediaVerse, and has been putting Claude and OpenAI workflows into production since 2023. He writes up what the studio learns along the way.

More about Varun

No comments yet