Skip to main content
Intercept mode pauses MCP messages between client and server, allowing you to inspect JSON-RPC payloads and optionally modify them before forwarding.

​
Starting Intercept Mode

Enable intercept mode on startup: 
qai proxy start \
  --transport stdio \
  --target-command "python my_server.py" \
  --intercept
Or toggle intercept mode during a session by pressing i in the TUI.
Start in passthrough mode (default) for full-session capture, then switch to intercept mode when you need to slow down and inspect specific messages.

​
TUI Layout

The proxy interface displays three panels: Message List (left)
  • Scrollable list of all intercepted messages in chronological order
  • Client-to-server messages prefixed with ▶
  • Server-to-client messages prefixed with ◀
  • Held messages show a pause icon (⏸)
  • Dropped messages show a cross mark (✕)
  • Select any message with arrow keys or mouse
Message Detail (right)
  • Full JSON-RPC payload of the selected message
  • In edit mode, becomes an editable text area
  • Syntax highlighting for JSON
  • Press m to enter edit mode
Status Bar (bottom)
  • Current mode: [PASSTHROUGH] or [INTERCEPT]
  • Total message count and held message count
  • Server connection status

​
Message Actions

When a message is held, you can take one of three actions:
ActionCommandEffect
FORWARDf or F5Send the message to its destination unchanged
MODIFYm or F6Edit the JSON payload, then send the modified version
DROPd or F8Discard the message without forwarding
Dropping messages may cause the other side to timeout or report protocol errors. Use carefully.

​
Keyboard Shortcuts

KeyAlternateAction
qQuit the proxy and save session
iToggle intercept mode on/off
fF5Forward the held message
dF8Drop the held message
mF6Enter edit mode to modify the message
Ctrl+SConfirm edit and send modified message
EscapeCancel edit (forward message as-is)
sSave session to file
rF9Replay the selected message against the server
/Focus the filter input for searching messages
Arrow keysNavigate message list and edit mode

​
Edit Mode

Press m or F6 on any message to enter edit mode:
  1. The detail panel becomes a JSON text editor
  2. Modify the JSON-RPC payload as needed
  3. Press Ctrl+S to validate and forward the modified message
  4. Press Escape to cancel (original message is forwarded)
Validation:
  • The editor validates JSON structure before sending
  • Invalid JSON or schema errors appear in a notification
  • The editor stays open so you can fix issues and retry
Example modification: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "original query"
    }
  }
}
Change the query and press Ctrl+S to send the modified request.

​
Message Filtering

Press / to focus the filter input and search for specific messages. Filter syntax:
PrefixEffectExample
>Client-to-server only>initialize
<Server-to-client only<result
(none)Substring match on method or payloadtools/call
Press Escape in the filter input to clear and return to the full list.

​
Mode Behavior

When switching from INTERCEPT to PASSTHROUGH: All currently held messages are automatically forwarded without modification. When switching from PASSTHROUGH to INTERCEPT: All new messages are held; previously passed messages are not affected.

​
Use Cases

Inspect Before Forwarding
  • Verify tool calls match expectations before sending
  • Check response payloads for unexpected data
Modify on the Fly
  • Change tool arguments to test edge cases
  • Inject test data into responses
  • Alter method names to test error handling
Block Dangerous Calls
  • Drop risky tool calls before they reach the target
  • Intercept and modify sensitive parameters
  • Test fallback behavior by dropping responses
Intercept mode slows message processing because each message waits for user action. Use it for targeted inspection of specific interactions, not for passive bulk capture. For high-volume recording, run in passthrough mode.

​
Performance Considerations

  • Each held message adds latency while waiting for action
  • Filter input does not block message capture
  • Switching modes is instantaneous
  • Saved sessions record all metadata including which messages were modified