AI Dad

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

Codex CLI config.toml에 MCP 서버 넣기 — codex mcp add가 파일에 쓰는 모양 (윈도우, 임시 CODEX_HOME 실측)

한 줄로

codex mcp add 이름 -- 명령 인자...를 치면 config.toml에 [mcp_servers.이름] 표가 생깁니다. 이번에 넣은 윈도우 경로는 작은따옴표로 저장됐고, 같은 경로를 큰따옴표 안에 역슬래시 그대로 적자 codex mcp list가 TOML 오류로 실패했습니다.

이번 실측은 진짜 설정을 건드리지 않으려고 임시 폴더를 CODEX_HOME으로 잡고 했습니다.

이런 분께

실측 환경

항목값
OSWindows 11 Home (10.0.26200)
셸Git Bash
codexcodex-cli 0.153.4
CODEX_HOMEC:\Users\User\AppData\Local\Temp\longtail_A\codex_home (끝나고 삭제)
붙인 서버npx -y @modelcontextprotocol/server-filesystem <폴더> (설정만, 실행 안 함)
실제 ~/.codex/config.toml실측 전후 해시 앞 16자리 46744fd1e59cbe09, 수정 시각 2026-09-17 16:44:14 동일

1. 쓸 수 있는 명령

codex mcp --help에 나온 하위 명령은 list, get, add, remove, login, logout, help입니다. add의 사용법은 이렇습니다.

Usage: codex mcp add [OPTIONS] <NAME> (--url <URL> | -- <COMMAND>...)
...
      --env <KEY=VALUE>
          Environment variables to set when launching the server. Only valid with stdio servers
...
      --url <URL>
          URL for a streamable HTTP MCP server

로컬에서 명령으로 띄우는 서버는 -- 뒤에 명령을, 원격 HTTP 서버는 --url을 씁니다. 이 글은 앞쪽만 다룹니다.

2. 임시 CODEX_HOME 준비

CODEX_HOME은 폴더가 먼저 있어야 합니다. 없는 경로를 주면 종료 코드 1로 멈춥니다.

Error: failed to resolve CODEX_HOME

Caused by:
    CODEX_HOME points to "C:\\Users\\User\\AppData\\Local\\Temp\\longtail_A\\codex_home", but that path does not exist

폴더를 만든 뒤에는 빈 상태로 잘 떴습니다.

mkdir -p /c/Users/User/AppData/Local/Temp/longtail_A/codex_home
export CODEX_HOME='C:\Users\User\AppData\Local\Temp\longtail_A\codex_home'
codex mcp list
No MCP servers configured yet. Try `codex mcp add my-tool -- my-command`.

임시 폴더를 %TEMP% 아래에 뒀더니 list·add·get 때마다 이 경고가 표준오류에 붙었습니다. 동작에는 지장이 없었습니다.

WARNING: proceeding, even though we could not create PATH aliases: Refusing to create helper binaries under temporary dir "C:\\Users\\User\\AppData\\Local\\Temp\\" ...

3. 서버 추가와 만들어진 파일

codex mcp add fs -- npx -y @modelcontextprotocol/server-filesystem 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root'
Added global MCP server 'fs'.

빈 폴더에 145바이트짜리 config.toml이 새로 생겼습니다.

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root']

역슬래시가 든 경로만 작은따옴표로 적혔습니다. TOML에서 작은따옴표 문자열은 역슬래시를 그대로 둡니다.

codex mcp list와 codex mcp get fs로 읽어 보면 이렇게 나옵니다.

Name  Command  Args                                                                                            Env  Cwd  Status   Auth
fs    npx      -y @modelcontextprotocol/server-filesystem C:\Users\User\AppData\Local\Temp\longtail_A\fs_root  -    -    enabled  Unsupported
fs
  enabled: true
  transport: stdio
  command: npx
  args: -y @modelcontextprotocol/server-filesystem C:\Users\User\AppData\Local\Temp\longtail_A\fs_root
  cwd: -
  env: -
  remove: codex mcp remove fs

codex mcp list --json은 "transport": {"type": "stdio", ...}, "auth_status": "unsupported", "startup_timeout_sec": null, "tool_timeout_sec": null 같은 필드를 함께 보여 줬습니다.

4. 환경 변수, 손으로 고친 값, 삭제

--env를 붙이면 하위 표가 따로 생깁니다.

codex mcp add fs2 --env DEMO_FLAG=1 -- npx -y @modelcontextprotocol/server-filesystem 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root'
[mcp_servers.fs2]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root']

[mcp_servers.fs2.env]
DEMO_FLAG = "1"

add에는 시작 대기 시간을 정하는 옵션이 없어서, [mcp_servers.fs] 아래에 startup_timeout_sec = 30을 손으로 넣었습니다. codex mcp get fs에 startup_timeout_sec: 30이 나타났고, list --json에는 "startup_timeout_sec": 30.0으로 읽혔습니다.

그다음 codex mcp remove fs2를 돌리자 Removed global MCP server 'fs2'.와 함께 파일이 이렇게 다시 쓰였습니다.

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", 'C:\Users\User\AppData\Local\Temp\longtail_A\fs_root']
startup_timeout_sec = 30.0

fs2 두 표가 사라진 것과 별개로, 손으로 적은 30이 30.0으로 바뀌었습니다. codex mcp add/remove는 파일 전체를 다시 쓰는 것으로 보이니, 직접 단 주석이나 서식이 남는지는 실제 파일에 쓰기 전에 사본으로 확인하는 게 좋겠습니다(주석 보존 여부는 재지 않았습니다).

5. 윈도우에서 흔한 실수: 큰따옴표 안의 역슬래시

별도 임시 폴더에 손으로 이렇게 적었습니다.

[mcp_servers.fs]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\User\AppData\Local\Temp\longtail_A\fs_root"]

codex mcp list가 종료 코드 1로 멈췄습니다.

Error: failed to load bootstrap configuration

Caused by:
    0: ...\codex_home_bad\config.toml:3:63: too few unicode value digits, expected unicode hexadecimal value
    1: TOML parse error at line 3, column 63
         |
       3 | args = ["-y", "@modelcontextprotocol/server-filesystem", "C:\Users\User\AppData\Local\Temp\longtail_A\fs_root"]
         |                                                               ^
       too few unicode value digits, expected unicode hexadecimal value

63번째 칸은 C:\Users에서 \U 바로 뒤의 s입니다. 오류 문구대로, 큰따옴표 문자열 안의 \U를 유니코드 값의 시작으로 읽었는데 그 뒤에 16진수가 오지 않아 멈춘 것입니다. codex가 스스로 쓴 모양(3절)처럼 작은따옴표로 감싸면 됩니다. 이 오류로 다른 codex 명령도 막히는지는 확인하지 않았고, 이번에 본 것은 codex mcp list 하나입니다.

결과

확인 항목결과
없는 CODEX_HOMEfailed to resolve CODEX_HOME, 종료 코드 1
빈 CODEX_HOME에서 listNo MCP servers configured yet.
add fs -- npx ...[mcp_servers.fs] 표 생성, 윈도우 경로는 작은따옴표
add --env[mcp_servers.<이름>.env] 하위 표 생성
stdio 서버의 Auth 칸Unsupported
손으로 넣은 startup_timeout_sec = 30get에 반영, remove 뒤 파일에 30.0으로 다시 쓰임
큰따옴표 안 C:\UsersTOML parse error at line 3, column 63, 종료 코드 1
인증 없는 임시 홈에서 codex exec401 Unauthorized, 종료 코드 1 (후속 확인 명령까지 포함한 전체 16.1초)
실제 ~/.codex/config.toml전후 해시·수정 시각 같음

실패한 것

임시 CODEX_HOME에는 로그인 정보가 없어서, MCP 서버를 실제로 붙인 채 codex에게 일을 시키는 단계는 하지 못했습니다. 설정 없는 빈 임시 홈에서 질문을 한 번 던져 보니 이렇게 끝났습니다.

ERROR: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header, url: https://api.openai.com/v1/responses, ...

그 전에 WebSocket 연결이 401 Unauthorized로 거듭 실패해 Reconnecting... 5/5까지 갔고, Falling back from WebSockets to HTTPS transport 경고 뒤 HTTPS로 다시 Reconnecting... 1/5부터 5/5까지 시도했습니다. 최종 종료 코드는 1이었습니다. 이 실행은 MCP 서버가 npx로 내려받아지지 않도록 설정이 빈 홈에서 했습니다. 인증 파일을 복사해 오는 방법은 쓰지 않았습니다.

확인하지 않은 것

함께 보기