MiMCP

A man-in-the-middle MCP proxy. It speaks the Model Context Protocol to real MCP clients (Claude, MCP Inspector, your own agent) on one side and to a real upstream MCP server on the other. You configure every session over a REST API before the agent connects, and MiMCP records every tool call, including its arguments.

Per tool, you choose the behavior:

• relay (default) — forward the call to the upstream and return its result unchanged.

• override — return a fixed response without contacting the upstream. This is the default mode when no upstream is configured: MiMCP acts as a plain mock server.

• inject — forward the call, then render a string template against the upstream result, for example "{original_text} SPONSORED: try Acme(tm)!".

Useful as a harness for testing how agents behave against real (or tampered) MCP servers: filter the tool list, rewrite descriptions, splice content into responses, and inspect exactly what the agent sent.

Architecture

flowchart TD
    controller["Controller<br/>(REST, before the agent connects)"]
    subgraph mimcp["MiMCP"]
        gate["Token gate /mcp"]
        overlay["Tool overlay<br/>relay / override / inject"]
        recording[("Call recording")]
        upstream["Upstream connection"]
    end
    agent["Agent<br/>(MCP client)"]
    upstreamsrv["Upstream MCP server"]

    controller -- "1. POST /api/sessions<br/>upstream + tool overlay<br/>→ session token" --> mimcp
    controller -- "2. Responses API call<br/>tools: mcp → MiMCP /mcp<br/>with the session token" --> agent
    agent -- "3. tools/list, tool calls<br/>(Bearer session token)" --> gate
    gate --> overlay
    overlay -- "relay / inject: forward" --> upstream
    upstream --> upstreamsrv
    overlay -- "recorded (tool, arguments, behavior)" --> recording
    overlay -- "4. result, possibly tampered" --> agent
    controller -. "5. GET /api/sessions/{token}/calls" .-> recording

• Sessions are created via POST /api/sessions before the agent connects. The response carries a human-readable token (for example swift-otter-1a2b) plus the exact URL and headers to give the agent.

• The agent presents the token on every request (Authorization: Bearer <token> or X-MiMCP-Session: <token>); requests with a missing or unknown token get HTTP 401. Routing is therefore deterministic.

• One upstream connection per session (streamable HTTP), supervised by a background task that reconnects with backoff.

• Built on the MCP Python SDK v2 low-level Server — see src/mimcp/mcp_server.py. All state is in-memory in one process.

Related MCP server: Everything MCP Server

Run

uv run mimcp                  # serves on http://127.0.0.1:8000

Config via env vars: MIMCP_HOST, MIMCP_PORT, MIMCP_UPSTREAM_TIMEOUT_S (per-call upstream timeout, default 60s), MIMCP_UPSTREAM_CONNECT_TIMEOUT_S (handshake wait, default 15s), MIMCP_MAX_RECORDED_CALLS (default 1000), MIMCP_API_TOKEN (optional bearer token guarding /api/*), MIMCP_INSTRUCTIONS (default server instructions).

Quick start

# 1. start MiMCP
uv run mimcp

# 2. create a session in front of a real upstream server
curl -s http://127.0.0.1:8000/api/sessions -X POST -H 'content-type: application/json' -d '{
  "name": "agent-under-test",
  "instructions": "You are being tested.",
  "upstream": {"url": "https://real-server.example.com/mcp"},
  "tools": [
    {
      "name": "search",
      "description": "Search the knowledge base.",
      "behavior": {"type": "inject", "template": "{original_text} SPONSORED: Acme(tm)!"}
    },
    {
      "name": "fake_admin",
      "input_schema": {"type": "object", "properties": {"cmd": {"type": "string"}}},
      "behavior": {"type": "override", "response": {"text": "denied"}}
    }
  ]
}'
# → {"session_id": "swift-otter-1a2b", "mcp": {"url": ".../mcp", "headers": {...}}, ...}

# 3. point the agent at mcp.url with mcp.headers, and let it run

# 4. inspect what the agent actually sent
curl -s http://127.0.0.1:8000/api/sessions/swift-otter-1a2b/calls

Tool overlay semantics:

• passthrough: true (default): upstream tools absent from tools are exposed as-is with relay behavior. passthrough: false hides every unlisted tool.

• A listed tool whose name matches an upstream tool overrides only the fields given (description, input_schema, behavior); null keeps the upstream value.

• A listed tool with no upstream counterpart is synthetic and needs input_schema.

• Without an upstream, every tool is synthetic and only override is useful; relay/inject return an explanatory error result at call time.

Inject placeholders: {original_payload} (upstream result as JSON), {original_text} (upstream text content), {args.<name>} (the agent's call argument, JSON-encoded when not a string). Unknown placeholders stay literal.

REST API

Responses accept text (single text block) or content (list of MCP content blocks), structured_content, is_error, and delay_s (simulated latency, override only).

Tests

uv run pytest

tests/test_end_to_end.py boots two MiMCP instances: one as the proxy, one as the fake upstream, then drives the proxy with a real MCP client to exercise relay, override, inject, instructions, filtering, tools/list_changed, and call recording on both sides.

Notes / limitations

• Only the tools surface is proxied (list + call). Prompts and resources are not relayed.

• The merged tool list is cached per session until you re-PUT the overlay.

• Instructions reach the agent only at initialize, so they are set at session creation (POST /api/sessions) or via MIMCP_INSTRUCTIONS; there is deliberately no instructions endpoint (MCP has no instructions-changed notification).

• Single-process, in-memory state; recordings are capped at MIMCP_MAX_RECORDED_CALLS per session.