Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@log-probe-mcp Debug the intermittent checkout failure using runtime logs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An agent-agnostic MCP server for hypothesis-driven, runtime-data-backed debugging.
Point any MCP-compatible coding agent (Claude Code, Cursor, etc.) at it and say something like:
Debug this using the log-probe mcp — checkout returns the wrong cart for some users.
log-probe-mcp never edits your code. Instead it runs a local HTTP log-ingestion server, correlates incoming logs to specific executions (a script run, a test invocation, a request), and tracks hypotheses — so the calling agent can drive the classic debugging loop (form hypotheses → instrument → reproduce → analyze → converge) with real runtime data instead of guessing from static code, and without a human manually copy-pasting console output back into the chat.
The agent calls probe_server_start to spin up a local HTTP server that accepts structured log
events (POST /ingest).
It records a debugging session and a few falsifiable hypotheses (debug_session_create,
hypothesis_create).
It fetches the logging contract (instrumentation_get_contract) and inserts a few log calls at
the decision points that would distinguish between the hypotheses, using its own file-editing
tools — log-probe-mcp only tells it what to send and where to send it, it never touches your
source files itself.
It reproduces the bug, either by running a script/test itself (execution_run, which also
captures stdout/stderr automatically) or by minting an execution for something already running
(execution_create) and asking a human to trigger it.
It reads the real data back (execution_get_logs, execution_compare for flaky/intermittent
bugs) and marks each hypothesis confirmed/refuted with evidence (hypothesis_update).
Once resolved, it applies the actual fix itself, removes the temporary instrumentation, and
optionally writes a durable record (knowledge_base_export, debug_session_resolve).
Call debug_workflow_guide (or use the debug MCP prompt, on clients that support prompts) for
the full step-by-step guidance an agent needs to run this loop well.
Related MCP server: AIS Revizor
{
"mcpServers": {
"log-probe": {
"command": "npx",
"args": ["-y", "log-probe-mcp"]
}
}
}For local development against a checkout of this repo, build it and point a client directly at
dist/bin.js:
{
"mcpServers": {
"log-probe": {
"command": "node",
"args": ["/absolute/path/to/log-probe-mcp/dist/bin.js"]
}
}
}Data (the SQLite store and any exported knowledge-base files) lives under .log-probe/ in the
project the agent is working in. Because MCP clients don't consistently launch servers with cwd
set to the project root, the authoritative source is, in priority order: the dataDir argument to
probe_server_start, the LOG_PROBE_DATA_DIR environment variable, then the server process's own
cwd.
Tool | Purpose |
| Ingestion server lifecycle |
| Track a debugging investigation |
| Track falsifiable hypotheses and their evidence |
| Mint/run/query correlated executions |
| The ingestion HTTP contract + ready-to-paste snippets per language |
| The hypothesis-driven methodology, full guide or per-stage |
| Writes a durable markdown record of a session |
Plus a debug MCP prompt for clients that support the prompts primitive — a thin wrapper around
debug_workflow_guide's content, so guidance is reachable via tools everywhere regardless of
prompt support.
Instrumented code sends a POST to <ingestion url>/ingest with a JSON body (single event, or an
array of up to 500 for batching):
{
"executionId": "exec_...",
"hypothesisId": "hyp_...",
"level": "info",
"message": "cache key computed",
"data": { "key": "route:/x" },
"source": "checkout.ts:88"
}executionId must already exist (minted via execution_create or execution_run) — this is what
correlation is built on. Instrumentation should always be fire-and-forget with a short timeout; see
instrumentation_get_contract for language-specific snippets that already do this correctly.
The ingestion server binds 127.0.0.1 only and has no auth token — acceptable for a local dev
tool, but don't run it anywhere multi-tenant or expose the port.
One MCP server process serves one data directory for its lifetime; to point at a different
project, restart/reconnect the client rather than changing dataDir mid-session.
examples/buggy-node-service/ is a small, intentionally-buggy HTTP server for trying the full
workflow end to end — see its README.
npm install
npm run build # compiles to dist/ and copies the SQL migration
npm run dev # tsx watch, for iterating
npm run typecheck
npm test
npm run inspect # build + launch the MCP inspector against dist/bin.jsStarts a new hypothesis-driven debugging session for a bug. All hypotheses and executions are tracked under a sessionId. Call this first, before creating hypotheses or executions.
Inputs: title (required), description.
Fetches full detail for a session: its hypotheses and execution summaries. Use format=markdown for a human-readable rendering.
Inputs: sessionId (required), format.
Lists debugging sessions, most recently updated first.
Inputs: limit, status.
Closes out a debugging session once the root cause is found and fixed (or the investigation is abandoned). Call knowledge_base_export first if you want a written record of the investigation.
Inputs: sessionId (required), status, resolutionSummary.
Explains how to debug using log-probe-mcp: reconnaissance, forming falsifiable hypotheses, instrumenting code, reproducing, analyzing real runtime data, converging on a root cause, and resolving. Call with no arguments for the full guide, or a specific stage once underway. Read this before starting a debugging session if you haven't used log-probe-mcp before.
Inputs: stage.
Diffs two executions' logs, grouped by normalized (source, level, message) so it tolerates differing data payloads (timestamps, ids). Returns log lines only present in A, only present in B, and lines common to both with their counts. This is the tool for flaky-test-style debugging: run the same thing repeatedly with execution_run, then compare a failing run against a passing one to isolate exactly what diverged.
Inputs: executionIdA (required), executionIdB (required).
Mints a new executionId for a process/request/test run you will trigger yourself (already running externally, or you'll reproduce it manually). Instrumented code must include this executionId in every log event it POSTs to the ingestion server. Requires probe_server_start to have been called first. For processes you want log-probe-mcp to launch and capture directly, use execution_run instead.
Inputs: sessionId (required), label.
Records the outcome of an execution that log-probe-mcp could not observe exiting on its own (i.e. one created via execution_create, not execution_run).
Inputs: executionId (required), notes, outcome.
Fetches the structured logs recorded for a single execution, in chronological order, optionally filtered by hypothesis, level, time range, or a text search over the message.
Inputs: executionId (required), level, limit, since, +4 more.
Lists executions for a debugging session with log-count summaries, most recent first.
Inputs: sessionId (required), limit.
Spawns command as a subprocess with LOG_PROBE_URL/LOG_PROBE_EXECUTION_ID/LOG_PROBE_SESSION_ID auto-injected into its environment, so any instrumentation you've added can POST straight to the ingestion server without you wiring the correlation IDs by hand. Stdout/stderr are also captured line-by-line as logs (stderr as level=error), merged with any HTTP-posted structured logs in execution_get_logs. Waits for the process to exit (or timeoutMs to elapse). Requires probe_server_start to have been called first. Best for scripts, one-off repros, and test runs (e.g. running a flaky test N times); for long-running services, use execution_create instead.
Inputs: command (required), sessionId (required), cwd, env, +3 more.
Records a falsifiable hypothesis about the root cause of a bug within a debugging session. Form several distinct, competing hypotheses rather than one — the point of instrumentation is to gather evidence that can confirm some and refute others.
Inputs: sessionId (required), statement (required), rationale.
Lists hypotheses for a debugging session, oldest first.
Inputs: sessionId (required), status.
Marks a hypothesis confirmed/refuted/inconclusive based on evidence gathered from logs, and/or links it to the execution(s) that provided that evidence. This is the durable record that knowledge_base_export later turns into a written debugging knowledge base.
Inputs: hypothesisId (required), status, evidence, relatedExecutionIds.
Returns everything needed to instrument target code: the live ingestion endpoint (or a placeholder if probe_server_start hasn't been called yet), the LogEvent JSON schema, the env vars execution_run/execution_create inject, and ready-to-paste snippets per language. Use this before inserting any instrumentation so calls match the contract exactly.
Inputs: language.
Writes .log-probe/knowledge/.md summarizing the root cause, confirmed/refuted hypotheses with evidence, and notable executions for a session, and refreshes .log-probe/knowledge/INDEX.md linking every exported session. This is the durable, written record analogous to a hand-maintained debugging notes file — call it once a session has reached a conclusion (or is being abandoned) so the investigation isn't lost.
Inputs: sessionId (required).
Starts the local HTTP log-ingestion server that instrumented code sends structured log events to. Must be called before any code can be instrumented or executions run. Also lazily opens the .log-probe/ SQLite storage for this project on first call.
Inputs: host, port, dataDir.
Reports whether the ingestion server is running, its URL, and basic counters.
Inputs: no named parameters.
Stops the local HTTP log-ingestion server. Stored sessions/hypotheses/logs are unaffected.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
Most tools have clearly distinct purposes across server lifecycle, sessions, executions, hypotheses, and knowledge base. The only minor overlap is between debug_session_get (which includes execution summaries) and execution_list, and execution_create vs execution_run require careful reading to distinguish, but descriptions resolve this.
All tool names follow a consistent snake_case convention with a resource_action pattern (e.g., probe_server_start, debug_session_create, execution_run, hypothesis_update). The convention is uniformly applied across all 19 tools, even if the order is noun-verb rather than the more common verb-noun.
19 tools is on the heavier end of the typical range, but each tool maps to a distinct phase of the debugging workflow: server management, session lifecycle, execution management, hypothesis management, instrumentation contract, guide, and export. The count feels justified by the comprehensive scope.
The toolset covers the full debug lifecycle without obvious gaps: start/stop/status the server, create/list/get/resolve sessions, create/run/end/list/log/compare executions, manage hypotheses, get instrumentation contract, read the guide, and export the knowledge base. No essential operation appears missing.
Agent Replay Debugger MCP — record every agent step + deterministic replay. Step-debugger for
Ingest and search LogsLoom logs from coding agents.
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
