DEV Community

Cover image for Zero-Boilerplate MCP Engineering: Compiling Typed Python Functions into Hardened JSON-RPC 2.0 Tool Servers with mcp-forge
Benni Alencar
Benni Alencar

Posted on Originally published at benni-os.net

Zero-Boilerplate MCP Engineering: Compiling Typed Python Functions into Hardened JSON-RPC 2.0 Tool Servers with mcp-forge

By **Benni Alencar* — Chief AI Systems Architect at Benni OS. Canonical article & interactive benchmarks at benni-os.net.*


1. The MCP Boilerplate Trap & Wire-Level Fragility

Every team shipping Model Context Protocol (MCP) integrations in Python hits the same wall within forty-eight hours. Writing a two-line domain function takes thirty seconds; wrapping it into a compliant MCP server takes three hundred lines of fragile plumbing. Developers copy-paste raw JSON Schema dictionaries by hand, wire an asyncio stdin/stdout loop for JSON-RPC 2.0 framing, implement initialize and notifications/initialized handshakes, and manually map exceptions into protocol error payloads.

Worse than the boilerplate tax is what breaks silently when those hand-rolled servers hit real agent traffic:

  • STDIO Wire Corruption: On MCP STDIO transport, stdout is the exclusive wire channel for newline-delimited JSON-RPC 2.0 frames. A single stray print() statement or third-party library writing to standard output injects non-JSON bytes into the stream and abruptly terminates the Claude Desktop, Cursor, or VS Code session.
  • Schema-Implementation Drift: When JSON Schemas are maintained separately from Python type annotations, adding a parameter or toggling a default value leaves the advertised inputSchema stale—causing the LLM to emit malformed arguments or pass None into non-nullable paths.
  • Silent Null Hallucinations: A tool that quietly returns None when a lookup misses is serialized as empty content unless an output validator traps the contract mismatch immediately.
  • Unbounded Hang & Blast Radius: A flat decorator wrapper without latency budgets, circuit breakers, or policy gates lets a single stalled downstream endpoint freeze an entire swarm—or lets a hallucinated tool call execute side effects on the host without human approval.

    **Core Doctrine:** Schema is derived, never hand-written; transport is a runtime concern, never business logic; and no tool is production-ready without circuit-broken latency budgets, Default-Deny policy gating, and AST-verified execution isolation.
    

2. End-to-End Synthesis Architecture: From Python Type Hints to Default-Deny Execution

The Benni OS tool infrastructure solves both ergonomics and hardening through three composable open-source layers. Benni-OS/mcp-forge acts as the FastAPI-style compiler and multi-transport server runtime, Benni-OS/benni-operator-gateway enforces Default-Deny capability routing and human-in-the-loop approval gates, and BenniAlencar/agent-code-sandbox isolates dynamic code or command evaluation behind a sub-millisecond AST scanner.

flowchart LR
    A["Typed Python Callable\n(@app.tool + Type Hints + BaseModel)"] -->|"Signature & AST Inspection"| B["mcp-forge Compiler\n(build_schema -> Draft-07 Schema)"]
    B -->|"validate_input / validate_output"| C["Resilience & Telemetry Layer\n(Circuit Breaker + P50/P90/P99)"]
    C -->|"STDIO stderr-safe / HTTP / SSE"| D["JSON-RPC 2.0 Wire\n(MCP 2024-11-05)"]
    D -->|"Risk Profile & Policy Gate"| E["benni-operator-gateway\n(Default-Deny + Approval Webhook)"]
    E -->|"Dynamic Execution Path"| F["agent-code-sandbox\n(< 0.2ms AST Guard + Ephemeral VFS)"]

Notice how clean the separation of responsibilities is: application engineers author pure typed Python functions, mcp-forge guarantees wire protocol and schema fidelity across transports, the circuit-breaker mesh prevents cascading timeouts, and the gateway/sandbox perimeter enforces authorization and host safety before side effects occur.


3. Inside the Type-to-Schema Compiler & Pre-Execution AST Inspection

At registration time, @app.tool() in mcp_forge/core/forge.py invokes build_schema(fn) from mcp_forge/core/schema.py while returning the original callable completely unmodified. Instead of forcing engineers to maintain parallel YAML or JSON manifests, build_schema() resolves typing.get_type_hints(fn) alongside inspect.signature(fn):

  • Primitive & Generic Resolution: _resolve_type() maps Python primitives (int, float, str, bool, list, dict, NoneType) to JSON Schema types and recursively unpacks parameterized generics such as list[T] (array with items) and dict[str, T] (object with additionalProperties).
  • Unions, Nullability & Required Fields: Both Optional[T] and Python 3.10+ T | None unions set "nullable": true on the resolved fragment, while multi-branch unions compile to anyOf. Any parameter whose default is inspect.Parameter.empty is automatically appended to required.
  • Pydantic v2 BaseModel Expansion: When a parameter or return annotation is a Pydantic BaseModel subclass, mcp-forge delegates directly to annotation.model_json_schema(), preserving nested constraints, descriptions, and field validators without reimplementing a schema engine.
  • Pre-Flight CLI Schema Gate: Before booting a transport or attaching to an IDE client, mcp-forge validate module:attribute imports the Forge instance and runs jsonschema.Draft7Validator.check_schema() across every registered tool, failing CI immediately if any schema fragment is malformed.

Coupling Signature Synthesis with Pre-Execution AST Scanning

When an MCP tool accepts Python code or expression strings from an LLM, static signature validation alone is not enough—a string parameter passes JSON Schema validation even if it contains import os; os.system(...) or reflective escapes like ().__class__.__base__.__subclasses__(). That is where ASTSecurityScanner from BenniAlencar/agent-code-sandbox integrates directly inside the tool boundary.

Using Python's native ast.parse() and an ast.NodeVisitor, ASTSecurityScanner.scan() walks the syntax tree in < 0.2 ms (0.18 ms average across 1,000 benchmark cycles) and blocks any forbidden module import (os, sys, subprocess, ctypes, importlib, socket), unsafe builtin call (eval, exec, compile, open, __import__), or reflective attribute traversal (__subclasses__, __mro__, __globals__, __closure__) before a subprocess is ever spawned.


4. Hardened JSON-RPC 2.0 Wire Framing, Multi-Transport & Zero-Socket Testing

Once schemas are compiled, Forge exposes identical tool contracts over three decoupled transports selectable via app.run(transport=...) or the mcp-forge run --transport CLI flag:

  • STDIO Transport (StdioTransport): Pins Python's root logging handler to sys.stderr, connects asynchronous pipe readers to sys.stdin, and writes UTF-8 JSON lines directly to sys.stdout.buffer. It implements the 2024-11-05 MCP handshake (initialize, silent notifications/initialized, tools/list, and tools/call) and translates unregistered tools (ToolNotFoundError) or invalid inputs (ValidationError) into standard JSON-RPC -32601 and -32603 error frames.
  • HTTP REST Transport (HttpTransport): Spins up a FastAPI + Uvicorn server exposing GET /health, GET /tools, and POST /tools/{tool_name} with configurable CORS origins from ForgeConfig.
  • SSE Streaming Transport (SseTransport): Serves POST /tools/{tool_name}/stream as text/event-stream, emitting structured result, error, and done frames for streaming agent clients.

At execution time, Forge.call_tool() runs validate_input() to enforce required fields and coerce JSON primitives, transparently awaits async def tools or invokes synchronous def tools, and passes the return value through validate_output()—raising a deterministic ValidationError if a non-nullable tool silently returns None.

To prevent shared mutable state across multi-app services, app.include(router) shallow-copies contrib router definitions (such as the opt-in memory, filesystem, and web routers), while ForgeTestClient executes tool calls directly in-process via client.call() or await client.acall() with zero sockets, ports, or subprocess mocks required in pytest.


5. Circuit Breakers, Latency Budgets & P50/P90/P99 Telemetry

Synthesizing valid JSON-RPC endpoints solves protocol drift, but production agent swarms face a second class of failure: cascading tail latency and retry storms. When an external API degrades or an upstream scraper hangs, an agent loop without bounded latency burns context tokens and blocks parallel workers.

In the Benni OS runtime, mcp_forge.serve.telemetry.TelemetryEngine records rolling execution metrics (max_history=500), computing per-tool call counts (tool_distribution), error rates, and real-time latency_p50_ms, latency_p90_ms, and latency_p99_ms percentiles alongside BenchMatrixRunner dispatch sweeps. Pairing that telemetry layer with the MCPMeshSynthesizer & MCPToolContract circuit-breaker state machine adds deterministic fault isolation:

  • Per-Tool Latency Budget (timeout_ms): Every tool contract declares an explicit millisecond budget enforced via asyncio.wait_for so slow external dependencies fail cleanly before breaching swarm SLAs.
  • Three-State Circuit Breaker (closed → open → half_open): Consecutive failures increment consecutive_failures. Once the count reaches failure_threshold (for example, 3 consecutive faults), the circuit flips to open, immediately rejecting subsequent calls with a structured circuit_open payload until the recovery cooldown allows a half_open probe.

6. Reference Implementation: Hardened MCP Server with Circuit Breaker & AST Sandbox

The Python module below demonstrates how mcp-forge's declarative @app.tool() decorator, Pydantic v2 schema derivation, TelemetryEngine percentile tracking, circuit-breaker latency budgets, and agent-code-sandbox's AST-verified execution combine into a single zero-boilerplate server:

import asyncio
import time
from dataclasses import dataclass, field
from typing import Any
from pydantic import BaseModel, Field

from mcp_forge import Forge, ForgeConfig
from mcp_forge.serve import TelemetryEngine
from mcp_forge.testing import ForgeTestClient
from agent_code_sandbox import SandboxEngine

app = Forge(
    name="hardened-operator-tools",
    version="1.0.0",
    config=ForgeConfig(transport="stdio", max_tool_timeout=15),
)
telemetry = TelemetryEngine(max_history=500)
sandbox = SandboxEngine()

@dataclass
class CircuitBreaker:
    failure_threshold: int = 3
    cooldown_seconds: float = 15.0
    consecutive_failures: int = 0
    state: str = "closed"  # closed | open | half_open
    opened_at: float = 0.0

    def allow_request(self) -> bool:
        if self.state == "closed":
            return True
        if self.state == "open" and (time.monotonic() - self.opened_at) >= self.cooldown_seconds:
            self.state = "half_open"
            return True
        return self.state == "half_open"

    def record_success(self) -> None:
        self.consecutive_failures = 0
        self.state = "closed"

    def record_failure(self) -> None:
        self.consecutive_failures += 1
        if self.consecutive_failures >= self.failure_threshold:
            self.state = "open"
            self.opened_at = time.monotonic()

_breakers: dict[str, CircuitBreaker] = {}

class SandboxAuditInput(BaseModel):
    code: str = Field(..., min_length=1, description="Python snippet to verify and run")
    timeout_s: float = Field(default=3.0, ge=0.2, le=10.0)

@app.tool(description="Run untrusted Python inside an AST-guarded ephemeral sandbox")
def run_sandboxed_python(payload: SandboxAuditInput) -> dict[str, Any]:
    t0 = time.perf_counter()
    res = sandbox.execute_python(code=payload.code, timeout=payload.timeout_s)
    elapsed_ms = (time.perf_counter() - t0) * 1000.0
    telemetry.record_call("run_sandboxed_python", elapsed_ms, success=res.is_safe and res.exit_code == 0)
    return res.to_dict()

@app.tool(description="Fetch upstream telemetry with circuit breaker and latency budget")
async def query_upstream_signal(endpoint: str, budget_ms: int = 1500) -> dict[str, Any]:
    breaker = _breakers.setdefault("query_upstream_signal", CircuitBreaker(failure_threshold=3))
    if not breaker.allow_request():
        telemetry.record_call("query_upstream_signal", 0.1, success=False)
        return {"status": "circuit_open", "endpoint": endpoint, "error": "Fast-failed by circuit breaker"}

    t0 = time.perf_counter()
    try:
        # Enforce deterministic per-tool latency budget
        async with asyncio.timeout(budget_ms / 1000.0):
            await asyncio.sleep(0.01)  # Replace with async httpx/DB call
            data = {"endpoint": endpoint, "signal": "nominal"}
        breaker.record_success()
        telemetry.record_call("query_upstream_signal", (time.perf_counter() - t0) * 1000.0, success=True)
        return {"status": "ok", "data": data}
    except Exception as exc:
        breaker.record_failure()
        telemetry.record_call("query_upstream_signal", (time.perf_counter() - t0) * 1000.0, success=False)
        return {"status": "error", "circuit_state": breaker.state, "error": str(exc)}

if __name__ == "__main__":
    # Zero-socket verification before attaching to STDIO / HTTP / SSE
    client = ForgeTestClient(app)
    safe_out = client.call("run_sandboxed_python", {"payload": {"code": "print(6 * 7)"}})
    assert safe_out["is_safe"] is True and "42" in safe_out["stdout"]

    blocked = client.call("run_sandboxed_python", {"payload": {"code": "import os; os.system('id')"}})
    assert blocked["is_safe"] is False

    app.run()  # Emits JSON-RPC 2.0 on stdout; logs pinned strictly to stderr
Enter fullscreen mode Exit fullscreen mode

7. Default-Deny Enforcement with benni-operator-gateway

Automatic schema derivation and input coercion ensure that parameters match their declared Python types—but schema validity is not authorization. An autonomous agent compromised by indirect prompt injection or model drift can still submit a perfectly typed JSON payload requesting a repository force push, production deploy, or secret exfiltration.

That is why Benni OS places Benni-OS/benni-operator-gateway in front of high-impact MCP tool meshes as a Default-Deny HTTP MCP Gateway:

  • Strict Capability Allowlist (CAPABILITY_REGISTRY): Every registered capability declares Zod-validated input/output schemas, a riskProfile (read, draft, execute, approval_required), timeoutPolicy, and retryPolicy. Unknown capability IDs or tools categorized as external_effect are rejected outright by isCapabilityAllowed().
  • Deterministic Approval Gate (requiresApproval()): Even for known capabilities, approval-policy.ts inspects both riskLevel and serialized payload keywords (such as merge, delete, force push, deploy, shell, exec, payment, and billing). Any risky invocation halts in pending_approval, redacts sensitive fields via redact(), and dispatches webhook links (approve_url / reject_url) to a human operator before execution resumes.
  • Transactional SQLite Decision Ledger: JobService persists every state transition (job_created, job_approved, job_rejected) inside atomic SQLite transactions with append-only auditEvents, while the hot-reload ConnectorRegistry namespaces downstream tools as connector__tool without server restarts.
// Excerpt from benni-operator-gateway approval policy & capability enforcement
export function requiresApproval(job: CreateJobInput): boolean {
  if (job.riskLevel === 'approval_required' || job.riskLevel === 'execute') return true;
  const typeLower = job.type.toLowerCase();
  if (!KNOWN_SAFE_TYPES.includes(typeLower)) return true;

  const inputJson = JSON.stringify(job.input || {}).toLowerCase();
  for (const keyword of HIGH_RISK_KEYWORDS) {
    if (inputJson.includes(keyword)) {
      if (job.type === 'repository_summary_preview' && job.riskLevel === 'read' && !inputJson.includes('merge pr')) {
        continue;
      }
      return true;
    }
  }
  return !(job.type === 'repository_summary_preview' && job.riskLevel === 'read');
}
Enter fullscreen mode Exit fullscreen mode

8. Architectural Comparison: Hand-Rolled MCP vs. Generic Wrappers vs. Benni OS Stack

Engineering Dimension Hand-Rolled JSON-RPC Scripts Generic Decorator Wrappers mcp-forge + Gateway + Sandbox
Schema Compilation Manual JSON dicts (high drift) Basic annotations only Derived Draft-07 + Pydantic v2 + CLI Gate
STDIO Wire Integrity Prone to print() corruption Mixed stdout logging risk Logs Pinned to stderr + Binary Pipe
Transport Portability Locked to one transport loop Usually STDIO-only STDIO, HTTP REST & SSE With Zero Code Change
Fault & Latency Control Unbounded hangs on downstream lag Ad-hoc timeouts per function Circuit Breakers + Latency Budgets + P99 Telemetry
Side-Effect Governance Implicit allow-all execution No human approval checkpoint Default-Deny Gateway + Webhook Approval Gate
Dynamic Code Safety Raw exec() or slow 3s+ containers No pre-execution AST inspection < 0.2 ms AST Guard + Ephemeral VFS + TokenShield

Deploy Hardened, Zero-Boilerplate MCP Infrastructure

Compile typed Python tools with Benni-OS/mcp-forge, enforce Default-Deny human approval gates with Benni-OS/benni-operator-gateway, and isolate dynamic execution in sub-millisecond time with BenniAlencar/agent-code-sandbox.




Frequently Asked Questions


      How does mcp-forge generate JSON Schema without manual schema files?
When you decorate a function with @app.tool(), mcp-forge inspects the callable using inspect.signature() and typing.get_type_hints(). Its build_schema() compiler recursively maps Python primitives, list[T], dict[str, T], Optional[T] / Union types, and Pydantic v2 BaseModel classes into a validated Draft-07 JSON Schema, automatically separating required parameters from defaults.
  Why does StdioTransport write all logs to stderr instead of stdout?
  On MCP STDIO transport, `stdout` is the exclusive newline-delimited JSON-RPC 2.0 protocol wire between the server and clients like Claude Desktop or Cursor. Any non-JSON text written to `stdout` corrupts frame parsing. `mcp-forge` pins `logging.basicConfig` to `sys.stderr` and writes serialized JSON responses directly to `sys.stdout.buffer`.


  How do circuit breakers and latency budgets prevent cascading failures in MCP tool meshes?
  Every synthesized tool contract tracks per-tool latency budgets (`timeout_ms`), rolling P50/P90/P99 telemetry via `TelemetryEngine`, and consecutive failure counts. When faults hit the failure threshold, the circuit breaker transitions from `closed` to `open`, returning an immediate structured `circuit_open` error instead of hanging the agent loop.


  How do benni-operator-gateway and agent-code-sandbox harden mcp-forge tools?
  `benni-operator-gateway` acts as a Default-Deny HTTP MCP broker that blocks unregistered capabilities and `external_effect` tools, inspects payload risk keywords, pauses high-risk actions in `pending_approval` with human webhook callbacks, and records redaction-safe audit trails. For tools executing dynamic code, `agent-code-sandbox` adds a sub-0.2ms AST security scanner, ephemeral workspace SHA-256 diffing, and stdout token shielding.
Enter fullscreen mode Exit fullscreen mode
Enter fullscreen mode Exit fullscreen mode




Frequently Asked Questions

How does mcp-forge generate JSON Schema without manual schema files?

When you decorate a function with @app.tool(), mcp-forge inspects the callable using inspect.signature() and typing.get_type_hints(). Its build_schema() compiler recursively maps Python primitives, list[T], dict[str, T], Optional[T] / Union types, and Pydantic v2 BaseModel classes into a validated Draft-07 JSON Schema, automatically separating required parameters from defaults.

Why does StdioTransport write all logs to stderr instead of stdout?

On MCP STDIO transport, stdout is the exclusive newline-delimited JSON-RPC 2.0 protocol wire between the server and clients like Claude Desktop or Cursor. Any non-JSON text written to stdout corrupts frame parsing. mcp-forge pins logging.basicConfig to sys.stderr and writes serialized JSON responses directly to sys.stdout.buffer.

How do circuit breakers and latency budgets prevent cascading failures in MCP tool meshes?

Every synthesized tool contract tracks per-tool latency budgets (timeout_ms), rolling P50/P90/P99 telemetry via TelemetryEngine, and consecutive failure counts. When faults hit the failure threshold, the circuit breaker transitions from closed to open, returning an immediate structured circuit_open error instead of hanging the agent loop.

How do benni-operator-gateway and agent-code-sandbox harden mcp-forge tools?

benni-operator-gateway acts as a Default-Deny HTTP MCP broker that blocks unregistered capabilities and external_effect tools, inspects payload risk keywords, pauses high-risk actions in pending_approval with human webhook callbacks, and records redaction-safe audit trails. For tools executing dynamic code, agent-code-sandbox adds a sub-0.2ms AST security scanner, ephemeral workspace SHA-256 diffing, and stdout token shielding.


Explore the Benni Master OS Open-Source Ecosystem

Top comments (0)