Codex 샌드박스 MCP 서버를 실행하려면 ~/.codex/config.toml에 권한 프로파일을 정의한 다음, 서버의 command가 codex sandbox --permission-profile <name> -- 뒤에 원래 명령을 붙인 형태를 가리키도록 설정하세요. Codex는 기본적으로 stdio MCP 서버를 샌드박스 처리하지 않으므로, 이 래퍼 없이 실행되는 npx 서버는 사용자의 모든 권한으로 동작합니다.
OpenAI의 엔지니어링 글 Inside the Codex sandbox(2026년 11월 18일 게시)에서 이 점을 분명히 밝혔습니다. Codex는 서버가 어떤 파일이나 네트워크 서비스에 접근하는지 안정적으로 추정할 수 없기 때문에, 서버의 실행 명령을 손대지 않고 그대로 둡니다. npx -y로 추가하는 모든 MCP 서버는 홈 폴더를 읽고, 사용자가 쓰기 가능한 모든 위치에 쓰고, 인터넷상의 어떤 호스트와도 통신할 수 있습니다.
이제 Apidog MCP Server용 프로파일을 만들고, 네트워크를 끈 상태로 로컬 OpenAPI 파일에 묶은 뒤, codex sandbox로 프로파일이 제대로 동작하는지 확인하고, 마지막으로 Apidog CLI를 사용해 반복 작업을 코딩 에이전트에 맡겨 보겠습니다.
Codex가 stdio MCP 서버를 샌드박스로 감싸지 않는 이유
stdio MCP 서버는 Codex가 실행하고 표준 입출력으로 대화하는 로컬 프로그램입니다. Codex는 모델이 실행하는 셸 명령은 샌드박스로 격리하지만, MCP 서버를 실행하는 명령은 격리하지 않습니다. 서버가 어떤 파일이나 호스트에 접근하는지 알 수 없기 때문입니다. 그래서 서버는 사용자의 모든 권한을 그대로 물려받습니다.
모델이 실행하는 명령에는 내장 :workspace 프로파일이 적용됩니다. 워크스페이스 내부에만 쓰기 가능하고, .git과 .codex는 읽기 전용이며, 광범위한 읽기는 허용되지만 네트워크는 차단됩니다. 반면 [mcp_servers]에 등록된 MCP 서버에는 이런 보호가 전혀 적용되지 않습니다.
이 격차가 중요한 이유는 MCP 서버가 실행 시점에 받아오는 서드파티 코드이기 때문입니다. 일반적인 설정은 다음과 같습니다:
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@1.0.0"]
npx -y는 묻지도 따지지도 않고 패키지를 다운로드해 곧바로 실행합니다. 만약 그 패키지가 변조된 상태라면, .env 파일과 SSH 키를 읽어 어디론가 전송할 수도 있습니다. 더 넓은 위협 모델은 MCP 보안 정책 가이드에서 다루고 있으며, 이 글은 Codex 설정의 단 하나의 구멍을 메우는 데 집중합니다.
Codex 권한 프로파일의 동작 방식
권한 프로파일은 config.toml의 [permissions] 아래에 정의되는, 이름이 붙은 파일시스템 및 네트워크 규칙의 모음입니다. OpenAI의 글과 Codex 권한 문서에서는 세 가지 파일시스템 수준을 설명합니다:
| 값 | 효과 |
|---|---|
read |
읽기 전용 접근 |
write |
읽기 및 쓰기 접근 |
deny |
접근 차단 |
핵심 키는 세 가지입니다:
":root" = "read"는 광범위한 읽기를 허용하며, Node.js와 npm이 자체 파일을 로드하는 데 필요합니다."~/.npm" = "write"같은 경로는 해당 폴더에만 쓰기를 허용합니다.":workspace_roots"테이블은 각 워크스페이스 루트를 기준으로 규칙을 적용합니다."**/*.env" = "deny"로 그 아래의 모든.env파일을 차단할 수 있습니다.
네트워크는 세 가지 모드를 지원합니다. 완전 차단, Codex 프록시를 통해 도메인 허용 목록을 적용하는 방식, 그리고 완전 허용입니다.

오픈소스 Codex CLI는 운영체제 수준에서 이 규칙들을 강제합니다. macOS에서는 Seatbelt, Linux에서는 bubblewrap과 seccomp, 그리고 호환되는 Windows 기기에서는 Microsoft의 MXC를 사용합니다. 자식 프로세스도 이 제한을 물려받기 때문에, 서버가 생성하는 모든 프로세스는 동일한 경계 안에 머뭅니다.
1단계: Apidog MCP Server에 가장 안전한 모드 선택하기
Apidog MCP Server(npm의 apidog-mcp-server, 현재 버전 0.0.18)는 두 가지 모드로 동작합니다:
- 프로젝트 모드:
--project-id=<id>와APIDOG_ACCESS_TOKEN을 사용해 네트워크를 통해 Apidog 프로젝트에서 API 문서를 가져옵니다. - OAS 모드:
--oas=<url-or-path>를 사용해 Swagger 또는 OpenAPI 파일을 직접 읽습니다.
로컬 파일을 사용하는 OAS 모드는 네트워크가 전혀 필요 없습니다. 이는 작성 가능한 가장 강력한 프로파일이므로, 이 글의 주요 예제로 사용합니다. Apidog CLI가 샌드박스 밖에서 스펙을 최신 상태로 유지합니다(5단계).
0.0.18 패키지를 살펴보면 서버가 어디에 쓰는지 알 수 있습니다. ~/.apidog-mcp-server(또는 APIDOG_DATA_LOCATION에 지정한 폴더)에 데이터를 캐시하며, 프로젝트 모드에서는 --apidog-api-base-url을 지정하지 않으면 https://api.apidog.com을 호출합니다.
2단계: 권한 프로파일 정의하기
~/.codex/config.toml에 다음을 추가하세요:
[permissions.apidog-mcp.filesystem]
# Node.js와 npm이 자체 파일을 로드할 수 있도록 광범위한 읽기 허용
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp.network]
enabled = false
이제 서버는 스펙을 읽고 두 개의 캐시 폴더에 쓸 수 있습니다. 워크스페이스의 .env 파일은 열 수 없고, 네트워크도 사용할 수 없습니다.
3단계: codex sandbox로 서버 명령 감싸기
이제 단순한 npx 실행 부분을 codex sandbox로 교체하세요. -C 플래그는 작업 디렉터리를 지정하며, 이 디렉터리가 .env 규칙이 적용되는 워크스페이스 루트가 됩니다:
[mcp_servers.pets-api-docs]
command = "codex"
args = [
"sandbox",
"--permission-profile", "apidog-mcp",
"-C", "/Users/you/code/pets-api",
"--",
"npx", "--offline",
"apidog-mcp-server@0.0.18",
"--oas=/Users/you/code/pets-api/openapi.json"
]
세 가지 사항이 중요합니다:
- 버전 고정.
@0.0.18로 고정하면 새 릴리스가 몰래 코드를 바꿔치기할 수 없습니다. npx --offline사용. 네트워크가 꺼져 있으므로npx가 캐시에서 패키지를 찾아야 합니다.- 절대 경로 사용. Codex는
args를 셸을 거치지 않고 그대로 전달하므로~가 확장되지 않습니다.
Apidog README에서는 서버를 문서화하는 API의 이름을 따서 이름을 짓기를 권장합니다. 예를 들어 “Pets API Documentation”처럼 붙이면 모델이 언제 이 서버를 사용해야 하는지 알 수 있습니다.

4단계: 패키지 미리 캐시하고 프로파일이 동작하는지 확인하기
샌드박스는 캐시 폴더에 쓸 수는 있지만 새로 만들 수는 없고, 아무것도 다운로드할 수 없습니다. 샌드박스 밖에서 다음을 한 번 실행하세요:
mkdir -p ~/.apidog-mcp-server
npx -y --package=apidog-mcp-server@0.0.18 -c true
그런 다음 이 프로파일을 신뢰하기 전에 테스트하세요. codex sandbox는 프로파일 아래에서 어떤 명령이든 실행할 수 있으므로, 간단한 테스트 도구로 활용할 수 있습니다:
cd /Users/you/code/pets-api
# 1. 워크스페이스에 있는 .env 파일은 읽을 수 없음
codex sandbox --permission-profile apidog-mcp -- cat .env
# cat: .env: Operation not permitted
# 2. 허용되지 않은 폴더에 쓰기 실패
codex sandbox --permission-profile apidog-mcp -- bash -c 'echo x > /tmp/probe.txt'
# bash: /tmp/probe.txt: Operation not permitted
# 3. 허용된 캐시 폴더에는 쓰기 가능
codex sandbox --permission-profile apidog-mcp -- touch ~/.apidog-mcp-server/probe
# (출력 없음, 종료 코드 0)
# 4. 네트워크 차단
codex sandbox --permission-profile apidog-mcp -- curl -sS https://api.apidog.com/
# curl: (6) Could not resolve host: api.apidog.com
이는 macOS에서 확인한 결과입니다. 그런 다음 MCP 핸드셰이크를 보내 서버가 여전히 동작하는지 확인하세요:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| codex sandbox --permission-profile apidog-mcp -- \
npx --offline apidog-mcp-server@0.0.18 --oas=$PWD/openapi.json
네트워크가 꺼진 상태에서 서버는 세 가지 도구로 응답했습니다. OpenAPI 스펙을 읽는 도구, $ref로 참조된 파일을 읽는 도구, 그리고 스펙을 갱신하는 도구입니다. Codex가 API에 맞춰 코드를 작성하는 데 필요한 것은 이것으로 충분합니다.
macOS에서는 아무 codex sandbox 호출에 --log-denials를 붙이면 명령이 끝난 뒤 Seatbelt가 거부한 항목을 출력합니다. 서버가 정당하게 필요로 하는 폴더를 가장 빠르게 찾는 방법입니다.
5단계: Apidog CLI로 Codex가 스펙을 최신 상태로 유지하도록 하기
오프라인 서버는 파일을 읽기 때문에, 누군가 그 파일을 업데이트해야 합니다. 이 작업은 Apidog CLI를 사용해 코딩 에이전트에 맡기세요. Apidog CLI는 MCP 샌드박스 밖에서 Codex의 일반 명령 규칙 아래 실행되므로, MCP 서버에는 토큰이 전혀 필요하지 않습니다.
설정 (한 번만):
npm install -g apidog-cli
apidog auth login --with-token <your-access-token>
CLI를 Codex에 아직 연결하지 않았다면 How to Use the Apidog CLI in Codex를 참고하세요.
에이전트에게 프롬프트 보내기:
Export the OpenAPI 3.1 spec for Apidog project 1234567 to ./openapi.json,
then run test scenario 637132 in environment 358171 against it and give me
a CLI summary. Don't touch any .env file.
에이전트가 실행하는 명령 (apidog export --help와 apidog run --help에서 확인한 플래그, CLI 2.2.12 기준):
apidog export --project 1234567 --format openapi --oas-version 3.1 --output ./openapi.json
apidog run -t 637132 -e 358171 -r cli,junit --out-dir ./apidog-reports
export는 샌드박스된 서버가 읽는 파일을 덮어쓰기 때문에, 다음 MCP 호출에서는 새로운 엔드포인트가 보입니다. run은 테스트 시나리오를 실행하고 CI용 JUnit 리포트를 작성합니다. Apidog 앱에서 실행 결과를 검토하려면 --upload-report를 추가하세요. Apidog의 무료 플랜은 최대 4명의 사용자까지 지원합니다.
서버에 네트워크가 필요할 때: 도메인 허용 목록
프로젝트 모드에서는 api.apidog.com에 접근해야 합니다. Codex의 해법은 네트워크 프록시입니다. enabled = true로 설정하고 허용할 도메인을 나열한 뒤 network_proxy 기능을 켜세요. 아래는 OpenAI 글에서 제시된 문서화된 형식을 Apidog에 맞게 조정한 것입니다:
[permissions.apidog-mcp-live.filesystem]
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp-live.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp-live.network]
enabled = true
[permissions.apidog-mcp-live.network.domains]
"api.apidog.com" = "allow"
[features]
network_proxy = true
명시적인 deny는 allow보다 우선하며, 프록시는 규칙이 허용한 뒤에야 호스트 이름을 확인합니다. DNS 조회만으로도 데이터가 유출될 수 있기 때문입니다. OpenAI는 광범위한 와일드카드가 여전히 DNS 기반 유출을 허용할 수 있다고 경고하므로, 정확한 호스트만 나열하세요.
저희 테스트에서 나온 주의 사항입니다. 저희 Mac에서는 프록시가 시작되어 HTTP_PROXY 등 환경 변수를 샌드박스에 주입했지만, 허용된 호스트를 포함한 모든 호스트에 대해 403과 함께 x-proxy-error: blocked-by-allowlist를 반환했습니다. 저희 머신은 DNS를 로컬 프록시 앱을 통해 라우팅하고 있어서 그럴 수도 있습니다. 이 프로파일에 의존하기 전에 직접 codex sandbox --permission-profile apidog-mcp-live -- curl -sS https://api.apidog.com/를 실행해 보세요. 허용된 호스트가 실패하면 1단계의 OAS 모드로 돌아가세요.
어떤 프로파일을 사용해야 할까?
| 서버 유형 | 네트워크 | 파일시스템 쓰기 | 예시 |
|---|---|---|---|
| 로컬 파일만 읽는 서버 | enabled = false |
npm 캐시 + 자체 데이터 폴더 | --oas를 사용하는 Apidog MCP Server |
| 알려진 API 하나를 호출하는 서버 | 프록시 + 정확한 도메인 | npm 캐시 + 자체 데이터 폴더 | --project-id를 사용하는 Apidog MCP Server |
| 열린 인터넷이 필요한 서버 | 피하거나 VM으로 격리 | 가능한 한 좁게 | 웹 탐색 서버 |
팀에서 Codex를 운영한다면 관리자는 requirements.toml의 allowed_permission_profiles를 사용해 사용자가 선택할 수 있는 프로파일을 제한할 수 있습니다. 그리고 샌드박스를 끄고 싶은 유혹이 든다면, 왜 Codex 샌드박스를 우회하는 것이 바로 이 보호를 포기하는 것인지 읽어 보세요.
자주 묻는 질문
Codex는 기본적으로 MCP 서버를 샌드박스로 감싸나요? 아닙니다. OpenAI는 Codex가 config.toml에 설정된 stdio MCP 서버를 시작하는 명령은 샌드박스로 격리하지 않는다고 명시합니다. codex sandbox --permission-profile <name> --를 통해 서버를 실행하면 샌드박스를 직접 추가할 수 있습니다.
왜 npx -y 대신 npx --offline을 사용해야 하나요? network.enabled = false에서는 npx가 아무것도 다운로드할 수 없습니다. --offline은 npx -y --package=<pkg>@<version> -c true로 미리 캐시한 복사본을 사용하도록 지시하며, 버전을 고정하면 새 릴리스가 코드를 교체하지 못합니다.
샌드박스가 API 키를 보호하나요? 거부한 것은 차단합니다. :workspace 프로파일은 광범위한 읽기를 허용하므로 .env 파일과 비밀 폴더에 대한 deny 규칙을 추가하세요. 네트워크가 꺼져 있으면 서버는 읽은 내용을 어디로도 보낼 수 없습니다.
Linux와 Windows에서도 동작하나요? 네. 동일한 프로파일이 어디서나 적용됩니다. Codex는 Linux에서는 bubblewrap과 seccomp로, 호환되는 Windows 기기에서는 MXC 기반 샌드박스로 이를 강제합니다. 경로와 DNS 설정이 다르므로 각 머신에서 codex sandbox로 테스트하세요.
다른 MCP 서버도 같은 방식으로 샌드박스 처리할 수 있나요? 네. 모든 stdio 서버에 적용됩니다. 서버가 쓰는 폴더와 호출하는 호스트를 파악하고, 프로파일을 부여하고, 명령을 감싸고, 패키지를 미리 캐시한 뒤 테스트하면 됩니다. OpenAI의 예제에서도 @modelcontextprotocol/server-memory를 ~/.npm과 ~/mcp-data에만 쓰기를 허용하도록 샌드박스 처리합니다.
