Skip to main content
The replay engine re-sends captured client-to-server messages from a session file against a live MCP server, collecting new responses for comparison.

​
Workflow

  1. Capture a session with proxy start --session-file:
qai proxy start \
  --transport stdio \
  --target-command "python my_server.py" \
  --session-file session.json
  1. Replay the captured messages against a server:
qai proxy replay \
  --session-file session.json \
  --target-command "python my_server.py"

​
Command reference

qai proxy replay [OPTIONS]
OptionRequiredDescription
--session-fileYesPath to a saved session file
--target-commandYes*Server command for replay (stdio)
--target-urlNoServer URL for replay (SSE/HTTP)
--outputNoSave replay results to JSON
--timeoutNoPer-message response timeout in seconds (default: 10.0)
--no-handshakeNoSkip auto-handshake if session already includes initialize
* Either --target-command or --target-url is required.

​
Auto-handshake

By default, the replay engine sends a synthetic initialize / notifications/initialized handshake before replaying messages. This ensures the server is ready to accept tool calls. Use --no-handshake if your session file already starts with the initialize sequence and you want to replay it exactly.

​
Modifying arguments

Replay sends messages exactly as captured. To modify arguments before replaying:
  1. Export or inspect the session to find the message you want to change
  2. Edit the session JSON file directly — modify the payload field of the target message
  3. Replay the edited session

​
Saving results

Use --output to save replay results as JSON: 
qai proxy replay \
  --session-file session.json \
  --target-command "python my_server.py" \
  --output replay-results.json
The output includes the original request, sent message, server response, error (if any), and round-trip duration in milliseconds for each replayed message.

​
Timeout

The --timeout option sets the per-message response timeout in seconds (default: 10.0). Increase this for slow servers: 
qai proxy replay \
  --session-file session.json \
  --target-command "python my_server.py" \
  --timeout 30.0
Messages that exceed the timeout are recorded with a timeout error.

​
Use case: reproducing findings

Replay is useful for reproducing audit findings. After a scan identifies a vulnerability, capture a targeted interaction with the proxy, then replay the exact message sequence to confirm the finding is reproducible: 
# 1. Capture the interaction
qai proxy start \
  --transport stdio \
  --target-command "python my_server.py" \
  --session-file evidence.json

# 2. Replay to confirm
qai proxy replay \
  --session-file evidence.json \
  --target-command "python my_server.py" \
  --output confirmation.json
Only client-to-server messages (requests and notifications) are replayed. Server-to-client messages in the session file are skipped.