MCP 服务器

mcp-runtime

A high-performance MCP execution engine that runs tool code in isolated, resource-constrained sandboxes with context state persistence.

README

<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

Architecture Diagram

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.