Debugging AI Coding Agent Sessions and Failed MCP Calls Locally

When you have multiple AI coding assistant sessions running at once, the most immediate debugging problem is: which session is stuck, and what was its last action? Starting from raw logs means manually matching session IDs, project paths, and tracing tool call records one by one. This process is tedious and error-prone.

Agent Observatory is a local terminal and browser dashboard tool designed specifically for inspecting Codex and Claude Code session records. It also receives OpenTelemetry data from custom instrumented Agents. Its views are organized around sessions, activity, recorded MCP calls, trace chains, and host processes, providing a more intuitive path for troubleshooting.

Quick Start Experience

Environment Setup and Launch

Using this tool requires Python 3.11+ and the uv package manager. On a machine that already has Codex or Claude Code session records, run the following command to start:

uvx --from agent-observatory-cli agent-observatory

The terminal interface opens first. Press b to switch to the local browser dashboard. The receiver listens on 127.0.0.1:14318, and captured data is stored in a local SQLite file. This local-first design means session data never leaves your machine.

What are uv and uvx?

uv is a Python package and project management tool written in Rust, positioned as an all-in-one replacement for tools like pip, pip-tools, and virtualenv, known for its speed and reliable dependency resolution. uvx is a command-line tool installed alongside uv that runs the executable provided by a Python package directly in an isolated temporary environment, without needing to manually create a virtual environment or install globally.

In the article, uvx --from agent-observatory-cli agent-observatory means: extract the command named agent-observatory from the agent-observatory-cli package and run it. This delivers a "zero-install trial" experience—no need to pollute your existing environment, and it's easy to quickly upgrade or discard. This is also why the article requires Python 3.11+: the tool relies on newer language features that older interpreters cannot run.

Session View: Locating Stuck Tasks

Open the Agents view and select a session. The list rows show the runtime type, session ID, project name, observed status, last update time, and the latest task reported by the source. The detail view further supplements model information, usage, and recent work records.

A key design detail: sessions are only marked as waiting when the source explicitly reports a waiting state. The dashboard does not infer undocumented causes. This prevents the debugging tool itself from producing misleading information.

MCP Call Inspection: Locating Failed Tool Calls

Open the MCP Calls view to see a list of servers with call records within the selected scope. Inspecting a single call lets you read its recorded parameters, return values, duration, and associated trace chain. Following the trace chain allows you to view surrounding operations and error evidence.

Note that the MCP view does not list all servers configured on the machine—it only shows those with actual call records. For troubleshooting issues like "why did a particular MCP call fail," this is exactly the view you need.

Introduction to the MCP Protocol

MCP (Model Context Protocol) is an open protocol proposed by Anthropic for letting AI assistants connect to external tools, data sources, and services in a standardized way. An MCP server typically exposes several "tools" that AI can call to perform operations like reading and writing files, querying databases, and accessing APIs.

Because MCP calls are the critical link between Agent and the outside world, they are also the most error-prone area: invalid parameters, server timeouts, insufficient permissions, or abnormal return value formats can all cause tasks to stall. That's why this tool lists MCP calls as its own view and links them to trace chains, so developers can directly see "which call, what parameters were passed, what was returned, how long it took"—without having to piece together context from scattered raw logs.

How to Connect Non-Built-in Runtimes

If your Agent is not a supported local runtime, you can send OTLP/HTTP telemetry data, or use the project's provided Python and JavaScript clients for instrumentation. Visible details depend on the data fields the Agent actually emits.

What are OpenTelemetry and OTLP/HTTP?

OpenTelemetry (abbreviated OTel) is a vendor-neutral open-source observability standard that defines how to generate, collect, and export three types of telemetry data: Traces, Metrics, and Logs. OTLP (OpenTelemetry Protocol) is its transport protocol, and OTLP/HTTP sends data via standard HTTP requests, typically on port 4318 by default.

In the context of this tool, the significance of OTLP/HTTP is that any Agent that can export according to this protocol—regardless of what language or framework it's written in—can push sessions, tool calls, and trace information to the local receiver (127.0.0.1:14318), without relying on Codex or Claude Code's built-in record format. This explains why the article emphasizes that "visible details depend on the data fields the Agent actually emits": OTel only transmits what the sender actively reports, and the receiver cannot conjure up fields that were never reported.

First-Run Checklist

If the dashboard appears empty, try starting a Codex or Claude Code task first and confirm the tool can read its local session records. For other runtimes, you need to configure telemetry export first. The project's "First Minute Guide" documentation records each view and keyboard shortcut binding.

The demo image above uses synthetic records. Actual captured content may include prompts, tool parameters, and project details. Before recording or sharing real sessions, be sure to review the project's privacy and capture boundary documentation.

Applicable Scenarios and Capability Boundaries

This workflow is particularly useful when a task appears stalled or a tool returns abnormal results: identify the session, check the last recorded action, then drill down along the call chain.

But it also clearly demonstrates the boundaries of evidence. If the source doesn't record the waiting reason or MCP calls, the dashboard cannot reconstruct that information. This honest capability statement actually makes the tool more trustworthy in real debugging—you won't be misled by false inferences.

For developers using AI coding assistants, this type of local observability tool fills a real gap: between logs and debuggers, it provides a layer of visual inspection capability for Agent sessions.

One-line Summary

Agent Observatory: a local-first visualization tool for troubleshooting Codex and Claude Code sessions and MCP calls.

Paragraph Summary

Agent Observatory is a locally running terminal and browser dashboard tool designed specifically for inspecting Codex and Claude Code session records, and can also receive data from custom instrumented Agents via OpenTelemetry. It organizes views around sessions, activity, MCP calls, trace chains, and host processes, helping developers quickly identify "which session is stuck and what it last did." The tool uses a local-first design, storing data in a local SQLite database that never leaves the machine. Its notable feature is an honest declaration of capability boundaries: sessions are only marked as waiting when the source explicitly reports a waiting state, and the MCP view only shows servers with actual call records, making no inferences. Users can launch it with a single uvx command, switch between terminal and browser interfaces with the b key, and the receiver listens on local port 14318.