DEV Community

Cover image for How to Sandbox an MCP Server with codex sandbox
Hassann
Hassann

Posted on Originally published at apidog.com

How to Sandbox an MCP Server with codex sandbox

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.

Try Apidog today

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"]
Enter fullscreen mode Exit fullscreen mode

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:

  1. ":root" = "read" grants broad reads, which Node.js and npm need to load their own files.
  2. A path such as "~/.npm" = "write" grants writes only to that folder.
  3. A ":workspace_roots" table applies rules relative to each workspace root. "**/*.env" = "deny" blocks every .env file under it.

Network has three modes: off, routed through Codex's proxy with a domain allowlist, or full access.

Three network modes for a Codex permission profile: network.enabled = false for no network, a proxy with a domain allowlist such as api.apidog.com, and full network access to avoid for MCP servers

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 an APIDOG_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
Enter fullscreen mode Exit fullscreen mode

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"
]
Enter fullscreen mode Exit fullscreen mode

Three details matter:

  • Pin the version. @0.0.18 means a new release can't swap code under you.
  • Use npx --offline. With the network off, npx must find the package in the cache.
  • Use absolute paths. Codex passes args straight 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.

Diagram: Codex launches codex sandbox with the apidog-mcp profile, which runs npx --offline apidog-mcp-server with an OpenAPI file; inside the sandbox it can read openapi.json and write to ~/.npm and ~/.apidog-mcp-server, while .env files, the internet and other folders are blocked

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)