mcp-app-harness

A small, working reference implementation of the pattern behind an RL-training sandbox: take a real application, run it in a container, and expose it to an agent through a FastMCP server — with populate / snapshot / restore hooks so every episode starts from an identical, known state and any trajectory can be checkpointed and rewound.

It's deliberately tiny (a support-desk service + its MCP integration) so the seams are visible. Swap the demo app for any web/desktop app and the harness structure is unchanged.

┌────────────────┐        MCP tools/resources        ┌────────────────────┐
│  Agent / RL    │  ───────────────────────────────▶ │  FastMCP harness   │
│  policy        │  create_ticket, populate,          │  (mcp_harness/)    │
└────────────────┘  snapshot, restore, tickets://all  └─────────┬──────────┘
                                                                 │ HTTP (httpx)
                                                                 ▼
                                                       ┌────────────────────┐
                                                       │  App under test    │
                                                       │  FastAPI + SQLite  │
                                                       │  (app/)            │
                                                       └────────────────────┘

Why this exists

Integrating an app into a sandbox has three hard parts, and this repo shows a clean answer to each:

1. Expose the app to an agent. Every product operation is a typed MCP tool (mcp_harness/server.py) and live state is an MCP resource. Schemas come free from the type hints.

2. Make state reproducible. populate() seeds a deterministic baseline; snapshot() captures full state; restore() re-applies it. restore(snapshot(x)) == x is asserted in the tests (tests/test_hooks.py).

3. Keep it testable locally. The HTTP client is transport-injectable, so the whole stack runs in-process over httpx.ASGITransport in CI — no sockets, no flakiness — while production uses real HTTP unchanged.

Layout

Run it

Tests (fastest way to see it work):

uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest -q

Locally, two processes:

# terminal 1 — the app under test
./scripts/run_app.sh                       # http://localhost:8080/health

# terminal 2 — an episode: populate → act → snapshot → reset → restore
./scripts/demo_episode.sh

The MCP server:

python -m mcp_harness.server               # stdio (embed in an agent runtime)
MCP_TRANSPORT=http python -m mcp_harness.server   # HTTP transport on :9000

In a sandbox (Docker):

docker compose up --build
# app  → :8080   |   MCP harness (HTTP) → :9000

The MCP surface

Tools: create_ticket, list_tickets, get_ticket, assign_ticket, close_ticket, populate, snapshot, restore. Resources: tickets://all (live ticket list), health://app (liveness).

An agent's loop looks like: populate() → read tickets://all → call ticket tools → snapshot() to checkpoint. An RL runner scores the resulting state and restore()s to branch a new rollout.

Configuration (all via env — no code changes between environments)

Adapting to a real app

app/ is the throwaway part. To integrate a real app:

• Point AppClient (or a subclass) at the app's actual API.

• Re-implement the three hooks against whatever state seam the app exposes — a DB volume snapshot, a docker commit, an export/import endpoint, or a management command. The tool/resource layer and the tests don't change.

License

MIT.