Opt-in, read-only MCP tool for inspecting recent tools/call activity.
lisp_debug lets the client LLM ask "how is this server doing?" without filesystem access and without grepping JSONL traces. It is off by default; enable it with --debug-tool (or PTC_RUNNER_MCP_DEBUG_TOOL=true). When disabled there is no extra process, no ring buffer, and the tool does not appear in tools/list.
For the broader MCP server overview see mcp-server.md. For the full configuration flag reference see mcp-server-configuration.md. For the ptc_runner_mcp release itself see mcp-server-cli.md.
What gets recorded
lisp_debug records every recognized-tool tools/call — lisp_eval, lisp_task, and all lisp_session_* tools when sessions are enabled — into a bounded in-memory ring (--debug-ring-size, default 500, FIFO eviction). Successes, args_error validation failures, and busy concurrency-gate rejections are all captured. lisp_debug's own calls and unknown-tool requests are not recorded.
The ring lives in process memory: it is lost on restart, and in a multi-client process it mixes records from all clients. Both facts are surfaced in every stats response (debug_source, window, ring_count). In Streamable HTTP mode this means lisp_debug is suitable only when every bearer-token holder is in the same trust boundary; v1 does not partition the ring by HTTP session.
Operations
op is required. The three operations are:
op | What it returns |
|---|---|
stats | Aggregate health: per-tool call counts / success-error rates / latency percentiles, an error-reason histogram, upstream-call outcomes (total / ok / by_reason / by_server), agentic planner stats, a payload_reduction aggregate (totals, p50/p95/max/weighted ratio, top-N reducers, planner-token sub-block — see aggregator-mode.md), plus a self-description (ring_size, ring_count, trace_dir_enabled, payload_policy, time window). |
recent | The last limit (≤ 200, default 20) call records, newest first. errors_only: true restricts to failures; since_seconds windows by age. |
get | The full redacted record for one request_id. When --trace-dir is set, returns the on-disk JSONL trace (source: "trace_file"); otherwise the ring record (source: "ring_buffer"). |
Example
// tools/call
{ "name": "lisp_debug", "arguments": { "op": "stats" } }
// → structuredContent (abridged)
{
"op": "stats", "payload_policy": "summary", "redaction_applied": true,
"debug_source": "ring_buffer", "ring_size": 500, "ring_count": 137,
"trace_dir_enabled": false,
"window": { "from": "…", "to": "…", "calls": 137 },
"by_tool": { "lisp_eval": { "calls": 120, "ok": 110, "error": 10,
"error_rate": 0.083,
"duration_ms": { "p50": 12, "p95": 210, "max": 1400 } } },
"errors": { "by_reason": { "timeout": 4, "runtime_error": 3, "args_error": 6, "busy": 1 } }
}Configuration flags
The full flag reference lives in mcp-server-configuration.md. The flags directly relevant to lisp_debug are:
| Flag | Env var | Default | Purpose |
|---|---|---|---|
--debug-tool | PTC_RUNNER_MCP_DEBUG_TOOL | false | Expose the lisp_debug tool. Also flips the response profile to debug unless --response-profile is set explicitly. |
--debug-ring-size | PTC_RUNNER_MCP_DEBUG_RING_SIZE | 500 | In-memory ring-buffer capacity (clamped to [10, 5000]). |
--max-debug-response-bytes | PTC_RUNNER_MCP_MAX_DEBUG_RESPONSE_BYTES | 65536 (64 KiB) | Hard cap on a single lisp_debug response (raised to a 4 KiB floor if set lower); oversized responses are truncated and flagged. |
Interaction with response profiles
--debug-tool implies --response-profile debug unless a profile is set explicitly. Combine --debug-tool --response-profile slim to keep client-facing responses slim while the lisp_debug recorder still receives the full pre-slim payload internally. See the response-profile section of mcp-server-configuration.md for the full profile matrix.
Redaction
lisp_debug reuses the trace redaction stack: the active --trace-payloads policy (none / summary / full, default summary) plus Credentials.Redactor.scrub/1. It never emits data at a level higher than --trace-payloads allows; every response echoes payload_policy and carries redaction_applied: true. At none, the program field is just a SHA-256 plus byte count and context is byte counts only.
Residual leakage is still possible even after redaction — error messages (always captured in full), upstream tool/server names, upstream-call reasons, agentic planner outcomes, and (at summary) program previews. Do not enable lisp_debug on a server that handles sensitive prompts or data unless you also set --trace-payloads none, and run one server process per trust boundary (v1 does not partition the ring per client).