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 provides transparent interception of Model Context Protocol (MCP) traffic, enabling you to inspect tool calls, modify messages in flight, and replay sessions for regression testing.

​
When to Use the Proxy

The proxy is a client-side interception tool. It sits between an MCP client and an MCP server, and the person running the proxy must control the client — because the client is what gets configured to route traffic through the proxy. The target server is unaware of the proxy’s presence. This means the proxy works when:
  • qai is the MCP client. When running qai audit scan or qai inject against a remote MCP server, qai itself opens the MCP connection. The proxy can intercept qai’s own traffic to the target server — no target modification required. This is the primary use case for offensive testing.
  • You control the MCP client. If you’re assessing your own MCP setup — your own Claude Desktop configuration, your own Cursor instance, your own agent framework — you can configure your client to route through the proxy for self-assessment or debugging.
The proxy does not work when the MCP client belongs to the target. If you’re testing whether a platform like LibreChat or Dify follows injected instructions from a poisoned document, the platform’s internal MCP client makes the tool calls — and you can’t configure that client without modifying the target. In those scenarios, use other evidence sources (IPI callbacks, agent response content, conversation logs) instead of proxy capture.
Once positioned in the traffic path, the proxy lets you:
  • Inspect tool calls — See exactly which tools are being invoked and with what parameters
  • Modify messages — Alter requests or responses mid-session for manual testing
  • Replay sessions — Re-send captured messages against different server implementations to test compatibility or reproduce findings
  • Drop messages — Intercept and discard specific tool invocations during manual testing

​
Core Concepts

​
Session Capture

The proxy operates as a transparent man-in-the-middle positioned between your client and server. Every message in both directions flows through the proxy envelope:
  • ProxyMessage — Wraps each JSON-RPC message with proxy metadata (timestamp, sequence number, direction, transport type)
  • ProxySession — Captures the complete sequence of messages across a single interaction, serializable to JSON for storage and replay

​
Operating Modes

Passthrough Mode (default)
  • All messages flow through unobstructed to their destination
  • Passive capture and monitoring without latency overhead
  • Use for baseline traffic recording
Intercept Mode
  • Messages are paused and held for user inspection
  • User can FORWARD unchanged, MODIFY with edits, or DROP entirely
  • Interactive TUI-based control
  • Useful for targeted analysis of specific interactions

​
Transport Support

The proxy bridges three MCP transports:
  • STDIO — Local processes communicating via stdin/stdout
  • SSE — HTTP servers using server-sent events
  • Streamable HTTP — Bidirectional HTTP for modern MCP implementations

​
Typical Workflow

  1. Start the proxy with your target server details and optionally enable intercept mode
  2. Configure the MCP client you control to connect to the proxy instead of directly to the target server
  3. Watch messages in real-time via the interactive TUI
  4. Toggle intercept mode to halt and inspect specific interactions
  5. Forward, modify, or drop messages as needed
  6. Export the completed session for evidence, testing, or audit purposes

​
What to Expect

Proxy is interactive. It captures and replays traffic but does not produce findings or vulnerability assessments. The researcher observes, inspects, and optionally modifies messages in real time. Session recordings provide evidence for later analysis, but the analysis itself is manual.

​
Chain Correlation

The proxy data model supports chain correlation via chain_run_id and chain_step_id fields on the proxy session. When populated, these enable post-execution analysis: for any chain step that involved MCP traffic through the proxy, you can find the corresponding captured messages and correlate network behavior with specific attack chain steps.
Chain correlation fields are stored and persisted by the proxy’s SessionStore and mapper, but must be explicitly passed when creating a session. Automatic propagation from the chain executor to the proxy adapter is not yet wired — if you need chain-tagged sessions, pass the chain context when constructing SessionStore.

​
Next Steps