MCP Agent Execution Runtime

A Python runtime for inspectable agent workflows that need MCP tools, bounded code execution, session-scoped context, policy decisions, traces, and regression evaluation. The implementation is deterministic so every routing, memory, and execution decision can be tested without a hosted model.

What it implements

• Official stdio Model Context Protocol server built with the MCP Python SDK.

• Four tools: run_agent_workflow, run_bounded_python, get_session_context, and list_runtime_skills.

• Declarative skill registry mapping named skills to capabilities and risk levels without duplicating execution logic.

• Role-separated planner, execution, and reviewer subagents coordinated by a workflow orchestrator.

• Expression-only Python execution in an isolated child interpreter with AST allowlists, an empty working directory, a cleared environment, timeouts, output limits, and best-effort POSIX CPU, memory, file, and descriptor limits.

• SQLite session memory with namespace validation, entry and context-window limits, secret redaction, and explicit deletion.

• JSONL observability traces containing hashes, timings, policy results, and status without raw prompts or secrets.

• Deterministic evaluation cases with a quality gate and JSON/Markdown reports.

• Unit, integration, MCP client/server, and policy-denial tests in GitHub Actions.

Architecture

flowchart LR
  A["MCP client"] --> B["Official stdio MCP server"]
  B --> C["Runtime tool service"]
  C --> D["Workflow orchestrator"]
  D --> E["Planner subagent"]
  D --> F["Execution subagent"]
  D --> G["Reviewer subagent"]
  D --> L["Declarative skill registry"]
  F --> H["Bounded Python child process"]
  D --> I["SQLite session memory"]
  C --> J["JSONL trace recorder"]
  K["Evaluation cases"] --> C

See docs/architecture.md for module responsibilities and docs/security.md for the execution threat model.

Run locally

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests -v
mcp-agent-runtime eval --cases evals/runtime_cases.json --report-dir reports
mcp-agent-runtime run "calculate: sum([4, 8, 15, 16, 23, 42])" --session example

Run the MCP server

mcp-agent-runtime mcp

Configure a compatible MCP client to start the installed mcp-agent-runtime executable with the mcp argument. The integration test launches the server over stdio, completes initialization, lists the three tools, and calls the workflow tool.

Evaluation gate

mcp-agent-runtime eval --cases evals/runtime_cases.json --report-dir reports

The supplied cases cover allowed arithmetic and collection operations plus denial of import and attribute-access attempts. A release passes only when all cases meet their expected status and value.

Container execution

Build the image:

docker build -t mcp-agent-execution-runtime .

Run the MCP server with additional container restrictions:

docker run --rm -i \
  --network none \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --pids-limit 64 \
  --memory 256m \
  --cpus 0.5 \
  mcp-agent-execution-runtime mcp

Security boundaries

The expression runner is layered and deliberately narrow. It is useful for demonstrating policy enforcement and resource controls, but it is not described as a complete hostile-code security boundary. Production execution should add an independently hardened container or microVM boundary, syscall filtering, per-tenant credentials, network policy, image provenance, and centralized audit storage. See docs/security.md.

Evidence boundaries

This is a portfolio runtime using deterministic subagents and local storage. It does not call a live LLM, operate against customer systems, prove manufacturing scale, or claim production-grade isolation. Those limits are intentional and documented so the implemented controls remain interview-defensible.