io.github.alanzha2/observe-instrument-mcp

observe-instrument-mcp

An MCP server that automatically instruments Python AI agents with the ioa-observe-sdk — adding OpenTelemetry-based tracing, metrics, and logs with zero manual effort.

Works with any MCP-compatible AI coding assistant: Claude Desktop, Cursor, Windsurf, and others.

What it does

Two tools:

instrument_agent — reads a Python agent file, applies full observe SDK instrumentation, writes it back, and returns a summary of changes. Creates a .bak backup before modifying.

check_instrumentation — audits a file for missing instrumentation without modifying it.

Supported frameworks: LlamaIndex, LangGraph, CrewAI, raw OpenAI SDK.

Installation

pip install observe-instrument-mcp
# or
uv add observe-instrument-mcp

Requires an API key for your chosen LLM provider. Defaults to Claude (ANTHROPIC_API_KEY). See supported providers below.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "observe-instrument": {
      "command": "uvx",
      "args": ["observe-instrument-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "observe-instrument": {
      "command": "uvx",
      "args": ["observe-instrument-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "observe-instrument": {
      "command": "uvx",
      "args": ["observe-instrument-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Examples

Ready-to-use uninstrumented agent files are included in the examples/ folder:

examples/
  single-agent/
    openai-sdk-example.py      # OpenAI SDK customer support agent
    langgraph-example.py       # LangGraph currency converter
    llama-index-example.py     # LlamaIndex math agent
    crewai-example.py          # CrewAI research crew
  multi-agent/
    openai-sdk-multi-agent-example.py   # OpenAI SDK orchestrator pipeline
    langgraph-multi-agent-example.py    # LangGraph supervisor pattern
    llama-index-multi-agent-example.py  # LlamaIndex research + writing pipeline
    crewai-multi-agent-example.py       # CrewAI research + publishing crews

Usage

Once configured, ask your AI assistant:

Instrument my agent with the observe SDK: path/to/my_agent.py

Check what observe SDK instrumentation is missing from path/to/my_agent.py

Environment variables

Variable	Description
LLM_MODEL	Model to use (default: claude-sonnet-4-6). See provider table below.
ANTHROPIC_API_KEY	Required for Anthropic models
OPENAI_API_KEY	Required for OpenAI models
GEMINI_API_KEY	Required for Google Gemini models
GROQ_API_KEY	Required for Groq models

Supported providers

Provider	Key variable	LLM_MODEL example
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-6
OpenAI	OPENAI_API_KEY	gpt-4o
Google Gemini	GEMINI_API_KEY	gemini/gemini-2.0-flash
Groq	GROQ_API_KEY	groq/llama-3.3-70b
Ollama (local, free)	none	ollama/llama3.2

After instrumentation

Install the SDK in your project:

pip install ioa-observe-sdk
# or
uv add ioa-observe-sdk

Start the observability stack (OTel Collector + ClickHouse):

cd path/to/observe/deploy
docker compose up -d

Run your agent:

OPENAI_API_KEY=sk-... OTLP_HTTP_ENDPOINT=http://localhost:4318 python my_agent.py

Query traces:

docker exec -it clickhouse-server clickhouse-client --user admin --password admin

SELECT SpanName, ServiceName, Duration / 1000000. AS ms, Timestamp
FROM otel_traces
ORDER BY Timestamp DESC
LIMIT 20;

Development

git clone https://github.com/alanzha2/observe-instrument-mcp
cd observe-instrument-mcp
pip install -e .

# Test the server locally
mcp dev observe_instrument_mcp/server.py

License

Apache-2.0