# Cursor & Claude Code Agent Sandbox MCP Server | Safe Shell for Copilot & Codex

An MCP server that adds a reviewable safety gate before an AI coding agent runs risky shell or file operations. It works with Cursor, Claude Code, Copilot CLI, Codex, and any MCP client that can launch a local stdio server.

The server is intentionally small: safe read-only commands run immediately; commands that look destructive return a one-time approval request; a human explicitly approves or rejects that request through a second MCP tool.

## Why this exists

AI coding agents are useful precisely because they can operate a terminal. That also means a mistaken `rm`, an over-broad Git cleanup, or a network-piped script can damage a working tree. This project makes the decision visible at the command boundary without requiring a container runtime.

## Install

```bash
git clone https://github.com/YOUR_USER/cursor-claude-agent-sandbox-mcp.git
cd cursor-claude-agent-sandbox-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

## Configure an MCP client

Add the following to the client’s MCP configuration. Replace the path with the absolute path to your checkout.

```json
{
  "mcpServers": {
    "agent-sandbox": {
      "command": "/ABSOLUTE/PATH/agent-sandbox-mcp/.venv/bin/agent-sandbox-mcp"
    }
  }
}
```

The same stdio configuration is suitable for Cursor, Claude Code MCP configuration, Copilot CLI MCP configuration, and Codex MCP configuration. Consult each client’s current documentation for the location of its configuration file.

## Tools

### `run_sandboxed_command`

Inputs:

- `command`: shell command to inspect and, when safe, run
- `cwd`: optional working directory (defaults to the server process directory)
- `timeout`: optional timeout in seconds, from 1 to 300

For a low-risk command, the result contains stdout, stderr, and an exit code. For a risky command, the result contains a `request_id` and a structured risk report. No risky command is run at this stage.

### `approve_command`

Inputs:

- `request_id`: the one-time ID returned by `run_sandboxed_command`
- `approved`: `true` to execute, `false` to reject

Approval requests are held in memory and consumed exactly once. Restarting the server clears them.

## Example

An agent asks to run:

```text
rm -rf src/
```

The server returns `approval_required` with a critical finding. A human can inspect the exact command and either call `approve_command(..., approved=false)` or explicitly approve it. A harmless command such as `git status` can run immediately.

## Safety model and limitations

This MVP is a policy gate, not a container or kernel sandbox. It uses conservative pattern matching and human approval. It does not guarantee that every shell trick, encoded command, alias, environment-variable expansion, or program-level side effect will be detected. Approved commands execute with the server process’s operating-system permissions and environment.

For stronger isolation, run this server inside a disposable container or restricted OS account, keep the working directory narrow, and review commands before approval. Future work can add an argv-based execution mode, configurable policy files, audit logs, and container backends.

## Development

```bash
python -m pip install -e '.[dev]'
pytest
```

The policy module has no MCP dependency, so its tests are fast and easy to run in a minimal environment.

## License

MIT