mcp-observe

One-line SDK that captures every LLM and MCP tool call and streams it to a real-time dashboard.

Zero runtime dependencies — uses only the Python standard library. Patches are silently skipped when a library isn't installed.

Install

pip install mcp-observe

Get a Server

mcp-observe is self-hosted. Stand up your own server in one command:

git clone https://github.com/Phytonking/mcp-observe.git
cd mcp-observe && cp .env.example .env  # edit secrets
docker compose up -d

See the self-host quickstart. Then create a project in the dashboard at http://localhost:3000 to get an API key.

Quick Start

import mcp_observe
mcp_observe.init(api_key="proj_...")

# Sends to http://localhost:3000/api/v1/events by default.
# Override with endpoint="https://my-server.example.com/api/v1/events"
# or MCP_OBSERVE_ENDPOINT env var.

# All supported SDK calls are now captured automatically.

Supported Providers

All patches are optional. If a library isn't installed, its patch is silently skipped — your app is never affected.

Server-Side Instrumentation

Instrument MCP servers directly to capture tool calls on the server side:

from mcp.server import Server
import mcp_observe

app = Server("my-server")
mcp_observe.instrument_server(app, api_key="proj_...")

Proxy CLI

Wrap any MCP server as a transparent proxy — no code changes needed:

mcp-observe --api-key tap_... -- python my_mcp_server.py

The proxy intercepts all JSON-RPC tools/call messages on stdio, captures them, and forwards everything unchanged.

Sessions

Sessions are detected automatically from conversation fingerprints. You can also set them explicitly:

import mcp_observe

# Context manager (scoped)
with mcp_observe.session("my-workflow") as session_id:
    # All events inside this block share the same session ID
    response = client.messages.create(...)

# Manual start/end
mcp_observe.start_session("my-workflow")
# ... your code ...
mcp_observe.end_session()

Traces

Group related operations across sessions with trace IDs:

import mcp_observe

trace_id = mcp_observe.start_trace()
# All events emitted until end_trace() share this trace_id
response = client.messages.create(...)
mcp_observe.end_trace()

Configuration

init() Parameters

Environment Variables

Debugging

If events aren't appearing in the dashboard:

1. Enable debug logging:

   import logging
   logging.basicConfig(level=logging.DEBUG)
   

   The SDK logs to the mcp_observe logger. You'll see messages for patch failures and send errors.

2. Verify your API key is correct (starts with proj_) and your endpoint URL is reachable.

3. Make sure mcp_observe.init() is called before importing the SDK you want to instrument.

Dashboard

The dashboard ships with the mcp-observe self-host repo. After docker compose up, open http://localhost:3000 to create projects, view events, and manage policies.

Tests

python3 -m unittest discover -s tests

License

MIT