aegis-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aegis-mcp search the workspace for TODO comments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
aegis-mcp — Zero-SDK OS-Sandboxed Filesystem & Execution MCP Server
aegis-mcp is a raw Model Context Protocol (MCP) server engineered in pure Python (3.11+) that provides AI coding agents (Claude Code, Google Antigravity, Cursor, OpenCode, Windsurf) with deterministic Filesystem and Code/Command Execution capabilities inside a 5-layer OS security perimeter—without requiring a Docker daemon or cloud micro-VM.
Why aegis-mcp?
Current open-source MCP servers fall into two extremes:
Naive Host Filesystem Servers (
@modelcontextprotocol/server-filesystem): Rely on simple string-prefix checks (path.startsWith(root)), leaving the host vulnerable to intermediate directory symlink escapes, FIFO/device node read hangs,.envcredential harvesting, and subprocess environment variable leakage (os.environ).Heavy Container Sandboxes (
docker runMCP wrappers): Incur 1,500–3,000ms cold-start latency per tool invocation, consume gigabytes of background VM memory, and fail in Dockerless environments.
aegis-mcp delivers < 10ms local execution latency while enforcing strict kernel and OS-level security invariants.
Related MCP server: MCP ToolHub
The 5-Layer OS Security Perimeter
Layer | Security Invariant | Threat Mitigated |
Layer 1: Canonical Path Jail | Component-by-component directory walk from | Blocks |
Layer 2: Sensitive File Denylist | Unicode | Blocks silent credential harvesting ( |
Layer 3: Zero-Trust Env Scrubbing | Subprocesses never inherit | Prevents malicious or injected LLM scripts ( |
Layer 4: Kernel Resource Limits & Process-Group Watchdog | Subprocesses run in an isolated session ( | Eliminates 64KB OS pipe buffer deadlocks, infinite loops, disk-filling bombs, and orphan grandchild processes. Optional macOS |
Layer 5: Bounded Output & Egress Secret Redactor | Caps | Prevents context-window flooding and accidental secret leakage into external LLM provider logs. |
Clean Architecture & Zero-SDK Protocol Design
aegis-mcp implements the Model Context Protocol (2024-11-05 & 2025-03-26) over newline-delimited JSON-RPC 2.0 stdio from scratch without the mcp or FastMCP SDKs:
Domain Layer (
src/aegis_mcp/domain/): Pure functionalResult[T, DomainError]monad, RFC 7807 Problem Details error serialization, RFC 9562 UUIDv7 generator, UnicodeNFCnormalizer,SensitiveFileMatcher,SecretRedactor, andCommandArgumentGuard.Application Layer (
src/aegis_mcp/application/): Single-responsibility Use-Case Handlers (ReadFileHandler,ListDirectoryHandler,SearchTextHandler,WriteFileHandler,PatchFileHandler,RunPythonHandler,RunCommandHandler,InspectPolicyHandler) with SHA-256 Optimistic Concurrency Control (CAS) and LRU Idempotency-Key Replay Protection.Infrastructure Layer (
src/aegis_mcp/infrastructure/):PosixJailFileSystem,SelectorSandboxRunner, W3Ctraceparentpropagation viacontextvars.ContextVar, Single-Line NDJSON structured logging onstderrwith recursive PII/Secret scrubbing, and RED latency telemetry ($p50, p95, p99$).
Exposed MCP Tools
Tool Name | Mode | Description |
| Read-Only | Read UTF-8 text files with line range ( |
| Read-Only | Iterative BFS directory listing ( |
| Read-Only | Streaming literal/regex search across workspace files with ReDoS protection and automatic binary/secret skipping. |
|
| Atomic file creation/update via |
|
| Atomic exact-block replacement ( |
|
| Execute isolated Python code inside the workspace with clean-room environment, POSIX |
|
| Execute allowlisted binaries ( |
| Diagnostic | Return active sandbox configuration, resource limits, allowed binaries, and live RED telemetry metrics. |
Quickstart & Installation
cd /Users/71234/explore-opensource/aegis-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"Run the 8-Vector Adversarial Security Benchmark
python3 examples/demo_attack_simulation.pyRun the 5-Gate Verification Harness
chmod +x scripts/verify.sh
./scripts/verify.shMCP Client Configuration (Claude Code / Antigravity / Cursor / OpenCode)
Add aegis-mcp to your MCP client configuration (claude_desktop_config.json, .cursor/mcp.json, or Antigravity MCP settings):
{
"mcpServers": {
"aegis-sandbox": {
"command": "python3",
"args": [
"-m",
"aegis_mcp",
"--root",
"/absolute/path/to/your/project",
"--allow-write",
"--allow-exec",
"--wrap-untrusted",
"--timeout",
"5.0"
]
}
}
}For strict read-only auditing mode (Least Privilege default), omit --allow-write and --allow-exec.
License
Apache License 2.0 — see LICENSE.
Available Tools
8 toolsexec_commandADestructive
Execute an allowlisted binary (e.g. pytest, ruff, mypy, git, ls) with shell=False, argument safety guards, scrubbed environment, and process-group timeout SIGKILL.
Inputs: binary (required), cwd, args, timeout_seconds.
exec_pythonBDestructive
Execute an isolated Python code snippet inside the sandbox with zero-trust scrubbed environment variables, POSIX resource limits, and process-group timeout SIGKILL.
Inputs: code (required), args, timeout_seconds.
fs_list_directoryARead-onlyIdempotent
List files and directories inside the sandbox workspace root using bounded iterative BFS traversal. Sensitive credential files are flagged as 'protected_sensitive'.
Inputs: path, max_depth, include_hidden.
fs_patch_fileAIdempotent
Atomically replace an exact target text block inside a workspace file with optional SHA-256 Optimistic Concurrency Control (expected_sha256) and idempotency_key.
Inputs: path (required), target (required), replacement (required), expected_sha256, +1 more.
fs_read_fileARead-onlyIdempotent
Read a UTF-8 text file inside the sandbox workspace root with line-range filtering, canonical path jail verification, sensitive credential blocking, and SHA-256 digest.
Inputs: path (required), end_line, max_bytes, start_line.
fs_search_textBRead-onlyIdempotent
Search for literal text or regular expressions across files in the sandbox workspace root with automatic binary skipping, ReDoS protection, and inline secret redaction.
Inputs: query (required), path, is_regex, max_results.
fs_write_fileADestructiveIdempotent
Atomically write a UTF-8 text file inside the workspace root using O_NOFOLLOW temp-file swap, optional Optimistic Concurrency Control (expected_sha256), and idempotency_key.
Inputs: path (required), content (required), expected_sha256, idempotency_key.
sandbox_inspect_policyARead-onlyIdempotent
Inspect the active sandbox security policy, resource limits, capability flags, allowed binaries, and runtime RED telemetry metrics.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct purposes: read/list/search are separate filesystem read operations, exec_python and exec_command target different execution models, and sandbox_inspect_policy is unique. The main potential overlap is fs_write_file versus fs_patch_file, both of which edit files, though their descriptions distinguish full atomic writes from exact-block replacement.
All names use consistent snake_case and follow a predictable category-prefixed pattern (fs_, exec_, sandbox_). Minor deviation exists because the fs_ tools use verb-object forms while exec_python/exec_command are more namespace-like, but the overall convention is still readable and predictable.
Eight tools is well-scoped for a sandboxed filesystem and execution server. Each tool earns its place by covering a distinct operation, with no obvious filler or redundant tools.
The surface covers read, list, search, write, patch, execution, and policy inspection, which supports most agent workflows. However, common filesystem lifecycle operations such as delete, move/rename, and directory creation are absent, leaving notable gaps for full CRUD coverage.
Maintenance
Related MCP Connectors
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Run AI agent tasks in isolated sandboxes with a cost cap, saved workflows and scoped connections.
Securely search and manage workspace context files for AI agents and teams.
Secure Linux sandboxes for AI agents, as MCP tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to safely read and write files in a sandboxed workspace via natural language, with on-demand connection, CVE-hardened path confinement, injection resistance, and full audit logging.-
- FlicenseAqualityBmaintenanceEnables coding agents to perform workspace-confined file operations, read-only Git inspection, and structured shell commands, while requiring out-of-band human approval for mutations and external executions and maintaining an audit trail.143-
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to safely read, search, understand, and edit local project code and files, with Git inspection, code indexing, and controlled command execution within permissioned workspaces.8 npm6MIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to safely execute commands, run tests, and modify project files inside disposable, policy-enforced Docker sandboxes that are isolated from the host machine and its credentials.15MIT