# mcp-sandbox-server

A remote [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that gives an AI agent authenticated shell and file access to a sandbox host — plus a safe, narrow path to trigger deploys on a separate production host it should never have full access to.

## What it does

- **Core MCP tools** (`run_command`, `read_file`, `write_file`, `list_directory`) exposed over Streamable HTTP, so an agent can build/test code directly on the sandbox.
- **A minimal OAuth 2.1 authorization server**, built from scratch: dynamic client registration (RFC 7591), an authorize endpoint gated by a single admin credential, and a token endpoint with PKCE. This exists because MCP clients (like claude.ai's connector UI) expect a full OAuth flow, not a pasted bearer token — so the server has to speak it, even for a single-admin setup.
- **A restricted gateway to a second, more sensitive host** (`biscuit_status`, `biscuit_logs`, `biscuit_deploy`, etc.). Rather than trusting the tool code alone to keep the agent in bounds, the actual boundary lives one layer down: a dedicated SSH key is restricted via `command="..."` in `authorized_keys` on the target host, so no matter what the client sends over that key, only one fixed, whitelisted script can ever run. The tool code here just constructs the literal action string — it isn't the security boundary, the forced command is.

## Why it's built this way

The interesting constraint is that the same agent needed two very different trust levels: full, unrestricted shell on a disposable sandbox, but only a handful of pre-approved, read-mostly operations on a host running live services. Rather than trying to sandbox the agent's *behavior* (prompting, tool descriptions, etc.), the design pushes the actual boundary down to something the OS enforces regardless of what the agent decides to send — a forced SSH command and a path-traversal-checked whitelist script.

## Stack

Node.js, Express, `@modelcontextprotocol/sdk`, Zod. No database — auth state persists to a small JSON file next to the server.

## Note

This is a trimmed, identifier-scrubbed copy of a server actually running in production. Real hostnames, IPs, and internal project names have been replaced with placeholders (`your-production-server-ip`, `project-a`/`project-b`/`project-c`, etc.).