Skip to main content
Glama

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:

  1. 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, .env credential harvesting, and subprocess environment variable leakage (os.environ).

  2. Heavy Container Sandboxes (docker run MCP 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 workspace_root, os.path.realpath() boundary verification, O_NOFOLLOW | O_NONBLOCK descriptor opens, and fstat(fd) S_ISREG verification.

Blocks ../../ path traversal, intermediate directory symlink escapes (CWE-59), TOCTOU swaps (CWE-367), and /dev/zero or named pipe (mkfifo) hang attacks (CWE-400).

Layer 2: Sensitive File Denylist

Unicode NFC normalization + automatic rejection of .env* (while allowing .env.example), *.pem, *.key, id_rsa*, .git/config, .git/credentials, .npmrc, *.tfstate*, and cloud service-account keys.

Blocks silent credential harvesting (OWASP LLM06) even when secret files reside physically inside the workspace root.

Layer 3: Zero-Trust Env Scrubbing

Subprocesses never inherit os.environ. A clean-room environment is constructed with safe PATH, LANG=en_US.UTF-8, and HOME/TMPDIR redirected to .aegis-sandbox/tmp inside the jail.

Prevents malicious or injected LLM scripts (import os; print(os.environ)) from stealing host OPENAI_API_KEY, ANTHROPIC_API_KEY, GITHUB_TOKEN, or AWS keys (CWE-526).

Layer 4: Kernel Resource Limits & Process-Group Watchdog

Subprocesses run in an isolated session (start_new_session=True / setsid) with POSIX setrlimit (RLIMIT_CPU, RLIMIT_FSIZE, RLIMIT_NOFILE, RLIMIT_CORE=0), non-blocking selectors.DefaultSelector dual-pipe draining, and monotonic os.killpg(pgid, SIGKILL) on timeout.

Eliminates 64KB OS pipe buffer deadlocks, infinite loops, disk-filling bombs, and orphan grandchild processes. Optional macOS sandbox-exec (Seatbelt) kernel profile (--enable-seatbelt).

Layer 5: Bounded Output & Egress Secret Redactor

Caps stdout/stderr and file reads at 64 KB ($O(1)$ bounded memory) and scrubs inline high-entropy credentials (AWS AKIA..., GitHub ghp_..., OpenAI/Anthropic sk-..., Google AIza..., Bearer tokens, PEM private keys) prior to JSON-RPC serialization.

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 functional Result[T, DomainError] monad, RFC 7807 Problem Details error serialization, RFC 9562 UUIDv7 generator, Unicode NFC normalizer, SensitiveFileMatcher, SecretRedactor, and CommandArgumentGuard.

  • 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, W3C traceparent propagation via contextvars.ContextVar, Single-Line NDJSON structured logging on stderr with recursive PII/Secret scrubbing, and RED latency telemetry ($p50, p95, p99$).


Exposed MCP Tools

Tool Name

Mode

Description

fs_read_file

Read-Only

Read UTF-8 text files with line range (start_line, end_line), byte cap, SHA-256 digest, and inline secret redaction.

fs_list_directory

Read-Only

Iterative BFS directory listing (max_depth <= 10). Sensitive files are flagged as protected_sensitive.

fs_search_text

Read-Only

Streaming literal/regex search across workspace files with ReDoS protection and automatic binary/secret skipping.

fs_write_file

--allow-write

Atomic file creation/update via O_NOFOLLOW temp-file swap (.aegis_tmp_<uuidv7> + os.replace), optional expected_sha256 CAS, and idempotency_key.

fs_patch_file

--allow-write

Atomic exact-block replacement (target $\rightarrow$ replacement) with expected_sha256 CAS and idempotency_key.

exec_python

--allow-exec

Execute isolated Python code inside the workspace with clean-room environment, POSIX rlimit, and process-group timeout SIGKILL.

exec_command

--allow-exec

Execute allowlisted binaries (pytest, ruff, mypy, git, ls, wc, head, tail, python3) with shell=False and dangerous git flag blocking.

sandbox_inspect_policy

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.py

Run the 5-Gate Verification Harness

chmod +x scripts/verify.sh
./scripts/verify.sh

MCP 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 tools
exec_commandA
Destructive

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_pythonB
Destructive

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_directoryA
Read-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_fileA
Idempotent

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_fileA
Read-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_textB
Read-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_fileA
DestructiveIdempotent

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_policyA
Read-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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • F
      license
      A
      quality
      B
      maintenance
      Enables 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.
      14
      3
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      15
      MIT