Observe Instrument Mcp

io.github.alanzha2Published by GitHub account alanzha2v0.1.2Updated Oct 24, 2026

Add OpenTelemetry tracing to Python AI agents. Supports LangGraph, LlamaIndex, CrewAI, OpenAI SDK.

VerifiedSTDIODesktop onlyDeveloper ToolsSecurity & MonitoringAI & ML

Overview

AI-generated overview

An MCP server that adds OpenTelemetry tracing, metrics, and logs to Python AI agent code by rewriting the agent file.

What you can do
It exposes two tools: instrument_agent reads a Python agent file, applies full ioa-observe-sdk instrumentation, writes the file back, and returns a summary of changes; check_instrumentation audits a file for missing instrumentation without modifying it. It supports LlamaIndex, LangGraph, CrewAI, and the raw OpenAI SDK. A .bak backup is created before any modification.
When to use it
Use it when you have a Python AI agent built on one of the supported frameworks and want OpenTelemetry-based tracing, metrics, and logs added with minimal manual editing. It is also useful for auditing existing agent files to see what instrumentation is missing.
Requirements
Runs locally as a stdio process, installed from PyPI (pip install observe-instrument-mcp or uv add observe-instrument-mcp). Requires an API key for the chosen LLM provider: ANTHROPIC_API_KEY (default), OPENAI_API_KEY, GEMINI_API_KEY, or GROQ_API_KEY; Ollama needs no key. LLM_MODEL selects the model. After instrumentation, the project needs ioa-observe-sdk and an OTel Collector plus ClickHouse stack.
Before you install
The instrument_agent tool writes to and rewrites your Python agent file, though it creates a .bak backup first. It requires an LLM provider API key such as ANTHROPIC_API_KEY or OPENAI_API_KEY, which is passed in the MCP server configuration. Instrumented agents send telemetry to the configured OTLP endpoint, so review where trace data goes.

Installation

In SourceWeft

  1. Open Observe Instrument Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
pip install observe-instrument-mcp# oruv 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:

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:

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

Windsurf

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

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

VariableDescription
LLM_MODELModel to use (default: claude-sonnet-4-6). See provider table below.
ANTHROPIC_API_KEYRequired for Anthropic models
OPENAI_API_KEYRequired for OpenAI models
GEMINI_API_KEYRequired for Google Gemini models
GROQ_API_KEYRequired for Groq models

Supported providers

ProviderKey variableLLM_MODEL example
AnthropicANTHROPIC_API_KEYclaude-sonnet-4-6
OpenAIOPENAI_API_KEYgpt-4o
Google GeminiGEMINI_API_KEYgemini/gemini-2.0-flash
GroqGROQ_API_KEYgroq/llama-3.3-70b
Ollama (local, free)noneollama/llama3.2

After instrumentation

Install the SDK in your project:

bash
pip install ioa-observe-sdk# oruv add ioa-observe-sdk

Start the observability stack (OTel Collector + ClickHouse):

bash
cd path/to/observe/deploydocker compose up -d

Run your agent:

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

Query traces:

bash
docker exec -it clickhouse-server clickhouse-client --user admin --password admin
sql
SELECT SpanName, ServiceName, Duration / 1000000. AS ms, TimestampFROM otel_tracesORDER BY Timestamp DESCLIMIT 20;

Development

bash
git clone https://github.com/alanzha2/observe-instrument-mcpcd observe-instrument-mcppip install -e .
# Test the server locallymcp dev observe_instrument_mcp/server.py

License

Apache-2.0

Source: README.md at commit 4c7ab11

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.