How to Run a Codex Sandbox MCP Server (with the Apidog MCP Server as the Example)
To run a Codex sandbox MCP server, define a permission profile in ~/.codex/config.toml, then point the server's command at codex sandbox --permission-profile <name> -- followed by the original command. Codex doesn't sandbox stdio MCP servers by default, so without that wrapper an npx server runs with your full user permissions.
OpenAI's engineering post Inside the Codex sandbox, published on November 18, 2026, spells it out: Codex can't reliably guess which files or network services a server needs, so it leaves the server's launch command alone. Every MCP server you add with npx -y can read your home folder, write anywhere you can write and call any host on the internet.
Below you'll build a profile for the Apidog MCP Server, lock it to a local OpenAPI file with the network switched off, prove the profile works with codex sandbox and then hand the routine work to your coding agent with the Apidog CLI.
Why Codex leaves stdio MCP servers unsandboxed
A stdio MCP server is a local program Codex starts and talks to over standard input and output. Codex sandboxes the shell commands its model runs, but it doesn't sandbox the command that launches an MCP server, because it can't tell which files or hosts that server needs. The server inherits your full user permissions.
Commands the model runs get the built-in :workspace profile: writes inside the workspace only, .git and .codex read-only, broad reads, no network. An MCP server in [mcp_servers] gets none of that.
That gap matters because MCP servers are third-party code you pull at launch time. A typical config looks like this:
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@1.0.0"]
npx -y downloads the package and runs it with no prompt. If that package is compromised, it can read your .env files and SSH keys and send them anywhere. Our guide to MCP security policies covers the wider threat model; this post fixes the one hole in your Codex setup.
How a Codex permission profile works
A permission profile is a named set of filesystem and network rules under [permissions] in config.toml. OpenAI's post and the Codex permissions docs describe three filesystem levels:
| Value | Effect |
|---|---|
read |
Read-only access |
write |
Read and write access |
deny |
No access at all |
Three keys do most of the work:
-
":root" = "read"grants broad reads, which Node.js and npm need to load their own files. - A path such as
"~/.npm" = "write"grants writes only to that folder. - A
":workspace_roots"table applies rules relative to each workspace root."**/*.env" = "deny"blocks every.envfile under it.
Network has three modes: off, routed through Codex's proxy with a domain allowlist, or full access.
The open-source Codex CLI enforces these rules with the operating system: Seatbelt on macOS, bubblewrap plus seccomp on Linux and, on compatible Windows devices, Microsoft's MXC. Child processes inherit the limits, so anything the server spawns stays inside the same box.
Step 1: Pick the safest mode for the Apidog MCP Server
The Apidog MCP Server (apidog-mcp-server on npm, version 0.0.18 today) runs in two modes:
-
Project mode, with
--project-id=<id>and anAPIDOG_ACCESS_TOKEN, pulls your API docs from an Apidog project over the network. -
OAS mode, with
--oas=<url-or-path>, reads a Swagger or OpenAPI file directly.
OAS mode with a local file needs no network at all. That's the strongest profile you can write, so it's the main example here. The Apidog CLI keeps the spec fresh from outside the sandbox (Step 5).
We read the 0.0.18 package to find what the server writes: it caches data in ~/.apidog-mcp-server (or the folder in APIDOG_DATA_LOCATION), and in project mode it calls https://api.apidog.com unless you pass --apidog-api-base-url.
Step 2: Define the permission profile
Add this to ~/.codex/config.toml:
[permissions.apidog-mcp.filesystem]
# Broad reads so Node.js and npm can load their own files.
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp.network]
enabled = false
The server can read the spec and write to two cache folders. It can't open any workspace .env file, and it has no network.
Step 3: Wrap the server command in codex sandbox
Now replace the plain npx launch with codex sandbox. The -C flag sets the working directory, which is also the workspace root the .env rule applies to:
[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"
]
Three details matter:
-
Pin the version.
@0.0.18means a new release can't swap code under you. -
Use
npx --offline. With the network off,npxmust find the package in the cache. -
Use absolute paths. Codex passes
argsstraight through with no shell, so~isn't expanded.
The Apidog README suggests naming the server after the API it documents, such as "Pets API Documentation", so the model knows when to use it.
Step 4: Pre-cache the package and prove the profile works
The sandbox can write to the cache folder but can't create it, and it can't download anything. Run these once, outside the sandbox:
mkdir -p ~/.apidog-mcp-server
npx -y --package=apidog-mcp-server@0.0.18 -c true
Then test the profile before you trust it. codex sandbox runs any command under a profile, which makes it a quick test harness:
cd /Users/you/code/pets-api
# 1. A .env file in the workspace is unreadable
codex sandbox --permission-profile apidog-mcp -- cat .env
# cat: .env: Operation not permitted
# 2. Writes outside the allowed folders fail
codex sandbox --permission-profile apidog-mcp -- bash -c 'echo x > /tmp/probe.txt'
# bash: /tmp/probe.txt: Operation not permitted
# 3. The allowed cache folder is writable
codex sandbox --permission-profile apidog-mcp -- touch ~/.apidog-mcp-server/probe
# (no output, exit 0)
# 4. No network
codex sandbox --permission-profile apidog-mcp -- curl -sS https://api.apidog.com/
# curl: (6) Could not resolve host: api.apidog.com
Those are the results we got on macOS. Then check that the server still works by sending it an MCP handshake:
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
With the network off, the server answered with three tools: one that reads the OpenAPI spec, one that reads files referenced by $ref, and one that refreshes the spec. That's all Codex needs to write code against your API.
On macOS, add --log-denials to any codex sandbox call to print the Seatbelt denials after the command exits. It's the fastest way to find a folder the server legitimately needs.
Step 5: Let Codex keep the spec fresh with Apidog CLI
An offline server reads a file, so something has to update that file. Hand that job to your coding agent with the Apidog CLI. It runs outside the MCP sandbox, under Codex's normal command rules, and the MCP server never needs a token.
Setup (once):
npm install -g apidog-cli
apidog auth login --with-token <your-access-token>
If you haven't wired the CLI into Codex yet, follow How to Use the Apidog CLI in Codex.
Prompt your agent:
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.
Commands the agent runs (flags from apidog export --help and 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 overwrites the file the sandboxed server reads, so the next MCP call sees new endpoints. run executes your test scenario and writes a JUnit report for CI. Add --upload-report if you want to review the run in the Apidog app. Apidog's Free plan covers up to 4 users.
When the server needs network: the domain allowlist
Project mode needs to reach api.apidog.com. Codex's answer is the network proxy: set enabled = true, list allowed domains and turn on the network_proxy feature. This is the documented shape from OpenAI's post, adapted to 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
An explicit deny wins over allow, and the proxy resolves a hostname only after a rule allows it, since even a DNS lookup can leak data. OpenAI warns that broad wildcards can still allow DNS-based exfiltration, so list exact hosts.
One caution from our own test. On our Mac, the proxy started and injected HTTP_PROXY and friends into the sandbox, but it answered 403 with x-proxy-error: blocked-by-allowlist for every host, including the allowed ones. Our machine routes DNS through a local proxy app, which may be why. Run codex sandbox --permission-profile apidog-mcp-live -- curl -sS https://api.apidog.com/ on your own machine before you depend on this profile. If the allowed host fails, fall back to OAS mode from Step 1.
Which profile should you use?
| Server type | Network | Filesystem writes | Example |
|---|---|---|---|
| Reads local files only | enabled = false |
npm cache + own data folder | Apidog MCP Server with --oas
|
| Calls one known API | Proxy + exact domains | npm cache + own data folder | Apidog MCP Server with --project-id
|
| Needs open internet | Avoid, or isolate in a VM | As narrow as possible | Web-browsing servers |
If you run Codex in a team, administrators can use allowed_permission_profiles in requirements.toml to limit which profiles users can pick. And if you're tempted to turn the sandbox off instead, read why bypassing the Codex sandbox trades away exactly this protection.
FAQ
Does Codex sandbox MCP servers by default? No. OpenAI states that Codex doesn't sandbox the command that starts a stdio MCP server configured in config.toml. You add the sandbox yourself by launching the server through codex sandbox --permission-profile <name> --.
Why use npx --offline instead of npx -y? With network.enabled = false, npx can't download anything. --offline tells it to use the copy you cached with npx -y --package=<pkg>@<version> -c true, and pinning the version stops a new release from replacing the code.
Does the sandbox protect my API keys? It blocks what you deny. The :workspace profile allows broad reads, so add deny rules for .env files and secret folders. With the network off, the server also can't send anything it reads.
Does this work on Linux and Windows? Yes. The same profile applies everywhere; Codex enforces it with bubblewrap and seccomp on Linux and with an MXC-based sandbox on compatible Windows devices. Test each machine with codex sandbox, since paths and DNS setups differ.
Can I sandbox other MCP servers the same way? Yes. Any stdio server works: find the folders it writes and the hosts it calls, give it a profile, wrap the command, pre-cache the package and test. OpenAI's own example sandboxes @modelcontextprotocol/server-memory with writes limited to ~/.npm and ~/mcp-data.


Top comments (0)