mcp-runtime

Executive Summary

The mcp-runtime repository delivers a high-performance, isolated execution engine and context state lifecycle manager built specifically for the Model Context Protocol (MCP). It provisions ephemeral, resource-constrained sandbox containers to execute untrusted MCP tool code securely without exposing host enterprise infrastructure.

Related MCP server: MCP Server Code Execution Mode

Business Problem

Executing tools invoked by LLMs and autonomous agents presents severe runtime security and stability risks:

• Resource Exhaustion: Unconstrained tool code can consume excessive CPU or memory, causing noisy-neighbor degradation.

• Malicious Payload Execution: Untrusted code or shell tools can attempt unauthorized host file system or network access.

• State Loss: Stateful multi-turn tool conversations require persistent context tracking across ephemeral container executions.

Business Value

• Zero-Trust Process Isolation: Enforces process sandboxing with strict cgroup memory and CPU limits per tool execution.

• Sub-Millisecond Execution Overhead: Low-overhead runtime container provisioning for real-time AI assistant responsiveness.

• Stateful Context Lifecycle Persistence: Automatically persists conversation context state across multi-turn tool calls.

Architecture

High-Level Execution Sequence

graph TD
    Gateway["MCP Gateway / AI Assistant"] --> RuntimeAPI["MCP Runtime Execution API"]
    RuntimeAPI --> Executor["MCP Tool Execution Engine"]
    RuntimeAPI --> SandboxMgr["Process Sandbox Isolation Manager"]
    RuntimeAPI --> ContextMgr["Context State Persistence Manager"]
    SandboxMgr --> Container1["Sandbox Container - Memory Limit 512MB"]
    SandboxMgr --> Container2["Sandbox Container - Memory Limit 1024MB"]

Core Components

• MCP Tool Execution Engine (src/mcp_runtime/core/executor.py): Core execution pipeline running tool handlers inside isolated sandbox containers.

• Process Sandbox Isolation Manager (src/mcp_runtime/sandbox/process_sandbox.py): Provisions, monitors, and terminates ephemeral process containers.

• Context Lifecycle State Manager (src/mcp_runtime/services/context_manager.py): Manages state storage and context restoration for agent sessions.

• FastAPI Async Transport Layer (src/mcp_runtime/api/routes.py): Asynchronous REST endpoints for tool execution, sandbox management, and state persistence.

Repository Structure

mcp-runtime/
├── .github/              # CI/CD workflows, issue & PR templates, CODEOWNERS
├── architecture/         # Mermaid sequence flow diagrams
├── deployment/           # Kubernetes manifests & Kustomize environment overlays
├── docs/                 # Enterprise architectural, deployment, & operational guides
├── examples/             # Real-world request/response JSON payloads
├── images/               # High-resolution architecture & workflow diagrams
├── src/mcp_runtime/      # Python Runtime source (api, core, sandbox, services)
├── terraform/            # Multi-cloud OpenTofu / Terraform IaC modules
├── tests/                # Unit, integration, and API test suites
├── Dockerfile            # Container build specification
├── docker-compose.yml    # Multi-container local orchestration
├── pyproject.toml        # PEP 621 package configuration
└── README.md             # Accelerator documentation manual

Capabilities

• Ephemeral Container Sandbox: Dynamic spawning and destruction of process sandboxes.

• Memory & CPU Throttling: Strict memory caps (default 512MB) and CPU core allocation per container.

• Context State Persistence: High-speed in-memory state tracking with disk serialization.

• Health & Liveness Probes: Native Kubernetes probes for container health monitoring.

Technology Stack

• Core Runtime: Python 3.11+, FastAPI 0.110+, Pydantic v2

• Infrastructure as Code: OpenTofu 1.8.5 / Terraform 1.6+

• Containerization: Docker, Docker Compose, Kubernetes 1.28+

• Quality Assurance: Pytest 8.0+, GitHub Actions CI

Implementation

# Clone repository
git clone https://github.com/Devopstrio/mcp-runtime.git
cd mcp-runtime

# Install in editable mode
pip install -e .[dev]

# Run automated unit and integration tests
pytest -v tests/

Deployment

OpenTofu / Terraform Provisioning

cd terraform
tofu init
tofu plan
tofu apply -auto-approve

Kubernetes Kustomize Deployment

kubectl apply -k deployment/kubernetes/overlays/prod/

API Reference

• GET /health — Returns runtime health status and version.

• POST /api/v1/execute — Executes an MCP tool payload inside isolated sandbox.

• POST /api/v1/sandbox/spawn — Spawns an ephemeral process container.

• DELETE /api/v1/sandbox/{container_id} — Terminates a running sandbox container.

• POST /api/v1/context/state — Persists context state for session.

Examples

• examples/sandbox-tool-execution/ — Isolated tool execution payload

• examples/runtime-container-lifecycle/ — Ephemeral container spawn payload

• examples/context-state-persistence/ — Context state persistence payload

Security

Refer to SECURITY.md for reporting security vulnerabilities. The runtime enforces process sandboxing and cgroup resource isolation.

Observability

The platform exports structured CloudWatch log groups (/aws/mcp-runtime/mcp-runtime) and metric alarms for sandbox memory exhaustion tracking.

Scalability

Horizontal pod autoscaling (HPA) overlays scale runtime worker replicas dynamically based on active container CPU load.

Multi-cloud Strategy

Infrastructure blueprints support AWS ECS/VPC deployment with modular extensions for Docker and Kubernetes containerd runtimes.

Roadmap

See docs/Roadmap.md for upcoming milestones including gVisor / Firecracker MicroVM integration and dynamic CPU cgroup throttling.

Contribution

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for community standards and contribution workflows.