Skip to main content
Glama
tobiasGuta

Code Sandbox MCP

by tobiasGuta
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Code Sandbox MCP

This project is an improved and security-hardened version of philschmid/code-sandbox-mcp.

Code Sandbox MCP provides short-lived, offline JavaScript workspaces to stdio MCP clients such as Codex. A client can create a sandbox, write and enumerate several files, read or delete files, run a JavaScript entrypoint, and destroy the session. Submitted source is streamed from memory into a container; it is never written to the repository, a host temporary directory, or a host bind mount.

This is a human-directed execution helper, not an autonomous agent. It has no target discovery, browser control, credential access, network-enabled profile, or general shell tool.

Security model

The MCP process is trusted and can talk to the host Docker daemon through the official Docker Python SDK. On Windows, docker.from_env() uses Docker Desktop's normal named-pipe configuration. The sandbox container does not receive that pipe, a Docker or Podman socket, a host path, the server environment, a device, a port, or a host namespace.

Each session is one Linux container with:

  • an immutable local image ID resolved from the single server allowlisted tag;

  • UID/GID 65532:65532, all capabilities dropped, no-new-privileges, Docker's built-in seccomp policy, and docker-default AppArmor when the daemon reports AppArmor support;

  • network_mode=none, no published ports, and no DNS configuration;

  • a read-only root filesystem;

  • a 64 MiB tmpfs at /workspace (rw,nosuid,nodev,mode=0700);

  • a 64 MiB tmpfs at /tmp (rw,noexec,nosuid,nodev,mode=0700);

  • 512 MiB memory and swap limits, one CPU, 128 PIDs, an init process, no devices, no extra groups, and no mounts;

  • only a fixed, minimal runtime environment plus the distroless image's non-secret certificate-file path. Host environment variables and credentials are never copied.

Docker isolation substantially reduces risk, but it is not a VM or a perfect security boundary. The Docker daemon and host kernel remain in the trusted computing base. Do not use this project to analyze container-escape exploits, hostile kernel-level malware, or workloads that require protection from a compromised Docker daemon. Keep Docker Desktop and the host patched, and do not share one stdio server process among unrelated clients.

Networking is deliberately unavailable. Sandboxed code cannot reach the internet, LAN, cloud metadata, host.docker.internal, Docker Desktop services, or host localhost services. There is no supported flag to change this. Dependencies must be baked into a reviewed image; the default distroless image provides Node.js and its built-in modules only. It contains no npm, package manager, or shell, and the MCP surface has no install or npm-script tool.

Related MCP server: MCP QuickJS Runner

Session lifecycle and limits

create_sandbox returns a cryptographically random opaque ID. Raw Docker IDs are never returned. Sessions belong to the MCP server process that created them and are held only in memory.

Limit

Default

Absolute lifetime

10 minutes

Inactivity timeout

3 minutes

Concurrent sessions

3

Workspace entries

100

Individual file

2 MiB

Workspace tmpfs

64 MiB

stdout / stderr

1 MiB each

Command timeout

30 seconds

Maximum command timeout

120 seconds

A background reaper destroys expired sessions. Each container also carries an expiration label, runs an independent maximum-lifetime watchdog, and uses Docker auto-removal. If Python, the MCP client, or the host process exits without cleanup, the container stops and removes itself when its hard lifetime elapses. At startup, the server discovers and removes stopped or already-expired managed containers; it deliberately leaves unexpired containers running so separate local MCP clients cannot destroy one another's active sessions. A legacy managed container with no valid expiration label is removed only when its Docker creation time is older than the configured maximum session lifetime. If Docker does not provide a valid creation time, the server preserves it for manual inspection rather than guessing.

destroy_sandbox force-removes a container and is idempotent after confirmed removal. A failed Docker removal marks the session as destroying, keeps it in the registry, and adds it to a retry queue. A later destroy_sandbox call or background reaper pass retries the same container; the session is forgotten only after Docker confirms removal or reports it already absent. All sessions are also removed from an atexit handler and from the server's finally block when stdio closes. Cancelling run_javascript asynchronously aborts the container without waiting for its session lock.

Execution timeout or an unexpected execution/file-transfer failure removes the affected session. After JavaScript exits, the runner repeatedly kills and checks new processes over a 450 ms grace period. If it cannot prove the process namespace is clean, it reports PROCESS_CLEANUP_FAILED and the host destroys the entire session. Output limits are counted as bytes inside the container; the process group is killed and the response reports OUTPUT_LIMIT_EXCEEDED when a stream crosses its cap.

Server operators may lower or raise bounded limits with CODE_SANDBOX_MAX_LIFETIME, CODE_SANDBOX_IDLE_TIMEOUT, CODE_SANDBOX_MAX_SESSIONS, CODE_SANDBOX_DEFAULT_TIMEOUT, and CODE_SANDBOX_MAX_TIMEOUT. Values are strictly validated at startup. These settings are not MCP inputs.

Run with Docker Desktop on Windows

How the two processes work

The MCP server itself runs as a local Python process. It uses the Docker SDK to create and remove a separate locked-down Linux container for each sandbox session:

flowchart LR
    Client["Codex / Claude Code / Gemini CLI"]
    MCP["Code Sandbox MCP<br/>Local Python process"]
    Docker["Docker Desktop"]
    Sandbox["Offline JavaScript sandbox<br/>Short-lived container"]
    Controls["No network<br/>Read-only root<br/>Non-root UID<br/>Resource limits<br/>Lifetime watchdog<br/>No host mounts"]

    Client -->|"MCP over stdio"| MCP
    MCP -->|"Docker SDK"| Docker
    Docker -->|"Creates and removes"| Sandbox
    Sandbox --- Controls

Do not start the sandbox image with docker run. The MCP server must create it so all security settings, limits, labels, tmpfs mounts, and cleanup behavior are applied together.

Prerequisites

  • Windows 10 or 11;

  • Docker Desktop running Linux containers;

  • Python 3.10 or newer; and

  • a local checkout of this repository.

Confirm Docker Desktop is ready:

docker version
docker info --format '{{.OSType}}'

The second command must print linux.

Install the MCP server

Run these commands from PowerShell:

Set-Location D:\Tools\code-sandbox-mcp

py -m venv .venv
& .\.venv\Scripts\python.exe -m pip install --upgrade pip
& .\.venv\Scripts\python.exe -m pip install -e .

The final command must be executed with .venv\Scripts\python.exe. Installing with a different Python puts the package in that Python installation and does not create the launcher inside this virtual environment.

Verify the launcher:

Test-Path .\.venv\Scripts\code-sandbox-mcp.exe
& .\.venv\Scripts\python.exe -c "from code_sandbox_mcp.server import main; print('MCP import OK')"

Test-Path must print True.

Build the sandbox image

docker build --pull `
  -t code-sandbox-mcp-javascript:1.0.1 `
  -f containers\Dockerfile.nodejs .

Verify the exact local image and its security profile label:

docker image inspect code-sandbox-mcp-javascript:1.0.1 --format 'ID={{.Id}}'
docker image inspect code-sandbox-mcp-javascript:1.0.1 --format '{{json .Config.Labels}}'

The labels JSON must contain both "io.code-sandbox-mcp.profile":"javascript-offline" and "io.code-sandbox-mcp.runtime-version":"1.0.1". The Dockerfile copies the Node 22.23.0 binary from a digest-pinned official Node build stage into a separately digest-pinned distroless/cc-debian12:nonroot runtime. Build tools, npm, Perl, and the source image filesystem do not enter the final image. The MCP server resolves code-sandbox-mcp-javascript:1.0.1 to its immutable local sha256: image ID and rejects an image unless both runtime labels exactly match. It never pulls an image automatically.

Launching code-sandbox-mcp.exe manually is not normally useful: it is a stdio server and waits for an MCP client on standard input. Register the executable with one of the clients below instead.

Rebuild after container-file changes

Changes to containers/Dockerfile.nodejs, containers/idle.mjs, containers/sandbox-helper.mjs, or containers/sandbox-runner.mjs do not affect an already-built image. Rebuild it with the same fixed tag:

docker build --pull --no-cache `
  -t code-sandbox-mcp-javascript:1.0.1 `
  -f containers\Dockerfile.nodejs .

Existing sandbox sessions continue using their original immutable image ID. Destroy them and create new sessions after rebuilding.

Hash-locked development installation

For the checked-in Windows/Python 3.14 development environment, install pylock.toml with a pip release that supports PEP 751 lock files, then install the local package without resolving anything else:

& .\.venv\Scripts\python.exe -m pip install --require-hashes -r pylock.toml
& .\.venv\Scripts\python.exe -m pip install -e . --no-deps --no-build-isolation

pylock.toml is platform-specific. Other Python/platform combinations use the exactly pinned inputs in requirements-dev.in and should generate and review their own lock with python -m pip lock -r requirements-dev.in -o pylock.toml.

Add the server to an MCP CLI

Use the absolute launcher path so clients work regardless of their current directory:

D:\Tools\code-sandbox-mcp\.venv\Scripts\code-sandbox-mcp.exe

The server intentionally supports local stdio only. Each client starts its own MCP server process, which gives sessions a clear owner and makes client-disconnect cleanup deterministic. Docker Desktop and the built image must exist on the same Windows host as that process.

Codex CLI

Register the server from PowerShell:

codex mcp add code-sandbox -- `
  "D:\Tools\code-sandbox-mcp\.venv\Scripts\code-sandbox-mcp.exe"

codex mcp list

Start a new Codex session and enter /mcp to confirm that code-sandbox is enabled. The Codex CLI and Codex IDE extension share MCP configuration on the same Codex host. See the official Codex MCP documentation.

For manual configuration, add this to %USERPROFILE%\.codex\config.toml:

[mcp_servers.code-sandbox]
command = 'D:\Tools\code-sandbox-mcp\.venv\Scripts\code-sandbox-mcp.exe'
startup_timeout_sec = 15
tool_timeout_sec = 150

Restart Codex after changing config.toml. To replace an old registration:

codex mcp remove code-sandbox
codex mcp add code-sandbox -- `
  "D:\Tools\code-sandbox-mcp\.venv\Scripts\code-sandbox-mcp.exe"

Claude Code CLI

Register it as a user-scoped local stdio server:

claude mcp add --transport stdio --scope user code-sandbox -- `
  "D:\Tools\code-sandbox-mcp\.venv\Scripts\code-sandbox-mcp.exe"

claude mcp list

Start a new Claude Code session and enter /mcp to inspect its status. Claude requires all MCP options before the server name and uses -- to separate the server command. See the official Claude Code MCP documentation.

To remove it:

claude mcp remove code-sandbox --scope user

Gemini CLI

Register it as a user-scoped stdio server:

gemini mcp add --scope user --transport stdio code-sandbox `
  "D:\Tools\code-sandbox-mcp\.venv\Scripts\code-sandbox-mcp.exe"

gemini mcp list

Start a new Gemini CLI session and enter /mcp list to inspect its status. Keep Gemini's default confirmation behavior; do not add --trust for an execution server. See the official Gemini CLI MCP documentation.

To remove it:

gemini mcp remove --scope user code-sandbox

Other local stdio MCP clients

Clients that accept the common JSON MCP shape can use:

{
  "mcpServers": {
    "code-sandbox": {
      "command": "D:\\Tools\\code-sandbox-mcp\\.venv\\Scripts\\code-sandbox-mcp.exe",
      "args": []
    }
  }
}

Configuration filenames and restart behavior are client-specific. Use the client's local stdio MCP option, not HTTP, SSE, or a Docker command. Do not configure secrets or host environment variables for this server.

End-to-end smoke test

After registration, ask the client:

Use the code-sandbox MCP tools to create a sandbox, write an index.js that
prints "Hello from the isolated container", run it, show stdout, and destroy
the sandbox even if a previous step fails.

While the request is running, a human can confirm that the managed container exists:

docker ps --filter label=io.code-sandbox-mcp.managed=true

After destroy_sandbox, the command should show no container for that completed session.

Tool schemas

All tool requests reject unexpected fields through strict Pydantic models. Paths are relative POSIX-style workspace paths after slash normalization. Absolute, drive, UNC, device, alternate-stream, null-byte, empty-component, dot-component, plain/encoded traversal, overlong, and over-deep paths are rejected. Before each operation the helper uses lstat; symlinks, hard links, and special files invalidate the workspace.

create_sandbox

Input: {}

Output fields: session_id, expires_at, and fixed profile javascript-offline.

write_files

{
  "session_id": "opaque-id",
  "files": [{"path": "lib/parser.js", "content": "export const parse = value => value.trim();"}],
  "overwrite": false
}

Files are sent through Docker exec stdin to a fixed in-image writer, without a shell or host temporary file. The writer creates only validated relative paths with fixed modes. Contents are data, never command interpolation. The result contains a status (written, overwritten, or exists) for every submitted path. A failed transfer destroys the session rather than leaving a partially trusted workspace.

list_files

Input fields: session_id, optional path (default .), recursive (default true), and max_depth from 0 through 10. Output entries contain relative path, type, and size, plus truncated.

read_file

Input fields: session_id, path, and max_bytes (1 through 2 MiB; default 65536). Only regular UTF-8 text is returned. The result includes original size and truncated.

delete_files

Input fields: session_id and one to 100 paths. Only regular files can be unlinked. The workspace root and directories cannot be deleted. Missing files are reported and do not make the operation fail.

run_javascript

Input fields: session_id, a .js, .mjs, or .cjs entrypoint, up to 32 bounded arguments, and optional timeout_seconds. The host constructs this exact argument form without a shell:

node --disable-proto=throw /workspace/<validated-entrypoint> <validated-arguments>

The result contains exit_code, UTF-8-decoded stdout and stderr, timeout and truncation flags, and duration_ms.

destroy_sandbox

Input: session_id. The result says whether a live session was destroyed. Calling it again after confirmed removal is safe. If Docker removal fails, the tool reports CONTAINER_REMOVAL_FAILED while retaining the session for explicit and background retries.

Errors use stable codes including INVALID_SESSION, SESSION_EXPIRED, INVALID_PATH, PATH_TRAVERSAL, FILE_TOO_LARGE, WORKSPACE_LIMIT_EXCEEDED, OUTPUT_LIMIT_EXCEEDED, TIMEOUT, PROCESS_CLEANUP_FAILED, CONTAINER_START_FAILED, and CONTAINER_REMOVAL_FAILED. Responses never include stack traces, Docker daemon details, host paths, container IDs, or submitted content.

Example Codex workflow

For "create three JavaScript files that normalize and deduplicate URLs, then run them," the client should:

  1. Call create_sandbox.

  2. Call write_files for index.js, normalize.js, and test-data.js.

  3. Call list_files and verify all three paths.

  4. Call run_javascript with index.js.

  5. Inspect stdout and stderr, overwrite a file if necessary, and run again.

  6. Call destroy_sandbox in all cases.

At no point do those files appear in the host repository or user profile. See examples/codex_workflow.py for the corresponding payload sequence.

Audit log

Security audit logging is enabled by default. On Windows it is stored under %LOCALAPPDATA%\code-sandbox-mcp\audit.jsonl; on Linux it uses $XDG_STATE_HOME or ~/.local/state. Set CODE_SANDBOX_AUDIT_LOG to choose another host location or CODE_SANDBOX_AUDIT_ENABLED=false to disable it.

Each JSONL record contains a timestamp, tool, SHA-256-derived session hash, result, duration, and relevant counts such as file/byte totals, exit code, timeout, output bytes, and cleanup result. It never logs source, raw session/container IDs, environment values, tokens, or Docker inspection data.

Audit writes are best-effort and non-fatal. Permission errors, disk exhaustion, invalid paths, antivirus locks, or a custom logger failure cannot turn an otherwise successful sandbox operation into an error or hide a newly created session ID. The server emits a generic warning to stderr when an audit record cannot be written, without exposing the audit path, session ID, or submitted content.

Testing and manual verification

& .\.venv\Scripts\python.exe -m pip install -e '.[dev]'
& .\.venv\Scripts\python.exe -m pytest -q
& .\.venv\Scripts\python.exe -m ruff check .
& .\.venv\Scripts\python.exe -m pyright src tests

docker build --pull -t code-sandbox-mcp-javascript:1.0.1 -f containers\Dockerfile.nodejs .
$env:RUN_DOCKER_TESTS='1'
& .\.venv\Scripts\python.exe -m pytest -q tests\test_docker_integration.py

While a human has a session open, inspect the managed container without giving its ID to the model:

docker ps --filter label=io.code-sandbox-mcp.managed=true
docker inspect <container-id> --format '{{json .HostConfig}}'

Confirm NetworkMode is none, ReadonlyRootfs is true, CapDrop is ALL, no binds/devices/ports exist, and only /workspace and /tmp appear in HostConfig.Tmpfs. If Docker Desktop reports unsupported hardening settings or uses Windows containers, the sandbox should be treated as unavailable rather than weakened.

Image and dependency updates

  1. Select an exact Node patch tag and obtain its multi-platform digest from the official image registry.

  2. Change both tag and digest in containers/Dockerfile.nodejs in a dedicated review.

  3. Build the image, run unit and Docker integration tests, generate the SBOM, and run Trivy with high/critical failures enabled.

  4. Retag only after review. Never add an MCP image parameter or automatic pull.

  5. Update exact Python pins, regenerate pylock.toml, run pip-audit, and review Dependabot output.

Every third-party GitHub Action in .github/workflows/security.yml is pinned to a full 40-character commit SHA with its release tag recorded in a comment. Review both the upstream release and resolved commit before changing a pin.

See MIGRATION.md for the intentionally breaking changes from the original project.

Troubleshooting

  • .venv\Scripts\code-sandbox-mcp.exe is missing: the project was not installed into that virtual environment. Run & .\.venv\Scripts\python.exe -m pip install -e ., then confirm the path with Test-Path.

  • The MCP client reports spawn, ENOENT, or file-not-found: use the absolute executable path, confirm it with Test-Path, and restart the client after changing its configuration.

  • The MCP server appears but has no usable sandbox: make sure Docker Desktop is running Linux containers and build code-sandbox-mcp-javascript:1.0.1 locally. The server deliberately does not pull it or accept an older runtime label.

  • CONTAINER_UNAVAILABLE: start Docker Desktop in Linux-container mode and build the exact approved image tag locally.

  • Image profile-label error: remove the incorrect local tag and rebuild from this Dockerfile.

  • Immediate session expiry: check the validated CODE_SANDBOX_* server settings; the model cannot override them.

  • JavaScript cannot fetch/install: expected; the default profile is permanently offline.

  • A session disappeared after an error: transfer, execution, output, workspace-integrity, and host-watchdog failures deliberately fail closed and remove it.

Available Tools

7 tools
create_sandboxA

Create a disposable offline JavaScript sandbox using the fixed server profile.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description provides basic context: 'disposable' implies temporary, 'offline' suggests no network, but lacks details on side effects, permissions, or lifecycle.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no redundancy, front-loaded with key action and context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and presence of output schema, description adequately defines purpose. Could elaborate on prerequisites or use cases but not critical for a simple creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters; baseline is 4. Description adds meaningful context beyond schema by explaining the sandbox is disposable, offline, and uses a fixed server profile.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'create', resource 'sandbox', and specifies 'disposable offline' and 'fixed server profile', distinguishing it from sibling tools like destroy_sandbox and run_javascript.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like destroy_sandbox or run_javascript. Only states what it does, not when or why.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_filesA

Delete selected regular files; deleting /workspace or directories is forbidden.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsYes
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the important restriction about forbidden targets, but lacks details on irreversibility, permission requirements, or side effects. This is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the action and constraint. No wasted words; every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the potentially destructive nature of file deletion and the lack of annotations, the description is minimally complete. It does not address error scenarios, success indicators, or what happens to the files, though the output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, increasing the need for explanation. The description relates 'regular files' to the 'paths' parameter, but does not clarify the meaning of 'session_id' or add format/constraints beyond the schema. Minimal added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete), target (regular files), and a critical constraint (forbidden to delete /workspace or directories). This distinguishes it from sibling tools like read_file or write_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when deleting regular files) and states a clear exclusion (cannot delete /workspace or directories). However, it does not provide explicit guidance on when not to use this tool or recommend alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

destroy_sandboxB

Force-remove a sandbox. Repeated calls are safe and idempotent.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It discloses idempotency and safety of repeated calls, but does not state if the operation is irreversible or what happens to files inside. This is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that front-load the action and immediately clarify safety. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple destructive tool, the description covers idempotency and action. However, it lacks any mention of prerequisites (e.g., sandbox must exist) or return values, though an output schema exists and is not shown.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter (session_id) with 0% schema description coverage. The description adds no explanation of what session_id represents or how to obtain it, leaving the agent without guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Force-remove') and the resource ('a sandbox'). It differentiates from siblings like delete_files which operate within a sandbox, making it distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you want to destroy a sandbox but provides no explicit guidance on when to use versus alternatives, nor does it mention prerequisites like having an existing sandbox.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_filesB

List regular files and directories beneath /workspace without following links.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNo.
max_depthNo
recursiveNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that it does not follow symbolic links, which is a key behavioral detail. However, without annotations, it does not mention other important behaviors such as permission handling or how recursion works.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the primary action. Every word is necessary, and there is no superfluous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters and no annotations, the description is insufficient. It lacks context about the path relative to the workspace, recursion behavior, and session ID requirements. The presence of an output schema partially compensates, but overall completeness is low.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds no information about the four parameters (path, max_depth, recursive, session_id). The schema provides defaults and titles, but the description fails to explain their meaning or context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists regular files and directories without following links, distinguishing it from siblings like read_file or delete_files. However, the phrase 'beneath /workspace' is somewhat ambiguous regarding the path parameter's relationship to the workspace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like read_file or write_files. The description does not mention prerequisites or typical usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileB

Read a bounded UTF-8 text file beneath /workspace.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
max_bytesNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It mentions UTF-8 and bounded, but lacks details on error handling, encoding behavior, or what happens with non-text files.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff. However, it could be expanded slightly to include parameter hints without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 parameters and an output schema, the description is too sparse. It omits session_id purpose, max_bytes role, and output format, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, yet description adds no information about parameters (path, max_bytes, session_id). The agent must rely solely on the schema, which lacks descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it reads a UTF-8 text file within /workspace, with a bounded size. This distinguishes it from sibling tools like create_sandbox or write_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies the tool is for reading text files under /workspace but does not specify when not to use it (e.g., binary files) or mention alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_javascriptC

Run an existing JavaScript file with fixed Node arguments and no shell.

ParametersJSON Schema
NameRequiredDescriptionDefault
argumentsNo
entrypointYes
session_idYes
timeout_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses 'fixed Node arguments' and 'no shell' but omits side effects (e.g., file system changes), environment, error handling, and execution output format. Minimal behavioral insight beyond basic execution mode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single 8-word sentence, which is concise but overly terse given the tool has 4 parameters and an output schema. It front-loads the core action but sacrifices completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is moderately complex (4 params, output schema present), yet the description provides no details on return values, prerequisites, or allowed parameter combinations. An agent cannot reliably use this tool without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds no information about any of the four parameters (session_id, entrypoint, arguments, timeout_seconds). The agent must rely solely on the schema for parameter meaning, which is insufficient for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'run', the resource 'existing JavaScript file', and key behavioral specifics ('fixed Node arguments', 'no shell'). It effectively distinguishes from sibling tools like create_sandbox and destroy_sandbox.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, such as when the file already exists or the need for a session. No prerequisites or exclusions mentioned. The agent lacks context on the proper usage scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_filesC

Write UTF-8 text files beneath /workspace using an in-memory archive.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesYes
overwriteNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description mentions 'using an in-memory archive' which hints at ephemeral storage, but lacks details on mutation behavior, permissions, error handling, or what happens on overwrite. The absence of behavioral disclosure beyond the one phrase limits agent understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise but overly sparse. It lacks necessary details, making it insufficient rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three parameters, a batch file operation, and no output schema provided, the description is severely incomplete. It omits the batch nature, overwrite behavior, session requirement, and return value. The tool is more complex than the description implies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no information about the parameters (path, content, overwrite, session_id). It does not explain the required session_id, the meaning of overwrite, or the structure of files. This leaves the agent without parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (write) and resource (UTF-8 text files beneath /workspace). It distinguishes from sibling tools like list_files and read_file. However, it does not mention the batch operation (array of files) or the overwrite capability, which would further clarify the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like create_sandbox or run_javascript. There is no mention of prerequisites, context, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.0.0
    • First observedcreate_sandbox
    • First observeddelete_files
    • First observeddestroy_sandbox
    • First observedlist_files
    • First observedread_file
    • First observedrun_javascript
    • First observedwrite_files
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

Each tool targets a distinct operation: sandbox lifecycle, file management, and execution. No overlap in purposes, making selection unambiguous for an agent.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case (e.g., create_sandbox, list_files, run_javascript), making the set predictable and easy to navigate.

Tool Count5/5

Seven tools is well-scoped for a sandbox management server, covering creation, destruction, file operations, and execution without unnecessary bloat.

Completeness4/5

The set covers core sandbox lifecycle and file operations. Minor gaps like renaming files or inspecting sandbox metadata exist but do not severely hinder common workflows.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP QuickJS Runner

    jlucaso1
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides secure execution of arbitrary JavaScript code within a sandboxed QuickJS WASM environment, allowing language models or other MCP clients to safely run JavaScript code snippets without compromising the host system.
    4
    -

  • Node.js Sandbox MCP Server

    alfonsograziano
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables running arbitrary JavaScript code in isolated Docker containers with on-the-fly npm dependency installation, supporting both ephemeral one-shot executions and persistent sandbox environments.
    134
    157
    -

  • Node Code Sandbox MCP

    mozicim
    F
    license
    A
    quality
    B
    maintenance
    A secure Node.js execution environment that allows coding agents and LLMs to run JavaScript dynamically, install NPM packages, and retrieve results while adhering to the Model Control Protocol.
    7
    134
    4
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tobiasGuta/Code-Sandbox-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server