Cara Menjalankan Server MCP Codex dengan Profil Izin Sandbox (Apidog MCP Server)
Untuk menjalankan server MCP sandbox Codex, tentukan profil izin di ~/.codex/config.toml, lalu arahkan command server ke codex sandbox --permission-profile <name> -- diikuti perintah aslinya. Codex tidak menjalankan sandbox pada server MCP stdio secara default, jadi tanpa pembungkus itu, server npx akan berjalan dengan izin pengguna penuh Anda.
Postingan engineering OpenAI berjudul Inside the Codex sandbox, yang diterbitkan pada 18 November 2026, menjelaskannya dengan gamblang: Codex tidak bisa menebak secara andal file atau layanan jaringan apa yang dibutuhkan sebuah server, sehingga ia membiarkan perintah peluncuran server apa adanya. Setiap server MCP yang Anda tambahkan dengan npx -y dapat membaca folder home Anda, menulis di mana pun Anda bisa menulis, dan memanggil host mana pun di internet.
Di bawah ini Anda akan membuat profil untuk Apidog MCP Server, menguncinya ke file OpenAPI lokal dengan jaringan dimatikan, membuktikan profil tersebut berfungsi dengan codex sandbox, lalu menyerahkan pekerjaan rutin ke coding agent Anda menggunakan Apidog CLI.
Mengapa Codex membiarkan server MCP stdio tanpa sandbox
Server MCP stdio adalah program lokal yang dijalankan oleh Codex dan diajak berkomunikasi melalui input dan output standar. Codex menjalankan sandbox pada perintah shell yang dijalankan modelnya, tetapi ia tidak menjalankan sandbox pada perintah yang meluncurkan server MCP, karena ia tidak bisa menentukan file atau host apa yang dibutuhkan server tersebut. Server itu mewarisi izin pengguna penuh Anda.
Perintah yang dijalankan model mendapat profil bawaan :workspace: hanya menulis di dalam workspace, .git dan .codex hanya-baca, pembacaan luas, tanpa jaringan. Server MCP di [mcp_servers] tidak mendapat semua itu.
Celah ini penting karena server MCP adalah kode pihak ketiga yang Anda unduh saat peluncuran. Konfigurasi tipikalnya seperti ini:
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@1.0.0"]
npx -y mengunduh paket dan menjalankannya tanpa konfirmasi. Jika paket itu disusupi, ia bisa membaca file .env dan kunci SSH Anda lalu mengirimkannya ke mana saja. Panduan kami tentang kebijakan keamanan MCP membahas model ancaman yang lebih luas; postingan ini memperbaiki satu celah dalam setup Codex Anda.
Cara kerja profil izin Codex
Profil izin adalah sekumpulan aturan filesystem dan jaringan bernama di bawah [permissions] dalam config.toml. Postingan OpenAI dan dokumentasi izin Codex menjelaskan tiga tingkat filesystem:
| Nilai | Efek |
|---|---|
read |
Akses hanya-baca |
write |
Akses baca dan tulis |
deny |
Tidak ada akses sama sekali |
Tiga kunci melakukan sebagian besar pekerjaan:
-
":root" = "read"memberikan pembacaan luas, yang dibutuhkan Node.js dan npm untuk memuat file mereka sendiri. - Path seperti
"~/.npm" = "write"hanya memberikan izin tulis ke folder tersebut. - Tabel
":workspace_roots"menerapkan aturan relatif terhadap setiap root workspace."**/*.env" = "deny"memblokir setiap file.envdi bawahnya.
Jaringan memiliki tiga mode: mati, dirutekan melalui proxy Codex dengan daftar domain yang diizinkan, atau akses penuh.
Codex CLI open-source menegakkan aturan ini melalui sistem operasi: Seatbelt di macOS, bubblewrap plus seccomp di Linux, dan, pada perangkat Windows yang kompatibel, MXC dari Microsoft. Proses anak mewarisi batasan tersebut, sehingga apa pun yang dijalankan server tetap berada di dalam kotak yang sama.
Langkah 1: Pilih mode teraman untuk Apidog MCP Server
Apidog MCP Server (apidog-mcp-server di npm, saat ini versi 0.0.18) berjalan dalam dua mode:
-
Mode proyek, dengan
--project-id=<id>danAPIDOG_ACCESS_TOKEN, mengambil dokumentasi API Anda dari proyek Apidog melalui jaringan. -
Mode OAS, dengan
--oas=<url-or-path>, membaca file Swagger atau OpenAPI secara langsung.
Mode OAS dengan file lokal sama sekali tidak membutuhkan jaringan. Itu adalah profil terkuat yang bisa Anda tulis, jadi itulah contoh utama di sini. Apidog CLI menjaga spesifikasi tetap segar dari luar sandbox (Langkah 5).
Kami membaca paket 0.0.18 untuk mencari tahu apa yang ditulis server: ia menyimpan cache data di ~/.apidog-mcp-server (atau folder di APIDOG_DATA_LOCATION), dan dalam mode proyek ia memanggil https://api.apidog.com kecuali Anda memberikan --apidog-api-base-url.
Langkah 2: Tentukan profil izin
Tambahkan ini ke ~/.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
Server dapat membaca spesifikasi dan menulis ke dua folder cache. Ia tidak dapat membuka file .env di workspace mana pun, dan tidak memiliki jaringan.
Langkah 3: Bungkus perintah server dengan codex sandbox
Sekarang ganti peluncuran npx biasa dengan codex sandbox. Flag -C menetapkan direktori kerja, yang juga merupakan root workspace tempat aturan .env berlaku:
[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"
]
Tiga detail penting:
-
Pin versinya.
@0.0.18berarti rilis baru tidak bisa menukar kode di bawah Anda. -
Gunakan
npx --offline. Dengan jaringan mati,npxharus menemukan paket di cache. -
Gunakan path absolut. Codex meneruskan
argsbegitu saja tanpa shell, jadi~tidak diekspansi.
README Apidog menyarankan untuk menamai server sesuai API yang didokumentasikannya, misalnya "Pets API Documentation", agar model tahu kapan harus menggunakannya.
Langkah 4: Pra-cache paket dan buktikan profilnya berfungsi
Sandbox dapat menulis ke folder cache tetapi tidak dapat membuatnya, dan tidak dapat mengunduh apa pun. Jalankan perintah ini sekali saja, di luar sandbox:
mkdir -p ~/.apidog-mcp-server
npx -y --package=apidog-mcp-server@0.0.18 -c true
Lalu uji profilnya sebelum Anda mempercayainya. codex sandbox menjalankan perintah apa pun di bawah sebuah profil, yang menjadikannya harness pengujian cepat:
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
Itulah hasil yang kami dapatkan di macOS. Kemudian pastikan server tetap berfungsi dengan mengirimkan handshake MCP kepadanya:
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
Dengan jaringan mati, server menjawab dengan tiga tool: satu yang membaca spesifikasi OpenAPI, satu yang membaca file yang direferensikan oleh $ref, dan satu yang menyegarkan spesifikasi. Itu semua yang dibutuhkan Codex untuk menulis kode terhadap API Anda.
Di macOS, tambahkan --log-denials ke setiap panggilan codex sandbox untuk mencetak penolakan Seatbelt setelah perintah selesai. Ini cara tercepat untuk menemukan folder yang memang dibutuhkan server.
Langkah 5: Biarkan Codex menjaga spesifikasi tetap segar dengan Apidog CLI
Server offline membaca sebuah file, jadi harus ada sesuatu yang memperbarui file itu. Serahkan tugas itu ke coding agent Anda dengan Apidog CLI. Ia berjalan di luar sandbox MCP, di bawah aturan perintah normal Codex, dan server MCP tidak pernah memerlukan token.
Setup (sekali):
npm install -g apidog-cli
apidog auth login --with-token <your-access-token>
Jika Anda belum menghubungkan CLI ke Codex, ikuti Cara Menggunakan Apidog CLI di Codex.
Prompt untuk agent Anda:
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.
Perintah yang dijalankan agent (flag dari apidog export --help dan 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 menimpa file yang dibaca server dalam sandbox, sehingga panggilan MCP berikutnya melihat endpoint baru. run menjalankan skenario tes Anda dan menulis laporan JUnit untuk CI. Tambahkan --upload-report jika Anda ingin meninjau eksekusi di aplikasi Apidog. Paket Free Apidog mencakup hingga 4 pengguna.
Saat server membutuhkan jaringan: daftar domain yang diizinkan
Mode proyek perlu menjangkau api.apidog.com. Jawaban Codex adalah proxy jaringan: atur enabled = true, daftarkan domain yang diizinkan, dan aktifkan fitur network_proxy. Berikut bentuk terdokumentasi dari postingan OpenAI, diadaptasi untuk 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 eksplisit menang atas allow, dan proxy baru menyelesaikan nama host setelah sebuah aturan mengizinkannya, karena bahkan pencarian DNS pun bisa membocorkan data. OpenAI memperingatkan bahwa wildcard yang terlalu luas tetap dapat memungkinkan eksfiltrasi berbasis DNS, jadi daftarkan host secara persis.
Satu peringatan dari pengujian kami sendiri. Di Mac kami, proxy mulai berjalan dan menyuntikkan HTTP_PROXY dan yang sejenisnya ke dalam sandbox, tetapi ia menjawab 403 dengan x-proxy-error: blocked-by-allowlist untuk setiap host, termasuk yang diizinkan. Mesin kami merutekan DNS melalui aplikasi proxy lokal, yang mungkin menjadi penyebabnya. Jalankan codex sandbox --permission-profile apidog-mcp-live -- curl -sS https://api.apidog.com/ di mesin Anda sendiri sebelum Anda bergantung pada profil ini. Jika host yang diizinkan gagal, kembali ke mode OAS dari Langkah 1.
Profil mana yang sebaiknya Anda gunakan?
| Jenis server | Jaringan | Penulisan filesystem | Contoh |
|---|---|---|---|
| Hanya membaca file lokal | enabled = false |
Cache npm + folder data sendiri | Apidog MCP Server dengan --oas
|
| Memanggil satu API yang diketahui | Proxy + domain persis | Cache npm + folder data sendiri | Apidog MCP Server dengan --project-id
|
| Membutuhkan internet terbuka | Hindari, atau isolasi di VM | Sesenpit mungkin | Server penjelajah web |
Jika Anda menjalankan Codex dalam tim, administrator dapat menggunakan allowed_permission_profiles di requirements.toml untuk membatasi profil mana yang dapat dipilih pengguna. Dan jika Anda tergoda untuk mematikan sandbox saja, baca mengapa melewati sandbox Codex menukar perlindungan ini.
FAQ
Apakah Codex menjalankan sandbox pada server MCP secara default? Tidak. OpenAI menyatakan bahwa Codex tidak menjalankan sandbox pada perintah yang memulai server MCP stdio yang dikonfigurasi di config.toml. Anda menambahkan sandbox sendiri dengan meluncurkan server melalui codex sandbox --permission-profile <name> --.
Mengapa menggunakan npx --offline alih-alih npx -y? Dengan network.enabled = false, npx tidak dapat mengunduh apa pun. --offline memberitahunya untuk menggunakan salinan yang Anda cache dengan npx -y --package=<pkg>@<version> -c true, dan mem-pin versi mencegah rilis baru menggantikan kode.
Apakah sandbox melindungi kunci API saya? Ia memblokir apa yang Anda tolak. Profil :workspace mengizinkan pembacaan luas, jadi tambahkan aturan deny untuk file .env dan folder rahasia. Dengan jaringan mati, server juga tidak dapat mengirim apa pun yang ia baca.
Apakah ini berfungsi di Linux dan Windows? Ya. Profil yang sama berlaku di mana saja; Codex menegakkannya dengan bubblewrap dan seccomp di Linux dan dengan sandbox berbasis MXC pada perangkat Windows yang kompatibel. Uji setiap mesin dengan codex sandbox, karena path dan setup DNS dapat berbeda.
Bisakah saya menjalankan sandbox pada server MCP lain dengan cara yang sama? Ya. Server stdio apa pun bisa: cari folder tempat ia menulis dan host yang ia panggil, beri profil, bungkus perintahnya, pra-cache paketnya, dan uji. Contoh sandbox OpenAI sendiri menggunakan @modelcontextprotocol/server-memory dengan penulisan dibatasi ke ~/.npm dan ~/mcp-data.


Top comments (0)