Skip to main content

​
ctpf proxy

Intercept and replay MCP traffic for inspection, testing, and analysis. 
ctpf proxy [COMMAND] [OPTIONS]

​
Commands

​
proxy start

Start the proxy with an interactive TUI. 
ctpf proxy start --transport TRANSPORT [OPTIONS]
Options:
OptionRequiredTypeDescription
--transportYesstringTransport type: stdio, sse, or streamable-http
--target-commandWhen transport is stdiostringServer command to proxy (stdio only)
--target-urlWhen transport is sse or streamable-httpstringServer URL to proxy (HTTP transports only)
--interceptNoflagStart in intercept mode (default: passthrough)
--session-fileNostringAuto-save session to this file on exit
Examples: 
ctpf proxy start \
  --transport stdio \
  --target-command "python my_server.py" \
  --intercept

ctpf proxy start \
  --transport sse \
  --target-url "http://localhost:3000" \
  --session-file session.json
Use passthrough mode (default) for passive capture of complete interactions. Use intercept mode when you need to halt and inspect or modify specific messages.

​
proxy replay

Replay captured messages against a live server. 
ctpf proxy replay --session-file FILE [OPTIONS]
Options:
OptionRequiredTypeDescription
--session-fileYesstringPath to saved session file
--target-commandYes*stringServer command for replay (stdio)
--target-urlYes*stringServer URL for replay (SSE/HTTP)
--outputNostringSave replay results to JSON file
--timeoutNofloatPer-message response timeout in seconds (default: 10.0)
--no-handshakeNoflagSkip auto-handshake; session must start with initialize
* Either --target-command or --target-url is required. Examples: 
ctpf proxy replay \
  --session-file session.json \
  --target-command "python my_server.py" \
  --output results.json

ctpf proxy replay \
  --session-file session.json \
  --target-url "http://localhost:3000" \
  --timeout 30.0 \
  --output results.json
By default, the replay engine sends a synthetic initialize handshake before replaying messages. Use --no-handshake if your session already includes the full handshake sequence.

​
proxy export

Export a session to JSON. 
ctpf proxy export --session-file FILE --output OUTPUT [OPTIONS]
Options:
OptionRequiredTypeDescription
--session-fileYesstringPath to saved session file
--outputYesstringOutput file path
--output-formatNostringExport format (default: json)
Example: 
ctpf proxy export \
  --session-file session.json \
  --output report.json

​
proxy inspect

Print session contents to stdout for review. 
ctpf proxy inspect --session-file FILE [OPTIONS]
Options:
OptionRequiredTypeDescription
--session-fileYesstringPath to saved session file
--verbose, -vNoflagShow full JSON payloads for each message
Example: 
ctpf proxy inspect --session-file session.json -v
Output format: 
Session: abc-123
Transport: stdio
Server command: python my_server.py
Messages: 12

  #000 → initialize id=1
  #001 ← (response) id=1
  #002 → notifications/initialized
  #003 → tools/call id=2
Add -v to include full JSON payloads.

​
Message Direction

In inspect output:
  • → denotes client-to-server messages (requests and notifications sent to the server)
  • ← denotes server-to-client messages (responses and notifications from the server)
In the TUI (proxy start):
  • ▶ denotes client-to-server messages
  • ◀ denotes server-to-client messages
  • ⏸ prefix on held messages (intercept mode)
  • ✕ prefix on dropped messages

​
Exit Codes

CodeMeaning
0Success
1Command error (invalid options, file not found, validation failure)
130Interrupted by user (Ctrl+C)