Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.q-uestionable.ai/llms.txt

Use this file to discover all available pages before exploring further.

The proxy module (q_ai.proxy) intercepts MCP traffic between a client and server for inspection, modification, and replay. It operates as a man-in-the-middle, presenting itself as the server to the client while forwarding messages to the real server.

​
Module Structure

proxy/
├── intercept.py         # Message interception logic
├── pipeline.py          # Processing pipeline for messages
├── session_store.py     # Session persistence (JSON files)
├── correlation.py       # Request-response message correlation
├── replay.py            # Session replay against live servers
├── models.py            # ProxyMessage, ProxySession, Transport, Direction
├── tui/                 # Textual TUI for interactive session review
│   └── app.py           # ProxyApp — main TUI application
├── adapters/
│   ├── stdio.py         # StdioServerAdapter for child process servers
│   ├── sse.py           # SseServerAdapter for SSE servers
│   └── streamable_http.py # StreamableHttpServerAdapter
├── exporting/           # Export to JSON
├── cli.py               # start, replay, export, inspect commands
├── adapter.py           # ProxyAdapter for orchestrator integration
└── mapper.py            # persist_session() — bridges to core DB

​
How It Works

qai proxy start launches the TUI. The proxy:
  1. Spawns the target MCP server (stdio) or connects to it (SSE/HTTP)
  2. Presents itself as the server to the client
  3. Records all messages with timestamps, direction, and sequence numbers
  4. In passthrough mode: forwards messages transparently
  5. In intercept mode: pauses on each message for inspection/modification

​
Session Model

A session is a sequence of ProxyMessage objects. Each message records:
  • direction — CLIENT_TO_SERVER or SERVER_TO_CLIENT
  • method — MCP method name (e.g., tools/call, initialize)
  • jsonrpc_id — For request/response correlation
  • sequence — Ordering within the session
  • raw — Full JSON-RPC message
  • original_raw — Pre-modification content (if intercepted and changed)
  • modified — Boolean flag
  • correlated_id — Links requests to their responses
Sessions persist as JSON files via SessionStore.

​
Replay

qai proxy replay replays recorded client-to-server messages against a live server:
  • Loads a saved session file
  • Optionally sends a synthetic initialize handshake
  • Sends each client→server message to the target
  • Records responses and latency
  • Reports success/failure per message
Supports replay against stdio servers (--target-command) or HTTP servers (--target-url).

​
TUI

The Textual-based TUI provides:
  • Chronological message list with direction indicators (→ client→server, ← server→client)
  • Message expansion for full JSON payload inspection
  • Intercept mode with pause/modify/forward controls

​
Adapter

ProxyAdapter wraps session recording for orchestrator workflows. It creates a child run, starts the proxy, and persists the session to the database on completion or failure.

​
Export

qai proxy export serializes a session to JSON. qai proxy inspect prints session contents to stdout with optional --verbose for full JSON payloads.