AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Attaching codex mcp-server to Claude Code as an MCP server — project scope on Windows, plus the deprecation warning

Newly checked — 2026-09-28: OpenAI's official documentation now says codex mcp-server and the standalone codex-mcp-server binary have been removed. The successful connections and calls in this note are historical measurements from 2026-09-17 with CLI 0.153.4. The reproduction commands below apply only to versions that retain the feature. The documented App Server migration uses a separate JSON-RPC protocol; replacing the command in Claude Code's MCP configuration is not sufficient.

The short version

claude mcp add codex-temp --scope project -- codex mcp-server registers Codex as an MCP server in the project config. Right after adding it the status was ⏸ Pending approval, and a query with approval granted for that invocation alone returned ✔ Connected. On Windows this worked with codex as written, no change to codex.cmd. The server exposed two tools, codex and codex-reply. That said, all three times we launched the server (0.153.4) directly from a Node script, stderr carried `warning: codex mcp-server is deprecated and will be removed in a future release.`

Who this is for

You want to hand work off to Codex from inside Claude Code. You want to know which tools codex mcp-server gives you before you attach it. Or you want to try it in a single project without touching your user settings.

What we tested on

Start with the help text

$ codex mcp-server --help
Start Codex as an MCP server (stdio)

Usage: codex mcp-server [OPTIONS]

The options listed are -c, --config <key=value>, --strict-config, --enable, --disable, and -h, --help. The first line says stdio, so that is how we registered it with Claude Code. The description in the codex --help command list was also Start Codex as an MCP server (stdio), with no deprecation marker there.

Step 1 — add it at project scope

Per claude mcp add --help, the --scope default is local. To leave the personal settings file (~/.claude.json) alone, we passed --scope project. We named it codex-temp so it would not collide with the server names we use day to day.

cd /c/Users/User/AppData/Local/Temp/longtail_B2/proj
claude mcp add codex-temp --scope project -- codex mcp-server

Added stdio MCP server codex-temp with command: codex mcp-server to project config
File modified: C:\Users\User\AppData\Local\Temp\longtail_B2\proj\.mcp.json

The resulting .mcp.json (162 bytes):

{
  "mcpServers": {
    "codex-temp": {
      "type": "stdio",
      "command": "codex",
      "args": [
        "mcp-server"
      ],
      "env": {}
    }
  }
}

Step 2 — status and approval

$ claude mcp get codex-temp
codex-temp:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: stdio
  Command: codex
  Args: mcp-server
  Environment:

To remove this server, run: claude mcp remove codex-temp -s project

claude mcp list likewise showed `codex-temp: codex mcp-server - ⏸ Pending approval (run claude to approve). Project servers are not connected to before approval. The approval procedure is written up in [Adding an MCP server to Claude Code](/en/notes/claude-code-mcp-add-windows). Here, rather than opening a chat session, we appended --settings '{"enableAllProjectMcpServers": true}'` to the query command.

claude --settings '{"enableAllProjectMcpServers": true}' mcp get codex-temp

codex-temp:
  Scope: Project config (shared via .mcp.json)
  Status: ✔ Connected
  Type: stdio
  Command: codex
  Args: mcp-server

claude mcp list with the same option also reported codex-temp: codex mcp-server - ✔ Connected. It connected even though command was plain codex with no extension.

Step 3 — which tools appear (asking over JSON-RPC directly)

claude mcp get shows connection status and the server's configuration (scope, command, args), but not the tool list. To see the tools, we launched codex mcp-server from a Node script and wrote single-line JSON-RPC messages to its stdin, in this order: initialize → notifications/initialized → tools/list.

The original script used shell: true so Windows could find codex.cmd, and Node emitted DEP0190. The response-handling code was omitted from the original example. A complete mcp-smoke.mjs download and runnable steps are now provided under "Newly checked" below. This client is a new replacement, not the original probe.

[stderr] warning: `codex mcp-server` is deprecated and will be removed in a future release.
[0.2s] initialize result: {
 "protocolVersion": "2025-06-18",
 "capabilities": { "tools": { "listChanged": true } },
 "serverInfo": { "name": "codex-mcp-server", "title": "Codex", "version": "0.153.4", ... }
}
[0.2s] tools/list: 2 tools
--- codex
description: Run a Codex session. Accepts configuration parameters matching the Codex Config struct.
inputSchema.required: ["prompt"]
--- codex-reply
description: Continue a Codex conversation by providing the thread id and prompt.
inputSchema.required: ["prompt"]

(Line breaks in the initialize response are condensed, and the user_agent value in serverInfo is omitted.)

The input fields of the two tools. The quoted text comes from the schema (partly abridged); the right-hand notes summarize.

Step 4 — calling a tool once

Using the same script, we followed tools/list with one call to the codex tool. The arguments were prompt: "Reply with the single word OK.", sandbox: "read-only", approval-policy: "never", and cwd set to the test folder.

[0.5s] notification codex/event type=session_configured
[0.5s] notification codex/event type=task_started
[5.0s] notification codex/event type=agent_message_content_delta
[5.2s] notification codex/event type=agent_message
[5.2s] notification codex/event type=task_complete
[5.2s] tools/call result: {
 "structuredContent": {
  "threadId": "***(redacted)",
  "content": "OK"
 },
 "content": [
  {
   "type": "text",
   "text": "OK"
  }
 ]
}

(Only some notification lines are kept. In practice mcp_startup_update, raw_response_item, token_count and others also arrived.)

Call to result took about 5 seconds. Several notifications named codex/event arrived before the result did. The structuredContent.threadId in the result is the value you pass to codex-reply to continue the conversation.

Step 5 — remove it

$ claude mcp remove codex-temp --scope project
Removed MCP server codex-temp from project config
File modified: C:\Users\User\AppData\Local\Temp\longtail_B2\proj\.mcp.json

After removal .mcp.json held only {"mcpServers": {}} (22 bytes), and claude mcp list had zero lines containing codex-temp. Counting lines in ~/.claude.json containing longtail_B2 and codex-temp with grep -c gave 0 for both (we never printed the file contents).

Newly checked — 2026-09-28

This section supplies a complete reproduction client; it is not a new Codex run. First check codex --version and codex mcp-server --help for your installed version and command availability. Stop here if the command has been removed. If it remains available, these steps let you inspect the server directly before registering it or making a model call.

Step 1

Create a new empty test directory and enter it in your terminal. Save mcp-smoke.mjs there, then install the SDK next to the file.

npm init -y
npm install @modelcontextprotocol/sdk@1.30.1

Step 2

Create a new request.json in that same directory with the full contents below. cwd: "." refers to this test directory. Passing arguments through a file avoids shell quoting of JSON.

{
  "prompt": "Reply with the single word OK.",
  "sandbox": "read-only",
  "approval-policy": "never",
  "cwd": "."
}

Step 3

List tools first. This command applies where codex is directly executable.

node mcp-smoke.mjs -- codex mcp-server

Step 4

To test the tool call, run the following. This step starts a real Codex session and requires authentication and access through the installed CLI.

node mcp-smoke.mjs --call codex --args-file request.json --timeout 60000 -- codex mcp-server

For an npm installation on Windows where the launcher is codex.cmd, explicitly invoke cmd.exe from PowerShell. These Windows commands were not run in this check.

node mcp-smoke.mjs -- cmd.exe /d /c codex mcp-server
node mcp-smoke.mjs --call codex --args-file request.json --timeout 60000 -- cmd.exe /d /c codex mcp-server

The new client's stdout is JSONL: an event: "connected" row with server, followed by event: "tools" with names. If codex is advertised, a requested call proceeds and prints event: "result", tool: "codex", and result. Check exit code 0 and read the actual answer in result; the fixture test below does not guarantee OK. Server stderr is separate. Transport, listing, and call errors, plus result.isError, produce exit code 1. The default request timeout is 60 seconds.

Actually checked this time: on Linux with Node v24.19.0, SDK 1.30.1, and Zod 4.6.5, a local fixture server completed initialization, tool listing, and add(2, 3) returning 5 with exit code 0. A tool returning isError and a request for an unadvertised tool each exited 1. These are client protocol and failure-handling tests. This environment has no Codex binary, authentication, or Windows, so the Codex tool, model response, cmd.exe launch, and Claude Code chat integration were not retested.

Results

About that deprecation warning

On 2026-09-17, the warning said only that removal would occur in a future release. No replacement command appeared in the warning or in codex mcp-server --help. The warning did not appear in claude mcp get or list. The removal and migration guidance newly found in the official documentation on 2026-09-28 is separated at the top of this note.

What didn't work

Adding, querying, calling directly, and removing all succeeded. The only nonzero exit codes in the log came from git rev-parse (128), used to confirm the test folder was not a git repo, and grep -c (1, because it matched nothing) when verifying the strings were gone after removal. What we did not manage was calling a codex-temp tool from inside a Claude Code chat session. Since the condition was to avoid opening an interactive session, the tool list and the call were done by attaching to the server directly from a Node script.

What we did not check

• What name these tools appear under in a Claude Code chat session, and what the approval dialog looks like.
• Continuing a conversation with codex-reply, and writing files under the workspace-write sandbox.
• The original 2026-09-17 run did not test a replacement or consult OpenAI's official docs. The 2026-09-28 documentation check is separated above; we have not performed an App Server migration.
• What local and user scope additions look like (skipped to protect personal settings).
• codex versions other than 0.153.4, and behavior in Command Prompt (cmd.exe) or WSL.

See also

• Adding an MCP server to Claude Code
• Fixing codex exec hanging on stdin
• Codex sandbox: read-only vs workspace-write
• Building a minimal MCP server in Node
• Reading codex doctor diagnostics