AI 해결 노트 · 2026-09-17 · 실측 2026-09-17

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

한 줄로

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입니다.

const { spawn } = require('child_process');
const p = spawn('codex', ['mcp-server'], { shell: true, stdio: ['pipe', 'pipe', 'pipe'] });
const send = (m) => p.stdin.write(JSON.stringify(m) + '\n');
send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {
  protocolVersion: '2025-06-18', capabilities: {},
  clientInfo: { name: 'longtail-probe', version: '0.0.1' } } });
// id 1 응답이 오면 notifications/initialized 와 { id: 2, method: 'tools/list' } 를 보냄

(응답을 줄 단위로 읽어 출력하는 부분은 줄였습니다. shell: true는 윈도우에서 codex.cmd를 찾게 하려고 넣었고, Node가 DEP0190 경고를 찍었습니다.)

[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이었습니다(파일 내용은 출력하지 않음).

결과

사용 중단 경고에 대해

경고 문구는 "앞으로의 릴리스에서 제거될 예정"이라는 내용뿐이었습니다. 대신 쓸 명령은 경고에도, codex mcp-server --help에도 나오지 않았습니다. 지금 붙여 쓰더라도 codex를 업데이트한 뒤에는 claude mcp get으로 연결 상태를 다시 확인하는 편이 안전합니다. claude mcp get과 list의 출력에는 이 경고가 나타나지 않았습니다.

실패한 것

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

확인하지 않은 것

• Claude Code 대화 세션에서 이 서버의 도구가 어떤 이름으로 보이는지, 승인 대화상자의 모양.
• codex-reply로 이어서 묻기, workspace-write 샌드박스에서의 파일 쓰기.
• 사용 중단 이후 대신 쓸 방법. OpenAI 공식 문서도 이번에는 찾아보지 않았습니다.
• local·user 범위로 추가했을 때의 모양(개인 설정 보호를 위해 하지 않음).
• codex 0.153.4 외 버전, 명령 프롬프트(cmd.exe)·WSL에서의 동작.

함께 보기

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