{"id":26362288,"url":"https://github.com/comet-ml/opik-mcp","last_synced_at":"2026-08-27T19:05:31.180Z","repository":{"id":281887266,"uuid":"946763772","full_name":"comet-ml/opik-mcp","owner":"comet-ml","description":"Model Context Protocol (MCP) server for Opik, the open-source LLM observability and evaluation platform, built by Comet. Read traces, log scores, and manage prompts from Claude Code, Cursor, or VS Code.","archived":false,"fork":false,"pushed_at":"2026-08-21T15:24:22.000Z","size":2451,"stargazers_count":218,"open_issues_count":33,"forks_count":36,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-08-22T05:33:41.016Z","etag":null,"topics":["claude-code","generative-ai","llm-observability","mcp","mcp-server","model-context-protocol","opik","python"],"latest_commit_sha":null,"homepage":"https://www.comet.com/site/products/opik/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/comet-ml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"claude":null,"gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2025-03-11T16:31:03.000Z","updated_at":"2026-08-21T15:25:50.000Z","dependencies_parsed_at":"2026-08-14T17:24:14.946Z","dependency_job_id":null,"html_url":"https://github.com/comet-ml/opik-mcp","commit_stats":null,"previous_names":["comet-ml/opik-mcp"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/comet-ml/opik-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/comet-ml","download_url":"https://codeload.github.com/comet-ml/opik-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36815513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-06T04:43:03.162Z","status":"online","status_checked_at":"2026-08-22T02:00:06.114Z","response_time":51,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","generative-ai","llm-observability","mcp","mcp-server","model-context-protocol","opik","python"],"created_at":"2025-03-16T18:01:32.163Z","updated_at":"2026-08-27T19:05:31.166Z","avatar_url":"https://github.com/comet-ml.png","language":"Python","funding_links":[],"categories":["Monitoring \u0026 Observability","Monitoring","MCP 服务器精选列表","💻 \u003ca name=\"development-tools\"\u003e\u003c/a\u003eDevelopment Tools","📚 Projects (1974 total)","Production-Ready Servers","پیاده‌سازی‌های سرور","📦 Other","Legend","官方 MCP 服务器列表","MCP Servers","Community Servers","Contributing","カテゴリ","Cloud Services","📊 Monitoring \u0026 Observability","Data \u0026 Analytics","Python","💻 Developer Tools (164 servers)","LLMOps","Developer Tools","Server Implementations","Table of Contents","LLM and Agent Observability"],"sub_categories":["Video","📊 数据分析、处理与可视化","MCP Servers","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eابزارهای توسعه‌دهنده","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eDeveloper Tools","💻 Developer Tools","How to Submit","🛠️ \u003ca name=\"developer-tools\"\u003e\u003c/a\u003e開発ツール","LLM Observability \u0026 Tracing","Developer Tools"],"readme":"# Opik MCP Server\n\n**The official Model Context Protocol (MCP) server for [Opik](https://github.com/comet-ml/opik), the open-source LLM observability and evaluation platform, built by [Comet](https://www.comet.com).**\nPlug your AI host (Claude Code, Cursor, VS Code Copilot, MCP Inspector) directly\ninto your Opik workspace: read traces, log scores, save prompt versions, and ask\n[Ollie](#ask_ollie), Opik's in-product AI assistant, investigative questions, all\nfrom the chat.\n\nBuilt for LLM engineers who already run Opik and want to drive it from the same\nAI assistant they code with.\n\n\u003e **Migrating from the old `npx opik-mcp`?** The TypeScript server is deprecated\n\u003e and sunsets on **2026-11-15**. Swap `npx -y opik-mcp` for **`uvx opik-mcp@latest`**\n\u003e in your MCP client config. Full guide: [`legacy/typescript/MIGRATION.md`](./legacy/typescript/MIGRATION.md).\n\n```\nYou:    \"Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?\"\nClaude: → ask_ollie → reads experiment + traces → \"Three traces failed because…\"\n\nYou:    \"Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'.\"\nClaude: → write(score.create) → done\n```\n\n---\n\n## Install\n\n`opik-mcp` is a Python package (requires Python 3.13+). The recommended way to\nrun it is `uvx`, which fetches and runs the latest published version on demand —\nno global install, no virtualenv juggling.\n\nInstall [`uv`](https://docs.astral.sh/uv/) once:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux\n# or: brew install uv\n```\n\nYou'll need two things from your Opik workspace:\n\n- **`OPIK_API_KEY`** — get it from [`comet.com/api/my/settings/`](https://www.comet.com/api/my/settings/).\n- **`OPIK_WORKSPACE`** — your workspace name (lowercase, as it appears in the URL). E.g. `https://www.comet.com/acme-ai/...` → `OPIK_WORKSPACE=acme-ai`. `COMET_WORKSPACE` is accepted as a deprecated alias.\n\n\u003e **Cloud, with an API key: set it unless your account default is the one you\n\u003e want.** Left out, the server sends `default`, which Comet resolves to your\n\u003e account's default workspace. That works, but if you actually work in a named\n\u003e workspace you will be pointed at a different one with nothing to tell you —\n\u003e your reads come back from the wrong place rather than failing.\n\u003e\n\u003e **Cloud, over OAuth: leave it unset.** The workspace comes from the token you\n\u003e authorized, and the server ignores this setting entirely.\n\u003e\n\u003e **Local / open source: leave it unset.** Open source Opik has a single\n\u003e workspace named `default` and no way to create others, which is exactly what\n\u003e the fallback gives you.\n\u003e\n\u003e **Self-hosted Comet: set it.** Unlike open source, these deployments have real\n\u003e named workspaces, and the same silent-wrong-workspace risk applies.\n\u003e\n\u003e Whichever applies, make sure the value is actually substituted. Snippets in\n\u003e the wild ship placeholders like `\u003cyour-workspace\u003e` or `${input:OPIK_WORKSPACE}`;\n\u003e pasted as-is, those are not workspace names. The server now refuses them\n\u003e outright rather than letting the backend answer with an auth error that\n\u003e explains nothing.\n\n### Claude Code\n\nAdd the server with one command:\n\n```bash\nclaude mcp add --transport stdio opik-mcp \\\n  --env OPIK_API_KEY=\u003cyour-key\u003e \\\n  --env OPIK_WORKSPACE=\u003cyour-workspace\u003e \\\n  -- uvx opik-mcp\n```\n\nOr edit `~/.claude.json` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"opik-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"opik-mcp\"],\n      \"env\": {\n        \"OPIK_API_KEY\": \"\u003cyour-key\u003e\",\n        \"OPIK_WORKSPACE\": \"\u003cyour-workspace\u003e\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Code. Verify with `/mcp` — `opik-mcp` should appear as connected.\nThen, in the chat, ask: **\"list my Opik projects\"** — Claude will call the `list`\ntool and you'll see your workspace's projects.\n\n### Cursor\n\nEdit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project), or open\n**Cmd+Shift+J → Features → Model Context Protocol**:\n\n```json\n{\n  \"mcpServers\": {\n    \"opik-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"opik-mcp\"],\n      \"env\": {\n        \"OPIK_API_KEY\": \"\u003cyour-key\u003e\",\n        \"OPIK_WORKSPACE\": \"\u003cyour-workspace\u003e\"\n      }\n    }\n  }\n}\n```\n\nReload Cursor; the green dot next to `opik-mcp` in the MCP panel confirms the\nconnection. Ask in chat: **\"list my Opik projects\"**.\n\n\u003e **Cursor 60s timeout.** Cursor enforces a hard tool-call timeout that doesn't\n\u003e reset on progress notifications. Long `ask_ollie` turns will fail on Cursor.\n\u003e See [Known host limits](#known-host-limits).\n\n### VS Code Copilot\n\n`.vscode/mcp.json` in your workspace (or User Settings JSON):\n\n```json\n{\n  \"servers\": {\n    \"opik-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"opik-mcp\"],\n      \"env\": {\n        \"OPIK_API_KEY\": \"\u003cyour-key\u003e\",\n        \"OPIK_WORKSPACE\": \"\u003cyour-workspace\u003e\"\n      }\n    }\n  }\n}\n```\n\nReload the window; the Copilot Chat **MCP** indicator shows `opik-mcp` once\nthe server is reachable. Ask in chat: **\"list my Opik projects\"**.\n\n### MCP Inspector (manual testing)\n\n```bash\nOPIK_API_KEY=\u003cyour-key\u003e OPIK_WORKSPACE=\u003cyour-workspace\u003e \\\n  npx @modelcontextprotocol/inspector uvx opik-mcp\n```\n\n### Self-hosted Opik\n\nAdd `COMET_URL_OVERRIDE` (and `OPIK_URL` if Opik lives at a non-default path) to\nthe same `env` block in your host config:\n\n```json\n{\n  \"mcpServers\": {\n    \"opik-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"opik-mcp\"],\n      \"env\": {\n        \"OPIK_API_KEY\": \"\u003cyour-key\u003e\",\n        \"OPIK_WORKSPACE\": \"\u003cyour-workspace\u003e\",\n        \"COMET_URL_OVERRIDE\": \"https://opik.your-company.com\",\n        \"OPIK_MCP_ANALYTICS_SOURCE\": \"\"\n      }\n    }\n  }\n}\n```\n\nOmit `OPIK_WORKSPACE` on an open-source deployment, where `default` is the only\nworkspace; keep it on a self-hosted Comet, which has real named ones.\n\n`ask_ollie` and `run_experiment` are available on Comet Cloud only — on\nself-hosted those calls will fail at dispatch, so use `read` / `list` / `write`\ndirectly. Setting `OPIK_MCP_ANALYTICS_SOURCE=\"\"` opts your install out of the\ncloud-Comet source label on telemetry events.\n\n---\n\n## Tools\n\n`opik-mcp` exposes a small, outcome-oriented surface — six tools that cover\nthe full lifecycle (read → annotate → curate → author → iterate).\n\n| Tool | Purpose |\n|---|---|\n| [`read`](#read) | Universal read by id / name / `opik://` URI |\n| [`list`](#list) | Universal list with optional name filter + pagination |\n| [`ask_ollie`](#ask_ollie) | Investigate / synthesize via the Opik in-product assistant |\n| [`write`](#write) | Universal write — log traces/spans, score, comment, save prompts, manage test suites \u0026 experiments |\n| [`schema`](#schema) | Introspect write-operation schemas (used by the LLM to construct valid payloads) |\n| [`run_experiment`](#run_experiment) | Run an evaluation experiment end-to-end via Ollie |\n\n### `read`\n\nOne tool for any \"show me X\" question. Takes an `entity_type` plus an `id`\n(UUID or, for nameable types, a name) or a full `opik://` URI. Composite reads\n(`trace`, `prompt`) inline their children so a single call returns the full\npicture.\n\n**Supported entities:** `project`, `trace`, `span`, `test_suite`, `experiment`,\n`prompt`. Name-based lookup is available for `project`, `experiment`, `prompt`,\n`test_suite` (slower — two API calls — and may return multiple matches).\n\n```python\nread(entity_type=\"trace\", id=\"7f2e3c8a-…\")\nread(entity_type=\"project\", id=\"demo\")          # name lookup\nread(entity_type=\"trace\", id=\"opik://traces/7f2e3c8a-…\")\n```\n\n### `list`\n\nBrowse a collection with optional name filter and pagination. Project-scoped\ntypes (`trace`, `test_suite_item`, `prompt_version`) require their parent UUID.\n\n```python\nlist(entity_type=\"experiment\", page=1, size=25)\nlist(entity_type=\"experiment\", name=\"rerank\")          # name substring filter\nlist(entity_type=\"trace\", project_id=\"\u003cproject-uuid\u003e\") # traces of one project\n```\n\n### `ask_ollie`\n\nFor investigative questions, cross-entity synthesis, or anything that needs\nOpik domain expertise. Ollie has direct read access to your workspace and can\nexecute writes (scores, comments, test-suite items, prompt versions) mid-stream\nwhen asked.\n\n```python\nask_ollie(query=\"Why are spans in project 'demo' slower this week than last?\")\nask_ollie(query=\"Compare experiments A and B on factuality. Score the bottom 5 traces of A 0.2 with reason.\")\n```\n\nReturns the assistant's final text plus a `thread_id`. Pass it back on\nfollow-ups to preserve context — Ollie has no memory across threads.\n\n**YOLO mode (default).** Writes Ollie performs mid-stream execute without a\nper-action confirmation. Each auto-approval is logged as a JSON audit row on\nthe `opik_mcp.audit` Python logger. To require confirmation instead, set\n`OPIK_MCP_AUTO_APPROVE=disabled` — Ollie's confirm requests then surface as\ntyped errors you can manually re-issue.\n\n\u003e Available on Comet Cloud only.\n\n### `write`\n\nUniversal write dispatcher. Pass `operation` + `data` and the dispatcher\nvalidates the payload, applies the right REST verb, and returns the\nbackend response.\n\n**Operations:**\n\n| Operation | What it does |\n|---|---|\n| `trace.create` | Log a single trace (or a batch). Parent for spans / scores / comments. |\n| `trace.update` | Finalize or amend an existing trace. |\n| `span.create` | Log a span on an existing trace (or a batch). |\n| `score.create` | Attach a numeric feedback score to a trace, span, or thread. |\n| `comment.create` | Attach a free-text comment to a trace, span, or thread. |\n| `prompt_version.save` | Save a new prompt version (creates the prompt by name if missing). |\n| `test_suite.create` | Create an evaluation test suite. |\n| `test_suite_item.upsert` | Upsert items into a test suite (always the envelope shape). |\n| `experiment.create` | Create an experiment scoped to a test suite. |\n| `experiment_item.create` | Attach trace + dataset_item rows to an experiment. |\n\n```python\nwrite(operation=\"score.create\", data={\n  \"target\": \"trace\",\n  \"target_id\": \"7f2e3c8a-…\",\n  \"name\": \"helpfulness\",\n  \"value\": 0.9,\n  \"reason\": \"great recovery\"\n})\n```\n\n### `schema`\n\nInspect the exact JSON shape and required fields of any write operation before\nyou call it — useful when you're not sure what `data` should look like. Returns\nthe schema, OAuth scope, and one validated example. Pure lookup, no backend\ncall.\n\n```python\nschema(operation=\"score.create\")\nschema(operation=\"prompt_version.save\")\n```\n\n### `run_experiment`\n\nRun an evaluation experiment end-to-end via Ollie. Takes a single\n`experiment_config` dict that mirrors Opik's experiment shape (prompt, test\nsuite, scorers); Ollie executes the run and writes results back as an Opik\nexperiment.\n\n```python\nrun_experiment(experiment_config={\n  \"test_suite_name\": \"qa-eval-v2\",\n  \"prompt_name\": \"welcome-msg\",\n  # … see `schema(operation=\"experiment.create\")` for the full shape\n})\n```\n\n\u003e Available on Comet Cloud only.\n\n---\n\n## Configuration\n\nEvery setting is an environment variable. Required ones in **bold**.\n\n### Identity / endpoint\n\n| Variable | Default | Notes |\n|---|---|---|\n| **`OPIK_API_KEY`** | — | Required for `ask_ollie` and any authenticated read/write. |\n| `OPIK_WORKSPACE` | _unset_ | Workspace name. On cloud with an API key, unset sends `default`, which resolves to your account's **default** workspace — set it explicitly if you work in a different one, or reads come from the wrong workspace silently. Leave unset over OAuth (the token carries it) and on local/OSS (`default` is the only workspace there). |\n| `COMET_WORKSPACE` | — | Deprecated alias for `OPIK_WORKSPACE` (backward compat). `OPIK_WORKSPACE` wins if both are set. |\n| `COMET_WORKSPACE_ID` | _unset_ | Optional workspace UUID. Stamped into analytics events when set, and takes precedence over the resolved one. Rarely needed — OAuth installs get the UUID from the token automatically. |\n| `COMET_URL_OVERRIDE` | `https://www.comet.com` | Set to your self-hosted Comet host, or `https://dev.comet.com` for staging. |\n| `OPIK_URL` | derived from `COMET_URL_OVERRIDE` + `/opik/api` | Override only if Opik lives on a different host/path than the Comet UI. |\n| `OPIK_DEFAULT_PROJECT_NAME` | _unset_ | When set, the per-session `instructions` blob tells the LLM to pass this as `project_name` on every tool call unless the user names a different project. |\n\n### Server / transport\n\n| Variable | Default | Notes |\n|---|---|---|\n| `OPIK_MCP_TRANSPORT` | `stdio` | `stdio` for host-launched, `streamable-http` to listen on a port. |\n| `OPIK_MCP_HOST` | `127.0.0.1` | uvicorn bind host (`streamable-http` only). |\n| `OPIK_MCP_PORT` | `8080` | uvicorn bind port (`streamable-http` only). |\n| `OPIK_MCP_RELOAD` | `false` | `true` to enable uvicorn `--reload` (dev only). |\n| `OPIK_MCP_AS_URL` | _unset_ | OAuth Authorization Server URL, advertised in `/.well-known/oauth-protected-resource` (RFC 9728) and used as the proxy target for AS-discovery probes. Required for MCP hosts to bootstrap the OAuth dance over HTTP. |\n| `OPIK_MCP_RESOURCE_URI` | _unset_ | Canonical public URI of this server, advertised as `resource` in the protected-resource metadata and used to derive the `WWW-Authenticate` hint. |\n| `OPIK_MCP_LOG_LEVEL` | `INFO` | stderr logger threshold. |\n\n#### Choosing a transport\n\nopik-mcp performs **no local credential validation** on HTTP transport: any\nwell-formed `Authorization: Bearer …` (an Opik API key or an `opik_mcp_at_…`\nOAuth access token) is forwarded verbatim to opik-backend, which is the\nsingle point of auth enforcement. Pick the transport by deployment shape:\n\n| Scenario | Transport |\n|---|---|\n| MCP client and Opik on the same machine (local OSS install) | **stdio** (recommended — simplest, no port, no OAuth setup) |\n| Local MCP client → remote Opik (Comet cloud / self-hosted) | stdio with `OPIK_API_KEY`, or HTTP with OAuth (`OPIK_MCP_AS_URL` pointing at the backend) |\n| Hosted opik-mcp behind the same edge as opik-backend | **HTTP** — bearers are validated by the backend per request |\n\nNote for local OSS installs: the OSS backend does not authenticate requests,\nso an HTTP opik-mcp in front of it is as open as the OSS REST API itself.\nKeep the default `127.0.0.1` bind (and prefer stdio) on shared networks.\n\n### Ollie / long calls\n\n| Variable | Default | Notes |\n|---|---|---|\n| `OPIK_MCP_AUTO_APPROVE` | `enabled` | `disabled` to require a per-action approval before Ollie's mid-stream writes proceed. On hosts that advertise the MCP `elicitation` capability the user sees a yes/no prompt; on dumber hosts the request surfaces as a typed error you can manually re-issue. |\n| `OPIK_MCP_ELICIT_TIMEOUT_SECONDS` | `60` | How long Ollie's mid-stream confirmation prompt may wait for the user before being treated as a cancel. `0` disables the bound (debug only). |\n| `OPIK_MCP_POD_READY_TIMEOUT_S` | `120` | Ollie pod cold-start poll cap. |\n| `OPIK_MCP_POD_READY_INTERVAL_S` | `2` | Cold-start poll interval. |\n| `OPIK_MCP_HEARTBEAT_INTERVAL_S` | `15.0` | Watchdog cadence — emits a `notifications/progress` tick when the pod is silent, keeping host timeouts at bay. |\n| `OPIK_MCP_STREAM_IDLE_TIMEOUT_S` | `300.0` | Hard ceiling on pod silence before `ask_ollie` aborts. `0` disables (debug only). |\n\n### Telemetry\n\nAnonymous usage events (event type + timing only — no query content). A SHA-256\ndigest of your API key is included so support can find your account; the raw\nkey never leaves the process. **Opt out:** `OPIK_MCP_ANALYTICS_ENABLED=false`.\n\n| Variable | Default | Notes |\n|---|---|---|\n| `OPIK_MCP_ANALYTICS_ENABLED` | `true` | Set to `false` to disable all telemetry. |\n| `OPIK_MCP_ANALYTICS_URL` | `https://stats.comet.com/notify/event/` | Override for staging. |\n| `OPIK_MCP_ANALYTICS_ENVIRONMENT` | `prod` | Tag on every event (`prod` / `staging` / `dev`). |\n| `OPIK_MCP_ANALYTICS_SOURCE` | `comet.com` | Receiver uses this to mark `on_prem=False`. On-prem installs should override to `\"\"` or their own domain. |\n| `OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S` | `5.0` | HTTP connect timeout. |\n| `OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S` | `10.0` | HTTP total request timeout. |\n\n---\n\n## Known host limits\n\nThe MCP spec lets hosts reset their tool-call timeout on\n`notifications/progress` — `opik-mcp` emits one per Ollie SSE event plus a\n15-second watchdog heartbeat. Reality is uneven:\n\n- **Claude Code** — no documented tool-call timeout; heartbeat keeps the call\n  alive until `message_end`. Recommended.\n- **Cursor** — hard 60s timeout that does **not** reset on progress\n  ([upstream bug](https://forum.cursor.com/t/mcp-tool-timeout/74465)).\n  Long Ollie turns will fail. Keep `ask_ollie` queries focused.\n- **MCP Inspector** — `MAX_TOTAL_TIMEOUT` bounds total duration (default 60s).\n  Raise it in the Inspector UI for long operations.\n\nIf a call gets stuck, set `OPIK_MCP_LOG_LEVEL=DEBUG` — heartbeat failures\n(usually host disconnects) are logged on `opik_mcp.ask_ollie` at debug level.\n\n---\n\n## Troubleshooting\n\n**`OPIK_API_KEY is required to use ask_ollie`** — the var isn't reaching the\nserver process. In Claude Code / Cursor / VS Code, env vars only apply when\ninside the `env` block of the MCP server config, not your shell. Restart the\nhost after editing.\n\n**`ask_ollie` returns \"pod not ready\" after 2 minutes** — the Ollie pod\ncold-start exceeded `OPIK_MCP_POD_READY_TIMEOUT_S`. Retry — the second call\nusually hits a warm pod.\n\n**`ask_ollie` / `run_experiment` fails with a dispatch error on self-hosted\nOpik** — those tools are available on Comet Cloud only. Use `read` / `list` /\n`write` directly on self-hosted.\n\n**Cursor call times out at 60s** — Cursor's known bug, not `opik-mcp`. Either\nshorten the Ollie query, or run the same operation on Claude Code which has no\nhard cap.\n\n---\n\n## Development\n\n```bash\ngit clone git@github.com:comet-ml/opik-mcp.git\ncd opik-mcp\nmake install        # uv sync --extra dev\nmake check          # lint + typecheck + test\nmake run-dev        # uvicorn with --reload + DEBUG logs\nmake inspect        # MCP Inspector against the running server\n```\n\nCommon targets:\n\n| Target | What it does |\n|---|---|\n| `make install` | `uv sync --extra dev` |\n| `make run` | Run the MCP server (stdio by default). |\n| `make run-dev` | Run with DEBUG logging + uvicorn `--reload`. |\n| `make dev` | Run via `mcp dev` (Inspector dev-mode wrapper). |\n| `make inspect` | Launch MCP Inspector against a running server. |\n| `make test` | `uv run pytest -q`. |\n| `make test-live` | Live end-to-end against `dev.comet.com` (set `OPIK_API_KEY` + `OPIK_WORKSPACE`). |\n| `make lint` | `ruff check` + format check. |\n| `make format` | `ruff format` + `ruff check --fix`. |\n| `make typecheck` | `mypy`. |\n| `make check` | `lint + typecheck + test`. |\n\nRepo layout:\n\n```\nopik-mcp/\n├── src/opik_mcp/        ← server, tools, ask_ollie, analytics\n├── tests/               ← pytest suites\n├── scripts/             ← live-BE smoke + MCP-session smoke\n├── legacy/typescript/   ← deprecated v2 TS server\n├── pyproject.toml\n└── Makefile\n```\n\n---\n\n## Get help\n\n- [Open an issue](https://github.com/comet-ml/opik-mcp/issues) for bugs and feature requests\n- [Opik docs](https://www.comet.com/docs/opik/) for SDK / backend documentation\n- [Comet community Slack](https://chat.comet.com/) for questions\n\n---\n\n\u003e **Upgrading from v2?** The legacy TypeScript server still ships on npm as\n\u003e `opik-mcp@^2` (`npx -y opik-mcp`); source is preserved under\n\u003e [`legacy/typescript/`](./legacy/typescript/). See\n\u003e [`legacy/typescript/DEPRECATED.md`](./legacy/typescript/DEPRECATED.md) for\n\u003e the support policy.\n\n---\n\n## License\n\nApache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fopik-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomet-ml%2Fopik-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fopik-mcp/lists"}