MCP Powered AI Assistance

A secure, standardised AI assistant on the Model Context Protocol: an OpenAI-driven LangGraph agent that can query databases, fetch metrics, and run Python — with every untrusted execution confined to an ephemeral Docker sandbox.

User ──▶ Client Gateway (LangGraph + OpenAI)
             │  MCP over SSE (remote) or stdio (local)
             ▼
        MCP Server (FastAPI + official MCP SDK)
             │  run_python · execute_sql · fetch_metrics
             ▼
        Ephemeral Docker sandbox (no network, read-only,
        cpu/mem/pid quotas, hard timeout, orphan reaper)

State: Postgres (LangGraph checkpointer) · Events: Redis pub/sub

Layout

• server/tools.py — tool registry; Pydantic-typed schemas exposed at capability negotiation

• server/sandbox.py — ephemeral Docker execution + orphan reaper

• server/main.py — FastAPI app (SSE transport) and stdio entrypoint

• client/gateway.py — MCP client + LangGraph function-calling loop

• tests/ — protocol compliance, schema validation, sandbox security E2E

Related MCP server: spotdb

Quick start

uv sync
docker compose up -d postgres redis     # infra
uv run python -m server.main            # MCP server on :8000 (SSE at /sse)

export OPENAI_API_KEY=sk-...
uv run python -m client.gateway "How many run_python calls in the last hour?"

# or local stdio (no server process needed):
MCP_TRANSPORT=stdio uv run python -m client.gateway "print hello from the sandbox"

Tests (V&V)

uv run pytest

• Protocol compliance — initialize, tools/list (schemas present), tools/call round-trip.

• Schema validation — malformed payloads return actionable Pydantic errors to the LLM; the server never crashes.

• Sandbox security (E2E) — injected malicious code attempting host env-var reads, directory traversal, network egress, and filesystem writes is blocked; runaway code is killed at the timeout; the reaper removes crash orphans.

Production deployment

# self-signed cert for local TLS testing (use real certs / cert-manager in prod)
mkdir -p deploy/certs && openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout deploy/certs/server.key -out deploy/certs/server.crt -subj "/CN=mcp"

MCP_API_KEY=$(openssl rand -hex 32) docker compose up --build
# clients connect to https://host:8443/sse with header X-Api-Key: <key>

Containerising the MCP server is the industry standard so AI-generated code never executes with raw host access. On Kubernetes: run the server as a Deployment, give sandboxes their own node pool or use a socketless runtime (Kata/gVisor) instead of mounting the Docker socket, front with an Ingress terminating TLS. On AWS ECS: one service for the server, sandbox tasks via RunTask with an isolated task security group, ALB + ACM for TLS.

Readiness checklist

• Network isolation — sandboxes run with network_disabled=True: no egress at all, including VPC metadata endpoints.

• Resource quotas — 256 MB memory (no swap), 0.5 CPU, 64 pids, read-only rootfs, 16 MB noexec tmpfs per sandbox.

• TLS & auth — Nginx reverse proxy enforcing HTTPS and X-Api-Key auth in front of the SSE endpoint.

• Ephemeral cleanup — containers force-removed after each run; background reaper kills anything labelled mcp-sandbox=1 older than 120 s.