Comet Opik

官方

用自然语言查询和分析你的Opik日志、追踪、提示词以及所有来自大语言模型的其他遥测数据。

文档

opik-mcp

从旧版 npx opik-mcp 迁移？ TypeScript 服务器已弃用，并将于 2026-11-15 停用。请在您的 MCP 客户端配置中将 npx -y opik-mcp 替换为 uvx opik-mcp@latest。完整指南：legacy/typescript/MIGRATION.md。

用于 Opik + Ollie 的模型上下文协议服务器。 将您的 AI 主机（Claude Code、Cursor、VS Code Copilot、MCP Inspector）直接接入您的 Opik 工作区——读取追踪、记录评分、保存提示版本，并向 Ollie 提出调查性问题，一切都在聊天中完成。

专为已在运行 Opik 并希望从他们编码时使用的同一 AI 助手驱动它的 LLM 工程师打造。

You:    "Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?"
Claude: → ask_ollie → reads experiment + traces → "Three traces failed because…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

安装

opik-mcp 是一个 Python 包（需要 Python 3.13+）。推荐的运行方式是 uvx，它会按需获取并运行最新发布的版本——无需全局安装，无需管理虚拟环境。

一次性安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv

您需要从 Opik 工作区获取两样东西：

OPIK_API_KEY — 从 comet.com/api/my/settings/ 获取。
OPIK_WORKSPACE — 您的工作区名称（小写，与 URL 中显示的一致）。例如 https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai。可选——默认为 default（Opik SDK 约定），这对于本地/OSS 安装是正确的；使用命名工作区的云用户应设置此项。COMET_WORKSPACE 作为已弃用的别名被接受。

预发布说明： opik-mcp（Python）尚未发布到 PyPI。在首个 PyPI 版本发布之前，请将以下任何代码片段中的 uvx opik-mcp 替换为： uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE 是可选的。 在以下任何代码片段中省略 OPIK_WORKSPACE 行/键，服务器将使用 default 工作区（对于本地/OSS 安装是正确的）。仅在连接到命名云工作区时设置它。

Claude Code

使用一条命令添加服务器：

claude mcp add --transport stdio opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env OPIK_WORKSPACE=<your-workspace> \
  -- uvx opik-mcp

或直接编辑 ~/.claude.json：

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

重启 Claude Code。使用 /mcp 验证——opik-mcp 应显示为已连接。然后，在聊天中询问：“列出我的 Opik 项目”——Claude 将调用 list 工具，您将看到工作区的项目。

Cursor

编辑 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目），或打开 Cmd+Shift+J → 功能 → 模型上下文协议：

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

重新加载 Cursor；MCP 面板中 opik-mcp 旁边的绿点确认连接。在聊天中询问：“列出我的 Opik 项目”。

Cursor 60 秒超时。 Cursor 强制执行硬性工具调用超时，该超时不会在进度通知时重置。长时间的 ask_ollie 轮次将在 Cursor 上失败。请参阅已知主机限制。

VS Code Copilot

在您的工作区（或用户设置 JSON）中配置 .vscode/mcp.json：

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

重新加载窗口；一旦服务器可访问，Copilot Chat 的 MCP 指示器将显示 opik-mcp。在聊天中询问：“列出我的 Opik 项目”。

MCP Inspector（手动测试）

OPIK_API_KEY=<your-key> OPIK_WORKSPACE=<your-workspace> \
  npx @modelcontextprotocol/inspector uvx opik-mcp

自托管 Opik

将 COMET_URL_OVERRIDE（以及如果 Opik 位于非默认路径时的 OPIK_URL）添加到您主机配置中的同一 env 块：

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

ask_ollie 和 run_experiment 仅在 Comet Cloud 上可用——在自托管环境中，这些调用在调度时会失败，因此请直接使用 read / list / write。设置 OPIK_MCP_ANALYTICS_SOURCE="" 将使您的安装选择退出遥测事件上的云 Comet 源标签。

工具

opik-mcp 暴露了一个小巧、面向结果的界面——六个工具覆盖了完整的生命周期（读取 → 标注 → 整理 → 创作 → 迭代）。

工具	用途
`read`	通过 ID / 名称 / `opik://` URI 进行通用读取
`list`	带有可选名称过滤器和分页的通用列表
`ask_ollie`	通过 Opik 产品内助手进行调查/综合
`write`	通用写入——记录追踪/跨度、评分、评论、保存提示、管理测试套件和实验
`schema`	内省写入操作模式（由 LLM 用于构建有效负载）
`run_experiment`	通过 Ollie 端到端运行评估实验

`read`

一个工具解决任何“向我展示 X”的问题。接受一个 entity_type 加上一个 id （UUID 或对于可命名类型，一个名称）或一个完整的 opik:// URI。复合读取（trace、prompt）内联其子项，因此一次调用即可返回完整画面。

支持的实体： project、trace、span、test_suite、experiment、 prompt。基于名称的查找适用于 project、experiment、prompt、 test_suite（较慢——两次 API 调用——并且可能返回多个匹配项）。

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")          # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")

`list`

使用可选的名称过滤器和分页浏览集合。项目范围类型（trace、test_suite_item、prompt_version）需要其父级 UUID。

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="trace", project_id="<project-uuid>") # traces of one project

`ask_ollie`

用于调查性问题、跨实体综合或任何需要 Opik 领域专业知识的情况。Ollie 对您的工作区具有直接读取访问权限，并且可以在被要求时在流中执行写入（评分、评论、测试套件项目、提示版本）。

ask_ollie(query="Why are spans in project 'demo' slower this week than last?")
ask_ollie(query="Compare experiments A and B on factuality. Score the bottom 5 traces of A 0.2 with reason.")

返回助手的最终文本以及一个 thread_id。在后续操作中将其传回以保留上下文——Ollie 没有跨线程的记忆。

YOLO 模式（默认）。 Ollie 在流中执行的写入无需每次操作确认即可执行。每次自动批准都作为 JSON 审计行记录在 opik_mcp.audit Python 日志记录器上。要改为要求确认，请设置 OPIK_MCP_AUTO_APPROVE=disabled——Ollie 的确认请求随后会作为类型化错误出现，您可以手动重新发出。

仅在 Comet Cloud 上可用。

`write`

通用写入调度器。传递 operation + data，调度器将验证有效负载，应用正确的 REST 动词，并返回后端响应。

操作：

操作	作用
`trace.create`	记录单个追踪（或批量）。作为跨度/评分/评论的父级。
`trace.update`	完成或修改现有追踪。
`span.create`	在现有追踪上记录跨度（或批量）。
`score.create`	将数值反馈评分附加到追踪、跨度或线程。
`comment.create`	将自由文本评论附加到追踪、跨度或线程。
`prompt_version.save`	保存新的提示版本（如果缺失，则按名称创建提示）。
`test_suite.create`	创建评估测试套件。
`test_suite_item.upsert`	将项目更新插入测试套件（始终使用信封形状）。
`experiment.create`	创建限定于测试套件的实验。
`experiment_item.create`	将追踪 + 数据集项目行附加到实验。

write(operation="score.create", data={
  "target": "trace",
  "target_id": "7f2e3c8a-…",
  "name": "helpfulness",
  "value": 0.9,
  "reason": "great recovery"
})

`schema`

在调用任何写入操作之前，检查其确切的 JSON 形状和必填字段—— 当您不确定 data 应该是什么样子时很有用。返回模式、OAuth 范围和一个经过验证的示例。纯查找，无后端调用。

schema(operation="score.create")
schema(operation="prompt_version.save")

`run_experiment`

通过 Ollie 端到端运行评估实验。接受一个单一的 experiment_config 字典，该字典镜像 Opik 的实验形状（提示、测试套件、评分器）；Ollie 执行运行并将结果作为 Opik 实验写回。

run_experiment(experiment_config={
  "test_suite_name": "qa-eval-v2",
  "prompt_name": "welcome-msg",
  # … see `schema(operation="experiment.create")` for the full shape
})

仅在 Comet Cloud 上可用。

配置

每个设置都是一个环境变量。必需的以粗体显示。

身份/端点

变量	默认值	备注
`OPIK_API_KEY`	—	`ask_ollie` 和任何经过身份验证的读/写所必需。
`OPIK_WORKSPACE`	`default`	工作区名称。可选——回退到 `default`（Opik SDK 约定）。使用命名工作区的云用户应设置此项。
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` 的已弃用别名（向后兼容）。如果两者都设置，则 `OPIK_WORKSPACE` 优先。
`COMET_WORKSPACE_ID`	—	可选的工作区 UUID。设置后，将标记到分析事件中，以便 BI 可以基于稳定的 ID 而不是（可变的）工作区名称进行连接。
`COMET_URL_OVERRIDE`	`https://www.comet.com`	设置为您自托管的 Comet 主机，或用于暂存环境的 `https://dev.comet.com`。
`OPIK_URL`	从 `COMET_URL_OVERRIDE` + `/opik/api` 派生	仅在 Opik 位于与 Comet UI 不同的主机/路径时覆盖。
`OPIK_DEFAULT_PROJECT_NAME`	未设置	设置后，每个会话的 `instructions` blob 会告诉 LLM 在每次工具调用时将其作为 `project_name` 传递，除非用户指定了不同的项目。

服务器/传输

变量	默认值	备注
`OPIK_MCP_TRANSPORT`	`stdio`	主机启动时为 `stdio`，监听端口时为 `streamable-http`。
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn 绑定主机（仅限 `streamable-http`）。
`OPIK_MCP_PORT`	`8080`	uvicorn 绑定端口（仅限 `streamable-http`）。
`OPIK_MCP_RELOAD`	`false`	设置为 `true` 以启用 uvicorn `--reload`（仅限开发）。
`OPIK_MCP_AS_URL`	未设置	OAuth 授权服务器 URL，在 `/.well-known/oauth-protected-resource`（RFC 9728）中公布，并用作 AS 发现探测的代理目标。MCP 主机通过 HTTP 启动 OAuth 舞蹈所必需。
`OPIK_MCP_RESOURCE_URI`	未设置	此服务器的规范公共 URI，在受保护资源元数据中作为 `resource` 公布，并用于派生 `WWW-Authenticate` 提示。
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr 日志记录器阈值。

选择传输方式

opik-mcp 在 HTTP 传输上不执行本地凭据验证：任何格式良好的 Authorization: Bearer …（Opik API 密钥或 opik_mcp_at_… OAuth 访问令牌）都会逐字转发到 opik-backend，后者是唯一的身份验证执行点。根据部署形态选择传输方式：

场景	传输方式
MCP 客户端和 Opik 在同一台机器上（本地 OSS 安装）	stdio（推荐——最简单，无端口，无需 OAuth 设置）
本地 MCP 客户端 → 远程 Opik（Comet 云/自托管）	使用 `OPIK_API_KEY` 的 stdio，或使用 OAuth 的 HTTP（`OPIK_MCP_AS_URL` 指向后端）
托管在与 opik-backend 相同边缘后的 opik-mcp	HTTP——持有者由后端按请求验证

本地 OSS 安装注意事项：OSS 后端不对请求进行身份验证，因此位于其前面的 HTTP opik-mcp 与 OSS REST API 本身一样开放。在共享网络上保持默认的 127.0.0.1 绑定（并优先使用 stdio）。

Ollie / 长时间调用

变量	默认值	备注
`OPIK_MCP_AUTO_APPROVE`	`enabled`	设置为 `disabled` 以要求 Ollie 的流中写入在继续之前获得每次操作批准。在公布 MCP `elicitation` 能力的主机上，用户会看到是/否提示；在较笨的主机上，请求会作为类型化错误出现，您可以手动重新发出。
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie 的流中确认提示在被视为取消之前可以等待用户多长时间。`0` 禁用此限制（仅限调试）。
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie pod 冷启动轮询上限。
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	冷启动轮询间隔。
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	看门狗节奏——当 pod 静默时发出 `notifications/progress` 滴答声，以防止主机超时。
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	pod 静默的硬上限，超过后 `ask_ollie` 将中止。`0` 禁用（仅限调试）。

遥测

匿名使用事件（仅事件类型和计时——无查询内容）。包含您 API 密钥的 SHA-256 摘要，以便支持人员可以找到您的账户；原始密钥永远不会离开进程。选择退出： OPIK_MCP_ANALYTICS_ENABLED=false。

变量	默认值	说明
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	设置为 `false` 可禁用所有遥测。
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	用于测试环境的覆盖设置。
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	每个事件上的标签（`prod` / `staging` / `dev`）。
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	接收端用于标记 `on_prem=False`。本地部署应覆盖为 `""` 或自己的域名。
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP 连接超时。
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP 请求总超时。

已知的主机限制

MCP 规范允许主机在 notifications/progress 上重置其工具调用超时 — opik-mcp 会为每个 Ollie SSE 事件发送一次，外加一个 15 秒的看门狗心跳。实际情况参差不齐：

Claude Code — 没有文档记录的工具调用超时；心跳会保持调用活跃，直到 message_end。推荐使用。
Cursor — 硬性 60 秒超时，且不会在收到进度通知时重置（上游缺陷）。长时间的 Ollie 轮次会失败。请保持 ask_ollie 查询聚焦。
MCP Inspector — MAX_TOTAL_TIMEOUT 限制了总持续时间（默认 60 秒）。对于长时间操作，请在 Inspector 界面中调高该值。

如果调用卡住，请设置 OPIK_MCP_LOG_LEVEL=DEBUG — 心跳失败（通常是主机断开连接）会以调试级别记录在 opik_mcp.ask_ollie 上。

故障排除

OPIK_API_KEY is required to use ask_ollie — 该变量未传递到服务器进程。在 Claude Code / Cursor / VS Code 中，环境变量仅在 MCP 服务器配置的 env 块内生效，而不是在你的 shell 中。编辑后请重启主机。

ask_ollie 在 2 分钟后返回“pod 未就绪” — Ollie pod 的冷启动超过了 OPIK_MCP_POD_READY_TIMEOUT_S。请重试 — 第二次调用通常会命中一个已就绪的 pod。

在自托管 Opik 上 ask_ollie / run_experiment 因调度错误而失败 — 这些工具仅在 Comet Cloud 上可用。在自托管环境中，请直接使用 read / list / write。

Cursor 调用在 60 秒时超时 — 这是 Cursor 的已知缺陷，并非 opik-mcp 的问题。可以缩短 Ollie 查询，或在没有硬性上限的 Claude Code 上运行相同的操作。

开发

git clone [email protected]:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --extra dev
make check          # lint + typecheck + test
make run-dev        # uvicorn with --reload + DEBUG logs
make inspect        # MCP Inspector against the running server

常用目标：

目标	作用
`make install`	`uv sync --extra dev`
`make run`	运行 MCP 服务器（默认使用 stdio）。
`make run-dev`	使用 DEBUG 日志记录 + uvicorn `--reload` 运行。
`make dev`	通过 `mcp dev`（Inspector 开发模式包装器）运行。
`make inspect`	针对正在运行的服务器启动 MCP Inspector。
`make test`	`uv run pytest -q`。
`make test-live`	针对 `dev.comet.com` 进行实时端到端测试（设置 `OPIK_API_KEY` + `OPIK_WORKSPACE`）。
`make lint`	`ruff check` + 格式检查。
`make format`	`ruff format` + `ruff check --fix`。
`make typecheck`	`mypy`。
`make check`	`lint + typecheck + test`。

仓库布局：

opik-mcp/
├── src/opik_mcp/        ← server, tools, ask_ollie, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

获取帮助

提交问题以报告缺陷和功能请求
Opik 文档用于 SDK / 后端文档
Comet 社区 Slack 用于提问

从 v2 升级？ 旧版 TypeScript 服务器仍以 opik-mcp@^2 (npx -y opik-mcp) 的形式在 npm 上发布；源代码保留在 legacy/typescript/ 下。有关支持政策，请参阅 legacy/typescript/DEPRECATED.md。

许可证

Apache-2.0。