mcp-runtime

<div align="center">

<img src="https://raw.githubusercontent.com/Devopstrio/.github/main/assets/Browser_logo.png" height="90"/>

<h1>mcp-runtime</h1>

<p><strong>High-Performance Model Context Protocol (MCP) Execution Engine & Sandbox Runtime</strong></p>

</div>

---

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.

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.

---

<div align="center"> © 2026 Devopstrio — Engineering the Autonomous Enterprise. </div>