codex mcp-server를 Claude Code에 MCP 서버로 붙이기 — 윈도우 project 범위 실측과 사용 중단 예고 경고

이번에 새로 확인함 — 2026-09-28: OpenAI 공식 문서는 codex mcp-server와 별도 codex-mcp-server 실행 파일이 제거되었다고 안내합니다. 이 글의 연결·호출 성공은 2026-09-17, CLI 0.153.4의 기록입니다. 아래 재현 명령은 해당 기능이 남아 있는 버전에 한정됩니다. 문서가 안내하는 App Server는 별도 JSON-RPC 프로토콜을 쓰므로 Claude Code MCP 설정의 명령만 바꿔 넣을 수 없습니다.

한 줄로

claude mcp add codex-temp --scope project -- codex mcp-server로 프로젝트 설정에 Codex를 MCP 서버로 등록했습니다. 등록 직후에는 ⏸ Pending approval이었고, 그 실행에만 승인을 준 조회에서 ✔ Connected가 나왔습니다. 윈도우에서도 codex를 codex.cmd로 바꾸지 않은 설정 그대로였습니다. 서버는 codex, codex-reply 도구 두 개를 내놓았습니다. 다만 Node 스크립트로 서버(0.153.4)를 직접 띄운 세 번 모두 표준오류에 `warning: codex mcp-server is deprecated and will be removed in a future release.`가 찍혔습니다.

이런 분께

Claude Code 안에서 Codex에게 일을 넘기고 싶은 분. codex mcp-server를 붙였는데 어떤 도구가 생기는지 먼저 알고 싶은 분. 사용자 설정을 건드리지 않고 한 프로젝트에서만 시험해 보고 싶은 분.

실측 환경

먼저 도움말

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

Usage: codex mcp-server [OPTIONS]

옵션은 -c, --config <key=value>, --strict-config, --enable, --disable, -h, --help가 나옵니다. 도움말 첫 줄에 stdio라고 적혀 있어서, Claude Code에도 stdio 서버로 등록했습니다. codex --help 명령 목록의 설명도 Start Codex as an MCP server (stdio)였고, 여기에는 사용 중단 표시가 없었습니다.

1단계 — project 범위로 추가

claude mcp add --help에 따르면 --scope 기본값은 local입니다. 개인 설정 파일(~/.claude.json)을 건드리지 않으려고 --scope project를 붙였습니다. 평소 쓰는 서버 이름과 겹치지 않게 이름은 codex-temp로 했습니다.

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

만들어진 .mcp.json(162바이트)입니다.

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

2단계 — 상태 확인과 승인

$ 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에서도 codex-temp: codex mcp-server - ⏸ Pending approval (run claude to approve)였습니다. 프로젝트 서버는 승인 전에는 연결하지 않습니다. 승인 절차는 Claude Code에 MCP 서버 붙이기에 따로 적었습니다. 이번에는 대화 세션을 열지 않고, 조회 명령에 --settings '{"enableAllProjectMcpServers": true}'를 붙였습니다.

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도 codex-temp: codex mcp-server - ✔ Connected였습니다. 설정의 command에 확장자 없이 codex만 적었는데도 연결됐습니다.

3단계 — 어떤 도구가 생기나 (JSON-RPC로 직접 묻기)

claude mcp get은 연결 상태와 서버 설정(범위·명령·인자)을 보여 주지만, 도구 목록은 나오지 않았습니다. 도구 목록을 보려고 Node 스크립트로 codex mcp-server를 띄우고, 표준입력에 한 줄짜리 JSON-RPC 메시지를 차례로 보냈습니다. 순서는 initialize → notifications/initialized → tools/list입니다.

당시 스크립트는 Windows에서 codex.cmd를 찾게 하려고 shell: true를 썼고 Node가 DEP0190 경고를 찍었습니다. 응답 처리 부분이 생략된 예제 대신, 아래 「이번에 새로 확인함」 절에 완전한 mcp-smoke.mjs 다운로드와 실행 순서를 추가했습니다. 새 클라이언트는 당시 스크립트 원본이 아닙니다.

[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"]

(initialize 응답은 줄 바꿈을 줄였고, serverInfo의 user_agent 값은 뺐습니다.)

두 도구의 입력 항목입니다. 영어는 스키마 문구를 옮긴 것이고(일부 생략), 한국어 칸은 요약입니다.

4단계 — 도구 한 번 불러 보기

같은 스크립트로 tools/list 뒤에 codex 도구를 한 번 불렀습니다. 인자는 prompt: "Reply with the single word OK.", sandbox: "read-only", approval-policy: "never", cwd는 실험 폴더였습니다.

[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": "***(가림)",
  "content": "OK"
 },
 "content": [
  {
   "type": "text",
   "text": "OK"
  }
 ]
}

(알림 줄은 일부만 남겼습니다. 실제로는 mcp_startup_update, raw_response_item, token_count 등이 더 왔습니다.)

호출부터 결과까지 약 5초였습니다. 결과가 오기 전에 codex/event라는 이름의 알림이 여러 개 먼저 왔습니다. 결과의 structuredContent.threadId가 이어서 물을 때 codex-reply에 넘길 값입니다.

5단계 — 지우기

$ 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

지운 뒤 .mcp.json은 {"mcpServers": {}}(22바이트)만 남았고, claude mcp list에서 codex-temp가 들어간 줄은 0개였습니다. grep -c로 ~/.claude.json에서 longtail_B2와 codex-temp가 들어간 줄 수를 세어 보니 둘 다 0이었습니다(파일 내용은 출력하지 않음).

이번에 새로 확인함 — 2026-09-28

이 절은 재현용 클라이언트를 보완한 것이며 Codex의 새 실행 결과가 아닙니다. 먼저 codex --version과 codex mcp-server --help로 설치된 버전과 명령 유무를 확인합니다. 명령이 제거된 버전에서는 여기서 중단합니다. 명령이 남아 있다면 등록·모델 호출 전에 다음 순서로 직접 확인할 수 있습니다.

단계 1

새 빈 시험 폴더를 만들고 터미널에서 그 폴더로 이동합니다. mcp-smoke.mjs를 그 안에 저장합니다. 파일 바로 옆에 SDK를 설치합니다.

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

단계 2

같은 폴더에 새 request.json 파일을 만들고 아래 내용을 저장합니다. cwd: "."는 이 시험 폴더를 뜻합니다. 인자를 파일로 넘겨 셸의 JSON 따옴표 문제를 피합니다.

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

단계 3

먼저 도구 목록만 확인합니다. codex가 직접 실행 가능한 환경의 명령입니다.

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

단계 4

이어서 도구 호출을 시험하려면 실행합니다. 이 단계는 실제 Codex 세션을 시작하므로 설치된 CLI의 로그인과 사용 권한이 필요합니다.

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

Windows의 npm 설치처럼 실행 대상이 codex.cmd이면 PowerShell에서 cmd.exe를 명시하는 형태를 사용합니다. 아래 Windows 명령은 이번에 실행하지 못했습니다.

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

새 클라이언트의 표준출력은 JSONL입니다. event: "connected"와 server, 그다음 event: "tools"와 names가 나옵니다. 목록에 codex가 있으면 호출을 진행하고 event: "result", tool: "codex", result를 출력합니다. 성공 판정은 종료 코드 0에 더해 실제 result의 답을 읽어 해야 합니다. OK가 나올지는 아래 fixture 시험이 보장하지 않습니다. 서버의 표준오류는 별도로 보이며, 통신·목록·호출 오류와 result.isError는 종료 코드 1로 처리합니다. 요청 제한 시간 기본값은 60초입니다.

이번 실제 확인 범위: Linux, Node v24.19.0, SDK 1.30.1과 Zod 4.6.5를 사용하는 로컬 시험 서버에서 초기화·도구 목록·add(2, 3) 결과 5 및 종료 코드 0을 확인했습니다. 도구가 isError를 반환한 경우와 목록에 없는 도구 요청은 각각 1로 끝났습니다. 이는 클라이언트의 프로토콜·실패 처리 시험입니다. 이 환경에는 Codex 실행 파일·로그인·Windows가 없으므로 codex 도구, 모델 응답, cmd.exe 실행, Claude Code 대화 연결은 이번에 검증하지 않았습니다.

결과

사용 중단 경고에 대해

2026-09-17 당시 경고 문구는 "앞으로의 릴리스에서 제거될 예정"이라는 내용뿐이었습니다. 대신 쓸 명령은 경고에도, codex mcp-server --help에도 나오지 않았습니다. claude mcp get과 list의 출력에는 이 경고가 나타나지 않았습니다. 2026-09-28 공식 문서에서 새로 확인한 제거·마이그레이션 안내는 글 맨 위에 구분해 두었습니다.

실패한 것

추가·조회·직접 호출·제거는 모두 성공했습니다. 로그에 남은 0이 아닌 종료 코드는 실험 폴더가 깃 저장소가 아닌지 본 git rev-parse(128)와, 제거 뒤 문자열이 없음을 확인한 grep -c(일치 0건이라 1)입니다. 다만 Claude Code 대화 세션 안에서 codex-temp 도구를 실제로 불러 보지는 못했습니다. 대화형 세션을 열지 않는 조건이라, 도구 목록과 호출은 Node 스크립트로 서버에 직접 붙어서 확인했습니다.

확인하지 않은 것

• Claude Code 대화 세션에서 이 서버의 도구가 어떤 이름으로 보이는지, 승인 대화상자의 모양.
• codex-reply로 이어서 묻기, workspace-write 샌드박스에서의 파일 쓰기.
• 2026-09-17 원래 실측에서는 사용 중단 이후의 대안을 시험하거나 OpenAI 공식 문서를 조회하지 않았습니다. 2026-09-28 문서 확인은 위 추가 기록에 구분했으며, App Server로의 마이그레이션을 실행한 것은 아닙니다.
• local·user 범위로 추가했을 때의 모양(개인 설정 보호를 위해 하지 않음).
• codex 0.153.4 외 버전, 명령 프롬프트(cmd.exe)·WSL에서의 동작.

함께 보기

• Claude Code에 MCP 서버 붙이기
• codex exec stdin 대기 해결
• Codex 샌드박스 read-only와 workspace-write 비교
• Node로 최소 MCP 서버 만들기
• codex doctor 진단 결과 읽는 법