{
  "markdown": "# observe-instrument-mcp\n\n<!-- mcp-name: io.github.alanzha2/observe-instrument-mcp -->\n\nAn MCP server that automatically instruments Python AI agents with the [ioa-observe-sdk](https://github.com/agntcy/observe) — adding OpenTelemetry-based tracing, metrics, and logs with zero manual effort.\n\nWorks with any MCP-compatible AI coding assistant: Claude Desktop, Cursor, Windsurf, and others.\n\n## What it does\n\nTwo tools:\n\n**`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.\n\n**`check_instrumentation`** — audits a file for missing instrumentation without modifying it.\n\nSupported frameworks: LlamaIndex, LangGraph, CrewAI, raw OpenAI SDK.\n\n## Installation\n\n```bash\npip install observe-instrument-mcp\n# or\nuv add observe-instrument-mcp\n```\n\nRequires an API key for your chosen LLM provider. Defaults to Claude (`ANTHROPIC_API_KEY`). See [supported providers](#supported-providers) below.\n\n## Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"observe-instrument\": {\n      \"command\": \"uvx\",\n      \"args\": [\"observe-instrument-mcp\"],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"sk-ant-...\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"observe-instrument\": {\n      \"command\": \"uvx\",\n      \"args\": [\"observe-instrument-mcp\"],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"sk-ant-...\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"observe-instrument\": {\n      \"command\": \"uvx\",\n      \"args\": [\"observe-instrument-mcp\"],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"sk-ant-...\"\n      }\n    }\n  }\n}\n```\n\n## Examples\n\nReady-to-use uninstrumented agent files are included in the `examples/` folder:\n\n```\nexamples/\n  single-agent/\n    openai-sdk-example.py      # OpenAI SDK customer support agent\n    langgraph-example.py       # LangGraph currency converter\n    llama-index-example.py     # LlamaIndex math agent\n    crewai-example.py          # CrewAI research crew\n  multi-agent/\n    openai-sdk-multi-agent-example.py   # OpenAI SDK orchestrator pipeline\n    langgraph-multi-agent-example.py    # LangGraph supervisor pattern\n    llama-index-multi-agent-example.py  # LlamaIndex research + writing pipeline\n    crewai-multi-agent-example.py       # CrewAI research + publishing crews\n```\n\n## Usage\n\nOnce configured, ask your AI assistant:\n\n```\nInstrument my agent with the observe SDK: path/to/my_agent.py\n```\n\n```\nCheck what observe SDK instrumentation is missing from path/to/my_agent.py\n```\n\n## Environment variables\n\n| Variable | Description |\n|---|---|\n| `LLM_MODEL` | Model to use (default: `claude-sonnet-4-6`). See provider table below. |\n| `ANTHROPIC_API_KEY` | Required for Anthropic models |\n| `OPENAI_API_KEY` | Required for OpenAI models |\n| `GEMINI_API_KEY` | Required for Google Gemini models |\n| `GROQ_API_KEY` | Required for Groq models |\n\n### Supported providers\n\n| Provider | Key variable | `LLM_MODEL` example |\n|---|---|---|\n| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |\n| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |\n| Google Gemini | `GEMINI_API_KEY` | `gemini/gemini-2.0-flash` |\n| Groq | `GROQ_API_KEY` | `groq/llama-3.3-70b` |\n| Ollama (local, free) | none | `ollama/llama3.2` |\n\n## After instrumentation\n\nInstall the SDK in your project:\n\n```bash\npip install ioa-observe-sdk\n# or\nuv add ioa-observe-sdk\n```\n\nStart the observability stack (OTel Collector + ClickHouse):\n\n```bash\ncd path/to/observe/deploy\ndocker compose up -d\n```\n\nRun your agent:\n\n```bash\nOPENAI_API_KEY=sk-... OTLP_HTTP_ENDPOINT=http://localhost:4318 python my_agent.py\n```\n\nQuery traces:\n\n```bash\ndocker exec -it clickhouse-server clickhouse-client --user admin --password admin\n```\n\n```sql\nSELECT SpanName, ServiceName, Duration / 1000000. AS ms, Timestamp\nFROM otel_traces\nORDER BY Timestamp DESC\nLIMIT 20;\n```\n\n## Development\n\n```bash\ngit clone https://github.com/alanzha2/observe-instrument-mcp\ncd observe-instrument-mcp\npip install -e .\n\n# Test the server locally\nmcp dev observe_instrument_mcp/server.py\n```\n\n## License\n\nApache-2.0\n",
  "bytes": 4299,
  "sha": "ed1610784dd2a9aba1b63623920540cf1c65da560b2a3a14f5ad92eaf0551f99",
  "repo_slug": "alanzha2/observe-instrument-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alanzha2_observe_instrument_mc_b1205639/readme"
}