The MCP Sandbox

Run MCP servers without blindly trusting them.

MCP Cage is the execution sandbox for MCP servers — the runtime layer where security certifications become hard enforcement. It verifies integrity, confines processes, and audits everything, so you never have to blindly trust the code you run.

Project: MCP Cage  ·  CLI command: smcp (short for Secure MCP)

• The Problem
• What MCP Cage Does
• The Sandbox
• Quick Start
• Installation
• Usage
• Configuration
• LLM Security Warnings
• Platform Support
• Documentation
• MCP Hub Platform
• License
• Contributing

Every time you run an MCP server, you are executing arbitrary code with your full system permissions:

uvx some-mcp-server       # What does this code actually do?
npx @someone/mcp-tool     # Can it read your SSH keys? Yes.

No verification. No resource limits. No sandboxing. No audit trail.

For individual developers experimenting locally, this may be acceptable. For teams and organizations running MCP servers connected to internal databases, APIs, credentials, and infrastructure — it is not. A compromised or malicious MCP server can exfiltrate secrets, exhaust system resources, spawn persistent processes, or pivot through your internal network, all with zero visibility.

The root cause is structural: the tools that run MCP servers (uvx, npx) were designed for convenience, not security. They have no mechanism for verifying what they are about to execute, no way to constrain what it does while running, and no record of what happened.

MCP Cage fixes this at the execution layer.

MCP Cage ships as smcp, a drop-in replacement for uvx and npx that wraps every MCP server execution in a full security envelope:

Packages are analyzed upstream by MCP Hub Platform for 14 classes of security vulnerabilities and assigned a certification level (0–3) before they ever reach your machine. MCP Cage enforces those certifications at runtime: it validates digests, checks your organization's policy, applies the sandbox, and writes an immutable audit log — for every execution, without exception.

The sandbox is the core of MCP Cage. It is not an afterthought or a checkbox — it is the primary reason the project exists.

When smcp run executes an MCP server, it does not simply exec the process. It builds an isolation boundary around it:

Resource limits are always applied, on every platform, with no way to disable them. Every MCP server runs with a hard cap on CPU time, memory, open file descriptors, and child process count. A server that tries to consume all available memory, fork-bomb the system, or run indefinitely will be stopped.

Filesystem isolation (Linux) confines the process to its working directory using kernel-level Landlock LSM. The server cannot read /etc/passwd, your SSH keys, your environment files, or anything outside the directory it was given.

Network isolation (Linux) places the process in a new network namespace with no interfaces by default. Unless the MCP manifest explicitly declares network requirements, the server cannot make outbound connections.

Subprocess control restricts the server's ability to spawn child processes unless the manifest declares that permission.

Secret redaction ensures that tokens, passwords, and API keys passed to the server are never written to logs, stdout, or stderr at any verbosity level.

Audit logging writes a structured JSON record for every execution: start time, end time, exit code, duration, applied limits, package reference, and digest. There is no way to run an MCP server through MCP Cage without generating an audit entry.

The sandbox layers are additive. Linux gets the full stack. macOS and Windows get resource limits and audit logging today, with deeper isolation on the roadmap. Run smcp doctor to see exactly which layers are active on your system.

For production workloads with untrusted MCP servers, Linux is the recommended platform. See Platform Support for details.

# 1. Install
brew install mcp-hub-corp/tap/smcp          # macOS
sudo apt install smcp                        # Ubuntu/Debian

# 2. Check your system's sandbox capabilities
smcp doctor

# 3. Run a certified MCP server
smcp run acme/hello-world@1.2.3

# 4. Use it with Claude Desktop — replace uvx/npx in your config:
# "command": "smcp", "args": ["run", "--trust", "acme/tool@latest"]

sudo add-apt-repository ppa:mcphub/smcp
sudo apt update
sudo apt install smcp

Supports Ubuntu Noble (24.04 LTS) and Jammy (22.04 LTS).

brew install mcp-hub-corp/tap/smcp

Download the latest release from GitHub Releases:

# macOS — Apple Silicon
curl -sSL https://github.com/mcp-hub-corp/mcp-cage/releases/latest/download/smcp_darwin_arm64.tar.gz | tar xz
sudo mv smcp /usr/local/bin/

# macOS — Intel
curl -sSL https://github.com/mcp-hub-corp/mcp-cage/releases/latest/download/smcp_darwin_amd64.tar.gz | tar xz
sudo mv smcp /usr/local/bin/

# Linux — amd64
curl -sSL https://github.com/mcp-hub-corp/mcp-cage/releases/latest/download/smcp_linux_amd64.tar.gz | tar xz
sudo mv smcp /usr/local/bin/

# Linux — arm64
curl -sSL https://github.com/mcp-hub-corp/mcp-cage/releases/latest/download/smcp_linux_arm64.tar.gz | tar xz
sudo mv smcp /usr/local/bin/

go install github.com/mcp-hub-corp/mcp-cage/cmd/smcp@latest

smcp --version
smcp doctor     # reports which sandbox features are active on your system

# Run by version
smcp run acme/hello-world@1.2.3

# Run latest published version
smcp run acme/tool@latest

# Run by exact digest (fully immutable — guaranteed bit-for-bit identity)
smcp run acme/tool@sha256:a1b2c3...

# Pre-download for offline use or CI/CD pipelines
smcp pull acme/tool@1.2.3

# Inspect a package before running it
smcp info acme/tool@1.2.3

smcp cache ls           # list cached artifacts
smcp cache rm --all     # clear the entire cache

smcp login --token YOUR_TOKEN
# or via environment variable
export MCP_REGISTRY_TOKEN=YOUR_TOKEN

Create ~/.smcp/config.yaml to set persistent defaults:

registry_url: "https://registry.mcp-hub.info"
timeout: 5m
max_memory: "512M"
max_cpu: 1000              # millicores — 1000 = 1 full core

audit_enabled: true
audit_log_file: "~/.smcp/audit.log"

policy:
  min_cert_level: 1        # 0 = any, 1 = static verified, 2 = security certified
  cert_level_mode: strict  # strict | warn | disabled
  allowed_origins:
    - official
    - verified

CLI flags take precedence over the config file. Environment variables use the MCP_ prefix — for example, MCP_REGISTRY_URL, MCP_CACHE_DIR, MCP_LOG_LEVEL.

When AI assistants like Claude Desktop, Cursor, or Windsurf run MCP servers, the human user never sees the terminal. If an MCP server has a low security score, there is ordinarily no way for the user to know.

MCP Cage solves this by injecting security warnings directly into the MCP protocol handshake. Replace uvx/npx with smcp run --trust in your AI client configuration:

{
  "mcpServers": {
    "data-tool": {
      "command": "smcp",
      "args": ["run", "--trust", "acme/data-tool@latest"]
    }
  }
}

If acme/data-tool scores below the warning threshold (default: 80), smcp intercepts the MCP initialize handshake and:

1. Prepends a security warning to the instructions field — the AI reads it and surfaces it to the user
2. Sends a notifications/message at level warning — displayed as a UI banner in supporting clients

After the handshake (typically 3–4 messages), the proxy switches to raw passthrough with zero overhead.

# Adjust the threshold
smcp run --trust --warning-threshold 60 acme/tool@latest

Set policy.warning_threshold: 80 in ~/.smcp/config.yaml to make this permanent.

The depth of sandboxing depends on the operating system. Linux provides the full isolation stack; macOS and Windows have partial support today.

Run smcp doctor to see the exact status on your machine.

Sandbox documentation by platform:

• Linux sandbox — cgroups v2, network namespaces, Landlock, seccomp, rlimits
• macOS sandbox — rlimits, Seatbelt/sandbox-exec, known limitations
• Windows sandbox — Job Objects, known limitations

macOS and Windows have confirmed sandbox bypass vulnerabilities (child processes escape resource limits). See Security Sandbox Limitations for full technical details, mitigations, and the production deployment recommendation (Linux or Docker).

MCP Cage is the execution plane of MCP Hub Platform — a complete trust infrastructure for publishing, certifying, and running MCP servers in a predictable, auditable, and governable way.

The platform is a pipeline of four components that work together end to end:

Developer
    │  smcp push / git commit
    ▼
[mcp-hub]  ── ANALYZE job ──▶  [mcp-scan]
    │                               │
    │  ◀── ANALYZE_COMPLETE ────────┘
    │
    │  publishes certified artifact
    ▼
[mcp-registry]  ── content-addressed storage (SHA-256)
    ▲
    │  resolve → validate → sandbox → audit
    │
[mcp-cage]  ◀── you are here

MCP Cage is where trust becomes real. The hub can analyze, score, and certify all it wants — but none of that matters if the execution layer does not validate digests, enforce policies, sandbox processes, and log everything. This project is responsible for the runtime half of the platform's security guarantees.

To publish MCP servers, manage certifications, or set organization-wide policies, visit mcp-hub.info.

MCP Cage is released under the MIT License.

This means you are free to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software, for any purpose, commercial or non-commercial, with or without attribution. The only requirement is that the license and copyright notice are included with any substantial copy of the software.

See the full license text in LICENSE.

The MIT license was chosen deliberately: MCP Cage is an execution-layer security tool, and its value comes from wide adoption. Restrictive licensing would work against that goal.

Contributions are welcome. See CONTRIBUTING.md for the development setup, code style guidelines, and pull request process.

For security issues, please follow the responsible disclosure process in SECURITY.md rather than opening a public issue.