Protocol tracing¶
--trace writes a redacted log of the MCP exchange to stderr. Command results stay on stdout. Tracing is off until you pass --trace, -v/--verbose, or set MCPDEV_TRACE / MCPDEV_VERBOSE.
The CLI contract is in CLI. Secret handling is in Diagnostics.
Enable¶
Human waterfall (default, 512-byte payload previews):
mcpdev --trace --command ./bin/weather inspect tools
Full redacted request and response bodies (-v / --verbose):
mcpdev -v --command ./bin/weather inspect tools
JSON Lines (one object per event, still on stderr):
mcpdev --trace --trace-format json --format json --url http://127.0.0.1:8080/mcp inspect |
jq .
--format is the command result. --trace-format is only the stderr trace. Enabling the trace does not change the JSON or human document on stdout.
Environment: MCPDEV_TRACE, MCPDEV_VERBOSE, MCPDEV_TRACE_FORMAT=json.
What is recorded¶
Each event has a monotonic seq and elapsed_ms from the start of the process.
kind |
Meaning |
|---|---|
frame |
One stdio JSON-RPC line (client → or server ←). |
http_request |
One Streamable HTTP POST or GET, with redacted headers. |
http_response |
Status and content type. JSON bodies get a preview; SSE bodies do not (they are sse events). |
sse |
One server-sent event from POST or GET. |
retry |
Discover version retry or GET SSE reconnect. Not a second copy of the frame. |
fallback |
Initialize after a legacy-shaped discover failure, or --no-discover. |
cancel |
Context deadline or interrupt. Not a JSON-RPC notifications/cancelled. |
stderr |
Bounded stdio child stderr. Never parsed as JSON-RPC. |
HTTP traces are request/response/SSE only. Stdio traces are frames only. The NDJSON pipe used to speak HTTP to the protocol layer is not also recorded as frames.
--trace payload previews are capped (default 512 bytes) after redaction. truncated: true means the preview was cut; the JSON document stays valid. -v / --verbose (or MCPDEV_VERBOSE=true) still redacts secrets but does not cap the payload.
Security¶
Headers such as Authorization, cookies, API keys, tokens, and passwords are replaced with [REDACTED] before the event is stored or printed. JSON object keys with those names are redacted the same way. Child stderr is treated as untrusted text, not as a protocol frame.
Do not paste live traces that still contain secrets from server tool arguments whose keys are not in that list.
Failure modes¶
| Situation | What you see |
|---|---|
| Trace off | No extra stderr from this feature. |
| Trace on, command succeeds | Result on stdout; ordered events on stderr (512-byte payload previews). |
| Verbose on, command succeeds | Result on stdout; ordered events on stderr with full redacted bodies. |
Secret in --header |
Value is [REDACTED] in the trace. |
| Child logs JSON-RPC on stderr | stderr event, not frame / protocol_error. |