Comet Opik
官方用自然语言查询和分析你的Opik日志、追踪、提示词以及所有来自大语言模型的其他遥测数据。
你可以用 Comet Opik MCP 做什么?
- 按项目查询追踪记录 — 查询项目中今天失败的追踪记录,并按错误信息、持续时间或令牌用量筛选。
- 读取任意 Opik 实体 — 通过 id、名称或
opik://URI 获取项目、追踪记录、跨度、数据集、实验、提示词、线程或 Diagnostics 问题。 - 记录评分和评论 — 通过写入工具,使用反馈指标和原因为追踪记录评分,或添加评论。
- 保存提示词版本 — 编写并保存新的提示词版本,以及数据集和实验。
- 检查写入架构 — 查询写入操作的架构,以便在发送前构建有效载荷。
- 检查项目健康状况 — 读取项目,获取过去 7 天的追踪记录数量、错误率、平均持续时间和总成本。
文档
Opik MCP Server
由 Comet 构建的开源 LLM 可观测性与评估平台 Opik 的官方 Model Context Protocol (MCP) 服务器。 将你的 AI 宿主(Claude Code、Cursor、VS Code Copilot、Codex、opencode 或任何 MCP 客户端)直接接入你的 Opik 工作区:读取追踪记录、记录评分并保存 提示词版本,所有操作都可以在聊天中完成。
专为已经在运行 Opik、并希望通过日常编写代码时使用的同一个 AI 助手来驱动 Opik 的 LLM 工程师打造。
You: "Which traces in project 'demo' failed today?"
Claude: → list(entity_type="trace", project_name="demo") → "Three traces failed…"
You: "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done
快速开始
只需一条命令,即可在你机器上的 AI 客户端中设置 Opik,包括 Claude Code。
它会查找你的 Opik(保存在 ~/.opik.config 中的实例、运行在
localhost 上的实例,或者询问你要使用哪个实例),注册 MCP 服务器、安装 Opik 技能包,
并检查连接。在 Opik Cloud 上无需处理 API 密钥:
客户端会在浏览器中登录。需要 uv
且无需 Opik SDK:
uvx opik@latest mcp configure
如果无法使用终端,例如通过编码代理或脚本操作,请指定客户端:
uvx opik@latest mcp configure --ai-client claude-code --skills
--ai-client 还接受 codex、cursor、vscode 和 opencode。以这种方式运行时,它会使用
保存在 ~/.opik.config 中的 Opik(包括 API 密钥),或使用 localhost 上
响应的实例;如果两者都没有,则会停止并询问 --deployment。
如果编码代理收到“install opik mcp”的请求,它会从 uvx opik-mcp@latest --help 获取完整步骤,
包括需要向用户询问的内容。这些步骤与下文的
使用编码代理安装 相同。
手动注册服务器(客户端命令见 手动设置)会跳过检查你使用的是哪个 Opik,也不会安装技能包, 因此适用于安装程序不支持的客户端。
| 你的 Opik | 服务器 | 传输方式 | 登录 |
|---|---|---|---|
Opik Cloud (www.comet.com) | 托管服务器,由 Comet 运行 | Streamable HTTP | 在浏览器中(OAuth);无需 API 密钥 |
| 自托管 Comet、开源 Opik | 本地服务器,此软件包 | stdio | 环境变量;仅在部署需要时使用 API 密钥 |
客户端会在会话启动时加载 MCP 服务器,因此设置完成后请启动新会话。
设置指南、故障排除和常见问题:comet.com/docs/opik/mcp-server。
Opik Cloud:托管服务器
Comet 在 https://www.comet.com/opik/api/v1/mcp 运行服务器。你的客户端
通过 HTTP 连接,并在首次使用时打开浏览器进行登录。无需安装任何内容、无需 API 密钥,
也无需设置工作区:服务器会使用你登录时选择的工作区。添加服务器后,启动新会话,
然后询问:“列出我的 Opik 项目”。
快速开始 命令可为 Claude Code、Codex、 Cursor、VS Code Copilot 和 opencode 完成设置,并安装技能包。在 Claude Code 中, 插件 可通过一条命令完成相同操作。下方的按钮可一键将其添加到 Cursor 或 VS Code;其他手动注册方式见 手动设置。
Claude Code 插件
opik 插件会安装 Opik 技能,并为 Opik Cloud 注册托管 MCP 服务器:
/plugin install opik --marketplace comet-ml/opik-mcp
在低于 2.1.275 的 Claude Code 版本中,运行 /plugin marketplace add comet-ml/opik-mcp,
然后运行 /plugin install opik@opik。技能会以 opik:<skill> 的形式加载,例如
opik:opik-instrument;/mcp 会将服务器显示为 plugin:opik:opik-cloud。
该服务器属于 Opik Cloud。启动新会话,然后从 /mcp →
Authenticate 登录。对于运行 MCP OAuth 服务器的自托管 Comet,请使用
claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp 添加;
对于其他自托管或开源 Opik,请使用
快速开始 命令。然后在
/mcp 中禁用 plugin:opik:opik-cloud。Claude Code 不会自动更新
此市场中的插件:运行 /plugin marketplace update opik,然后运行
/plugin update opik@opik,或者在 /plugin 中启用市场的自动更新。此市场提供
main,可能比最新发布版本更新。只有在每次发布时插件版本发生变化后,
才会收到更新。
如果你之前在相同 URL 添加过 opik-mcp,Claude Code 会保留你的副本,
并跳过插件提供的副本。如果你的副本是另一个服务器,例如本地的
uvx opik-mcp,则两者都会加载:运行 claude mcp remove opik-mcp,只保留
插件提供的服务器。技能包中的技能也会与插件提供的副本同时加载;
运行 npx skills remove --global --agent claude-code 可移除它们,系统会询问你要移除哪些技能。
自托管和开源 Opik:本地服务器
opik-mcp 在你的机器上运行:客户端通过 uvx opik-mcp 启动它,
并通过 stdio 与其通信。快速开始 命令会根据你的
~/.opik.config 或本地 Opik 完成设置;如需手动注册,请参阅
手动设置。只需安装一次 uv;
首次使用时,它会获取软件包,并在需要时安装 Python 3.13:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
# or: brew install uv
uvx opik-mcp 会复用 uv 缓存的副本,因此启动速度很快;
uv cache clean opik-mcp 会让下次启动时获取最新版本。
uvx opik-mcp@latest 会在每次启动时查询 PyPI,因此会多花大约一秒半。Codex 会等待
mcp_optional_startup_grace_ms(默认 1 秒),然后才为服务器构建第一个工具列表,
因此启动较慢时,工具可能不会出现在第一轮对话中。本 README 中的一次性命令(opik mcp configure、
opik mcp status、--help、--check)都带有 @latest,
因此绝不会运行 uv 几个月前缓存的副本。
环境变量用于将服务器指向你的 Opik:
| 你的 Opik | 环境变量 |
|---|---|
| 此机器上的开源 Opik | OPIK_URL=http://localhost:5173/api |
| 服务器上的开源 Opik | OPIK_URL=https://<host>/api;仅当部署启用了身份验证时才需要 OPIK_API_KEY |
自托管 Comet 平台(Opik UI 位于 https://<host>/opik) | COMET_URL_OVERRIDE=https://<host>、OPIK_WORKSPACE、OPIK_API_KEY |
- 开源版本在
/api提供 API,且只有一个工作区default,因此 不需要OPIK_WORKSPACE。COMET_URL_OVERRIDE会将服务器指向/opik/api,而开源版本并不提供该服务。 - 自托管 Comet 使用命名工作区。将
OPIK_WORKSPACE设置为 Opik URL 中/opik/后面的路径段;如果不设置,读取操作会使用你账户的默认工作区, 但不会报错提示这一点。 - 运行 MCP OAuth 服务器(默认关闭)的自托管 Comet 也可以使用托管流程,地址为
https://<host>/opik/api/v1/mcp。 - 替换所有值。服务器会拒绝诸如
<your-workspace>或${input:OPIK_WORKSPACE}这样的 占位工作区;占位 URL 会原样发送,并导致连接失败。 - 在
env块中设置OPIK_MCP_ANALYTICS_SOURCE="",可让自托管安装 不再将云端 Comet 标记为遥测事件的来源。
将服务器添加到客户端之前,请检查设置:使用相同的环境变量和 --check 运行它。
它会调用一次 Opik,并打印工作区及其项目数量;如果有问题,则会说明需要修复的内容并附上文档链接,
最后以 0 或 1 退出。客户端无法在新会话启动前告诉你这些信息:即使密钥错误,
Claude Code 仍会显示 Connected,而 Codex 在此之前不会启动任何内容。
OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check
然后向客户端注册服务器:手动注册本地服务器。
使用编码代理安装
适用于收到“install opik mcp”等安装服务器请求的 AI 代理。目标是为用户的 Opik 注册服务器、
安装 Opik 技能包,并让用户完成登录。请从这台机器上确认用户使用的是哪个 Opik,
只询问你无法自行判断的信息:每条消息只问一个问题,并在收到回答后再问下一个问题。
第 3 步中的安装程序会一次性完成整个设置,因此请先完成第 1 和第 2 步,再运行它。
uvx opik-mcp@latest --help 会打印这些步骤。
-
查看现有配置。
uvx opik@latest mcp status它会显示保存在
~/.opik.config中的 Opik(URL 和工作区,不会显示密钥), 以及已配置服务器的客户端。在 Claude Code 中,还要运行claude mcp list: 它会显示 claude.ai 连接器和使用其他名称的条目。它还会打印每个条目的命令; 旧的 npx 条目可能包含 API 密钥:不要复述该命令。- 任何名称下配置的
https://www.comet.com/opik/api/v1/mcp服务器(例如 claude.ai 连接器)都表示服务器已注册: 不要重复添加。单独安装技能包即可,使用npx skills add comet-ml/opik-skills -g --all。如果服务器显示为! Needs authentication,请转到第 4 步。 - 安装程序会直接替换现有的
opik-mcp条目,不会询问,例如旧的 npx 服务器。 运行前请先询问用户。
- 任何名称下配置的
-
确认用户使用的 Opik。
- 已保存在
~/.opik.config中:使用该配置,并告知用户你要设置的是哪个实例。 安装程序会读取该配置,包括 API 密钥,因此不要询问密钥。 - 没有
~/.opik.config:curl -s http://localhost:5173/api/is-alive/ping。 如果有响应,说明这台机器上运行着开源 Opik。在沙盒 shell 中(例如 Codex 的 shell), 没有响应可能意味着 shell 无法访问网络,而不是没有 Opik。 - 两者都没有:询问用户,不要自行选择。项目中的 Opik URL(例如
.env中的OPIK_URL_OVERRIDE)可以将问题变成是非题。 否则请问:“你使用的是哪个 Opik:Opik Cloud (www.comet.com)、开源 Opik(其 URL), 还是自托管 Comet 平台(其 URL 和工作区)?”
- 已保存在
-
运行安装程序,并指定你正在使用的客户端。它会连同服务器一起安装 Opik 技能包,无论是否使用
--skills;如果你要提供命令让用户稍后运行,请保留该标志。 在 Opik Cloud 上,安装程序会打开浏览器登录页面,并等待一分钟,因此请提前告知用户。uvx opik@latest mcp configure --ai-client claude-code --skills--ai-client还接受codex、cursor、vscode和opencode。 如果 Opik 保存在~/.opik.config中或运行在 localhost 上,请直接运行:--deployment会暂存已保存的配置,包括 API 密钥。如果两者都没有,请根据用户在第 2 步中 指定的 Opik 添加相应标志:用户使用的 Opik 添加 Opik Cloud, www.comet.com--deployment cloud开源 Opik --deployment local;如果不在 localhost 上,则还需添加--url <url>自托管 Comet 平台,URL 中包含 /opik/--deployment self-hosted --url <url> --workspace <workspace>,并在 shell 中设置OPIK_API_KEY如果失败(例如 Opik 没有响应),请告知用户程序输出的内容以及需要检查的项目,例如 VPN 或 URL。 不要切换到另一个 Opik。
-
Opik Cloud 登录。 如果安装程序报告服务器尚未登录,请让用户运行
claude mcp login opik-mcp,或在 Claude Code 会话中运行/mcp,不要替用户运行: 该命令会等待浏览器操作。claude.ai 连接器应从/mcp登录。 登录时会要求选择工作区;如果~/.opik.config中保存了工作区,请指定该工作区。 -
完成。 说明已安装的内容和剩余步骤。请明确提及技能包: Opik 技能,已为每个项目安装,可指导代理使用 Opik 进行插桩、 评估和调试。客户端会在会话启动时加载 MCP 服务器和技能:请用户启动新会话, 然后尝试询问 “列出我的 Opik 项目”。
无论采用哪种方式:
-
不要让用户在聊天中粘贴 API 密钥。托管服务器不需要密钥;其他情况下,请从 shell 环境 (
"$OPIK_API_KEY") 中读取,或让用户自行运行命令。 -
不要猜测工作区。它是用户 Opik URL 中
comet.com/opik/后面的路径段 (自托管 Comet 则是/opik/后面的路径段)。 -
不要打印
~/.claude.json或~/.opik.config:两者都可能包含 API 密钥。uvx opik@latest mcp status和claude mcp list会显示所需信息,安装程序会自行读取配置。 -
如果权限检查阻止了命令,不要绕过检查。请将命令交给用户运行(在 Claude Code 中, 运行前先执行
!)。 对于安装程序不认识的客户端,请使用手动设置中的命令手动注册:Opik Cloud 使用托管服务器,其他情况使用本地服务器。 -
注册本地服务器前,请使用你将传入的环境变量运行它,并使用
--check;在 shell 中导出OPIK_API_KEY,不要将其写在命令中:OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check。它会以状态码 0 退出,并显示它检测到的工作区,或指出需要修复的内容。注册后,即使密钥错误,Claude Code 也会报告 Connected,而 Codex 没有检查机制。 -
Claude Code 不允许覆盖现有的
opik-mcp条目,因此请先使用claude mcp remove opik-mcp --scope user将其移除;Codex 的add会替换该条目。 -
注册后,在 Claude Code 中只查看状态行:
claude mcp get opik-mcp | grep Status。完整输出会打印env块,其中包含 API 密钥。托管服务器会显示! Needs authentication,直到运行claude mcp login opik-mcp。Codex 没有可在会话开始前启动服务器的功能;codex mcp get opik-mcp会显示已保存的内容,并屏蔽环境变量值。
手动设置(不检查 Opik,不安装技能包)
快速开始命令会为 Claude Code、Codex、Cursor、VS Code Copilot 和 opencode 完成所有这些操作,还会检查你使用的是哪个 Opik 并安装技能包。只有在使用其他客户端,或想查看安装程序写入的内容时,才需要手动注册。为用户安装的编码代理应运行安装程序:请参阅使用编码代理安装。
托管服务器(Opik Cloud)
手动设置 Claude Code
claude mcp add --scope user --transport http opik-mcp https://www.comet.com/opik/api/v1/mcp
然后在 Claude Code 会话中通过 /mcp → Authenticate 登录。这会打开浏览器,由键盘前的用户完成操作;在自己的终端中运行 claude mcp login opik-mcp 也会执行相同操作。--scope user 会让服务器在每个项目中都可用;如果不使用它,Claude Code 只会为当前目录注册服务器。通过 SSH 连接时,claude mcp login opik-mcp --no-browser 会打印登录 URL,供你在自己的机器上打开;最后一步需要交互式终端(ssh -t)。
手动设置 Codex
codex mcp add opik-mcp --url https://www.comet.com/opik/api/v1/mcp
add 会打开登录页面;codex mcp login opik-mcp 会再次打开。在 ~/.codex/config.toml 中,同一服务器的配置如下:
[mcp_servers.opik-mcp]
url = "https://www.comet.com/opik/api/v1/mcp"
手动设置 Cursor
使用托管服务器下方的按钮,或添加到 ~/.cursor/mcp.json:
{
"mcpServers": {
"opik-mcp": {
"url": "https://www.comet.com/opik/api/v1/mcp"
}
}
}
手动设置 VS Code Copilot
使用托管服务器下方的按钮,或添加到工作区中的 .vscode/mcp.json,或添加到用户的 mcp.json(MCP: Open User Configuration):
{
"servers": {
"opik-mcp": {
"type": "http",
"url": "https://www.comet.com/opik/api/v1/mcp"
}
}
}
其他客户端
任何支持 URL 的客户端都可以使用托管服务器:
npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp
只能启动本地命令的客户端可以通过 npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp 连接到它。
使用 API 密钥连接 Opik Cloud
如果无人能完成浏览器登录,例如代理通过脚本无人值守运行,或客户端不支持 MCP OAuth,请改用来自comet.com/api/my/settings/的 API 密钥,并将本地服务器指向 Opik Cloud:
claude mcp add --scope user opik-mcp \
--env OPIK_API_KEY="$OPIK_API_KEY" \
--env OPIK_WORKSPACE=<workspace> \
-- uvx opik-mcp
其他客户端在其 env 块中使用相同的两个变量。将 OPIK_WORKSPACE 设置为 Opik URL 中 comet.com/opik/ 之后的部分(https://www.comet.com/opik/acme-ai/projects → acme-ai)。如果省略,服务器会发送 default,Comet 会将其解析为你账户的默认工作区,因此读取操作可能会从错误的工作区获取数据,且不会报错。
本地服务器(自托管和开源 Opik)
示例使用本地开源 Opik。对于自托管的 Comet,请替换为表格中的三个变量。 添加服务器后,启动新会话并询问:“列出我的 Opik 项目”。
手动设置 Claude Code
claude mcp add --scope user opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp
对于自托管的 Comet,请将密钥放在 shell 的 OPIK_API_KEY 中:
claude mcp add --scope user opik-mcp \
--env COMET_URL_OVERRIDE=https://<host> \
--env OPIK_WORKSPACE=<workspace> \
--env OPIK_API_KEY="$OPIK_API_KEY" \
-- uvx opik-mcp
或者直接编辑 ~/.claude.json:
{
"mcpServers": {
"opik-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["opik-mcp"],
"env": {
"OPIK_URL": "http://localhost:5173/api"
}
}
}
}
服务器启动后,claude mcp get opik-mcp 会显示 ✔ Connected。这并不能证明 URL 或密钥正确,因为只有工具调用才会访问 Opik;--check(本地服务器)才会执行此检查。它还会打印 env 块,其中包含 API 密钥。
手动设置 Codex
codex mcp add opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp
或者编辑 ~/.codex/config.toml:
[mcp_servers.opik-mcp]
command = "uvx"
args = ["opik-mcp"]
env = { OPIK_URL = "http://localhost:5173/api" }
# On a self-hosted Comet, forward the key from the environment Codex starts in,
# so it stays out of this file:
# env_vars = ["OPIK_API_KEY"]
# Time allowed for the server to start (default 10 s); the first start
# downloads the package.
startup_timeout_sec = 30
Codex 只会向本地服务器传递 env 中的变量和 env_vars 中的名称,因此除非另行配置,否则在 shell 中导出的密钥不会传递给它。
手动设置 Cursor
添加到 ~/.cursor/mcp.json(全局)或 .cursor/mcp.json(项目),或者使用 Cmd+Shift+J → Features → Model Context Protocol:
{
"mcpServers": {
"opik-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["opik-mcp"],
"env": {
"OPIK_URL": "http://localhost:5173/api"
}
}
}
}
Cursor 60 秒超时。 Cursor 对工具调用强制实施硬性超时,进度通知不会重置计时。请参阅已知的宿主限制。
手动设置 VS Code Copilot
添加到工作区中的 .vscode/mcp.json,或添加到用户的 mcp.json(MCP: Open User Configuration):
{
"servers": {
"opik-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["opik-mcp"],
"env": {
"OPIK_URL": "http://localhost:5173/api"
}
}
}
}
MCP Inspector(手动测试)
OPIK_URL=http://localhost:5173/api npx @modelcontextprotocol/inspector uvx opik-mcp
从 npx opik-mcp 迁移?
TypeScript 服务器(npm opik-mcp@2)已弃用,并将于 2026-11-15 停止处理请求。全新安装请运行快速开始命令;uvx opik-mcp 是客户端用于启动服务器的命令,不是安装程序。要迁移 Opik Cloud 上的现有配置,请切换到托管服务器并移除 API 密钥。否则,请在 MCP 客户端配置中将 npx -y opik-mcp 替换为 uvx opik-mcp。部分环境变量已重命名,命令行标志也不再读取:请参阅https://github.com/comet-ml/opik-mcp/blob/main/legacy/typescript/MIGRATION.md。
支持政策:DEPRECATED.md。
TypeScript 源码位于 git 标签 legacy-typescript-final。
工具
opik-mcp 提供一组精简、以结果为导向的工具,覆盖完整生命周期(读取 → 标注 → 整理 → 编写 → 迭代)。
| 工具 | 用途 |
|---|---|
read | 按 ID / 名称 / opik:// URI 通用读取 |
list | 通用列表查询,支持可选名称筛选和分页 |
write | 通用写入——记录 traces/spans、评分、评论、保存 prompts、管理 datasets 和 experiments |
schema | 检查写入操作的 schema(供 LLM 构造有效载荷) |
read_skill | 读取此服务器附带的一项 Opik 代理技能 |
read
一个工具即可回答任何“显示 X”的问题。它接受一个 entity_type,以及一个 id(UUID,或对于可按名称识别的类型,使用名称),或者完整的 opik:// URI。复合读取(trace、prompt、thread、agent_insights_issue)会内联其子项,因此一次调用即可返回完整信息。
指定的记录会完整返回。内联的子项则不会:其内容通过后端的 truncate=true 获取,因此在 ClickHouse 中,超过约 10 KB 的字段会被截断,base64 图像会替换为 "[image]"——否则,同一附件在 200 个 spans 中重复回显,成本会超过读取其他所有内容的总和。响应会在 spanBodies / messageBodies 中说明这一点;任何子项都可以通过其自身的 read("span", id) 或 read("trace", trace_id) 完整读取,这些接口完全没有 truncate 参数。
内联集合的长度也有限制:200 个 spans、200 个 turns、100 个 prompt 版本。超过限制时,spansTruncated / messagesTruncated / versionsTruncated 会显示为 true,旁边的 moreSpans / moreMessages / moreVersions 行会提供数量,以及从内联部分停止处继续读取的准确 list(...) 调用。
支持的实体:project、trace、span、dataset、dataset_item、experiment、prompt、thread、agent_insights_issue。project、experiment、prompt、dataset 支持按名称查找(速度较慢——需要两次 API 调用——且可能返回多个匹配项)。thread 和 agent_insights_issue 需要指定项目范围:传入 project_id 或 project_name,或传入包含项目的链接/URI。dataset 和 dataset_item 以前分别称为 test_suite 和 test_suite_item;旧名称仍可解析,但不会再公开,新代码应使用新名称。
read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo") # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")
read(entity_type="agent_insights_issue", id="<issue-uuid>", project_id="<project-uuid>")
read(
entity_type="agent_insights_issue",
id="https://www.comet.com/opik/<ws>/projects/<pid>/diagnostics?issue=<id>",
)
从 Opik UI 复制的链接可用作 id:线程链接或 Diagnostics 页面链接会包含项目,因此无需 project_id,实体类型也会从链接中获取。
project 读取可通过一次调用回答“我的项目运行情况如何”。它会返回 {project, summary, vocabulary, contains, url}:先是记录,然后是 Logs 页面卡片中显示的四项指标(trace 数量、错误率、平均时长、总成本),比较最近 7 天与之前 7 天的数据;与界面一样,仅统计 SDK 流量。since / until 可调整时间范围;since="30d" 是 UI 默认打开的时间范围。如果某个时间段内没有 traces,速率或平均值会返回 null,因为没有流量的一周显示 0% 错误率,会让人误以为这一周运行正常。
vocabulary 是进行其他查询前所需的映射:项目的反馈评分名称、token 使用量键,以及用于为 traces 评分的自动化规则。这些名称会用于筛选条件或下文的 series=;如果猜错,返回的页面会是空的,看起来像是好消息。评分名称和规则有数量上限,但始终会报告实际总数,并指出用于获取其余内容的调用;使用量键会完整列出,因为没有其他接口能枚举它们。contains 会列出最新的 experiment、dataset、prompt 版本和优化运行,因此无需再调用四次就能了解“这里最近发生了什么”。加载失败的部分会明确说明,而不会显示为空;空的部分则会省略。
agent_insights_issue 读取会返回 {issue, example_trace_ids, details}:
Diagnostics 问题记录(名称、描述、原因、建议的修复方法、严重性、状态)、表现出该问题的去重 trace ID(与 Diagnostics 页面显示的样本相同——使用 read("trace", id) 打开其中一个),以及按天汇总的数据。不会内联 trace 内容,因此读取只需一次后端调用。since / until 可缩小按天数据的范围;默认范围为全部时间。如果服务器知道 Opik URL 和会话工作区,读取结果还会包含 url(该问题的 Diagnostics 页面)和 trace_url_template(任一示例 trace 的深层链接),方便助手提供可点击的链接;如果 OAuth 会话无法解析工作区,则会省略这些链接,而不会猜测。
traces 本身不包含 URL——无法从 read 或 list 返回的字段推导出链接,猜测链接格式会导致 404。因此,会话说明中提供了链接模板 .../v1/session/redirect/projects/?trace_id={trace_id}&path=...,助手可填入 ID 并提供链接。该链接会经过 opik-backend 的重定向,由其根据 trace 解析项目和工作区,因此即使无法使用直接项目 URL,也能正常工作,包括无法解析工作区的 OAuth 会话。这与 Python SDK 为 trace 打印的链接相同。
list
浏览或搜索集合,并使用分页。项目范围内的类型(trace、span、thread、agent_insights_issue、dataset_item、prompt_version)需要指定其父级:项目 UUID 或名称、dataset UUID,或 prompt UUID。
list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank") # name substring filter
list(entity_type="agent_insights_issue", project_name="demo") # open Diagnostics issues
list(entity_type="agent_insights_issue", project_id="<uuid>", status="resolved")
list(entity_type="trace", project_name="demo") # latest traces of one project
list(
entity_type="trace", project_name="demo", filters="error_info is_not_empty AND duration > 5000"
)
list(
entity_type="span",
project_name="demo", # spans across the whole project
filters='type = "llm" AND usage.total_tokens > 10000',
)
list(
entity_type="thread",
project_name="demo",
filters="number_of_messages > 20 AND feedback_scores.helpfulness < 0.5",
)
list(entity_type="experiment", filters='dataset_id = "<dataset-uuid>" AND tags contains "baseline"')
筛选条件。 trace、span、thread、experiment 和 dataset_item 接受 OQL 字符串,语法与 SDK 的 search_traces(filter_string=…) 相同:
<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in
字符串使用双引号,数字不加引号,duration 的单位是毫秒,
日期为带时区的 ISO-8601 时刻("2026-09-08T10:00:00Z")。
分数和字典使用键:feedback_scores.accuracy < 0.5、
metadata.environment = "prod"。AND 是唯一的连接符。
与 UI 的 Logs 页面一样,trace、span 和 thread 列表会添加 source = "sdk",
以免评估器、playground 和实验的 trace 干扰视线;自行命名为 source
即可查看它们。第一行输出会回显已应用的筛选条件。
筛选条件有误时,会在请求到达后端之前失败,并说明如何修正:
语法错误的位置、最接近的字段名、该字段类型支持的运算符,或预期的值格式。
具有固定取值范围的字段(source、span type、thread status、visibility_mode)也会
进行校验,包括 in 列表中的每个元素。source 是唯一由后端自行校验的字段,
对于未知值,它会返回 500 而不是 400,因此大写字母会导致 source = "SDK" 变成不透明的服务器错误。
其余字段会按字符串比较,并返回空页面;这看起来像是“没有匹配项”,实际含义却是“没有此值”。如需完整字段参考(包括可接受的值),请查询
schema("list.trace")(或 list.span、list.thread、list.experiment)。
在数据集中查找单个案例。 list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key> 可按构建数据集时使用的键筛选,
full_data 可匹配整个 payload 中的子字符串(会进行完整扫描——尽可能指定键),还可按 id、tags、source、trace_id、
span_id 和时间戳筛选。data.<key> 仅接受六种字符串运算符
(=、!=、contains、not_contains、starts_with、ends_with);后端会对比较操作返回 400,因此此类操作会在调用前被拒绝。该端点不支持排序和自由文本搜索——sort 会被拒绝,而不是忽略。
read(entity_type="dataset_item", id=…) 会返回完整案例,可用于读取表格中被截断的值。
list(entity_type="dataset_item", dataset_id="<uuid>", filters='data.question contains "install"')
list(
entity_type="dataset_item", dataset_id="<uuid>", filters='trace_id = "<trace-uuid>"'
) # the case made from that trace
read(entity_type="dataset_item", id="<item-uuid>") # the case, uncut
使用 experiment_ids 时,同一列表会改为比较结果——即附带各次运行的案例——并按运行筛选(feedback_scores.<name>、
output、duration)。两者对应不同后端端点上的不同字段集:schema("list.dataset_item_case") 是数据集自身的案例,
schema("list.dataset_item") 则是比较结果。
排序。 trace、span、thread 和 experiment 默认采用
sort="<field> [asc|desc]"、desc,且一次只能指定一个字段:
sort="duration desc"、sort="total_estimated_cost"、
sort="feedback_scores.accuracy asc"、sort="usage.total_tokens"。调用前会根据实体可排序字段列表校验该字段,因为后端会静默忽略无法排序的字段。在非常大的工作区中,后端会完全取消排序;发生这种情况时,表头会予以说明。
dataset_item 仅在比较结果中支持排序(使用 experiment_ids):items 端点不接受排序参数,因此普通列表上的排序会被拒绝,而不是忽略。
时间范围和搜索。 trace、span 和 thread 接受 since 和
until,每个值可以是相对时间跨度("30m"、"1h"、"7d"),也可以是带时区的 ISO-8601 时刻,因此无需计算“过去一小时”的具体时间。时间范围依据记录创建时间;这对后端来说开销较低,并且对于实时流量,与 start_time 的差异在几秒以内。如需精确指定边界,请将
start_time 放入 filters。这三种类型也都接受 search,可在 id、name、input、output、metadata、tags 和 thread id 中任意位置匹配自由文本。搜索会扫描后端上的整个项目,因此大型项目的首次调用可能需要几十秒。这些调用的超时时间为 60 秒。添加 since 可恢复快速响应。
阅读表格。 时长标记为 duration_ms / ttft_ms,
并以整数毫秒显示;该字段在 filters 和
sort 中仍为 duration。时间戳显示到秒,成本以普通小数显示。项目行包含 last_updated_trace_at,便于查看哪些项目有实时流量;thread 行则包含第一条消息。时间范围筛选下的空页面会说明该项目最近一次 trace 的时间;默认 source = "sdk" 筛选下的空页面则会说明如何查看其他来源。拼写错误的
project_name 会返回最接近的现有名称。
list(
entity_type="trace",
project_name="demo",
since="1h",
filters="error_info is_not_empty",
sort="duration desc",
)
list(entity_type="trace", project_name="demo", search="order-42")
Diagnostics 问题。 agent_insights_issue 是通过 MCP 查看 Diagnostics 页面:它列出 Opik 的 Diagnostics 作业为某个项目归类的重复故障,并按 UI 的排序方式排列(最近出现的排在最前)。列包括 severity、
status、total_occurrences(累计总和)、latest_count(最近一次报告日期,即问题描述中提到的日期)和 last_seen。
默认列出未解决的问题;传入 status="resolved" 或 "closed" 可查看其余问题。read 和 list 也可通过 issue 查询,这是 UI 对这些问题的称呼;长名称是 entity_type 枚举中的名称,因此同一实体不会在其中重复出现。计数为累计值,与 UI 保持一致;与 trace 相同的 since / until 可缩小时间范围,但会截断到 UTC 报告日,因为 Diagnostics 按天聚合。
列表为空时会说明原因,因为“没有故障”和“尚未为此项目启用 Diagnostics”看起来并无区别。共有五种状态:此部署不提供 Diagnostics、此项目未启用、已关闭、已启用但近期未扫描,或已启用且状态正常并附有最近扫描时间。可采取操作的状态会指出要调用的操作,每种状态都会链接到项目的 Diagnostics 页面。
列表非空时会标明日期。问题是最近一次扫描归类的结果,因此回复会以 Report covers data through <time> 结尾;如果你请求的时间范围超出了该日期,则会指出未覆盖的时间段以及如何补齐:如果重新扫描覆盖到足够早的时间,则触发扫描;否则使用它提供的 since 查询原始 trace。对于每晚扫描一次的项目,如果请求一周的数据,归类结果会缺少最后一天;此处会说明这一点。
write("agent_insights_job.enable", {"project_name": "demo"}) 会启用 Diagnostics。
此后每天都会扫描,重复调用也安全。
write("agent_insights_job.trigger", …) 会立即扫描过去 24 小时的数据,无需等待夜间扫描。两者都需要与读取问题相同的权限;如果部署不提供 Diagnostics,两者都会拒绝执行。
问题可通过
write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"})
标记为已处理,或通过 …close 标记为无需处理;使用 …reopen 可将两者重新放回未解决列表。三者都需要相同的权限,并会返回问题移入的视图链接,因为已解决的问题不会再出现在默认页面上。故障是否已修复需要判断,因此只有在你提出要求时才应执行这些操作:助手不应在分诊时擅自整理列表。
随时间变化的指标。 project_metric 会将项目的一项指标按时间桶制成表格:trace、span 和 thread 数量、时长、错误率、成本、token 用量和反馈分数。它回答概览之后的后续问题:情况何时发生了变化。
list(entity_type="project_metric", project_name="demo", metric_type="trace_count")
list(
entity_type="project_metric",
project_name="demo",
metric_type="trace_error_rate",
since="14d",
interval="daily",
)
list(
entity_type="project_metric", project_name="demo", metric_type="span_count", breakdown="model"
) # one column per model
list(
entity_type="project_metric",
project_name="demo",
metric_type="span_duration",
breakdown="model",
series="p99",
) # the p99 of each model
行表示时间桶,而非记录,因此 page、size 和 sort 会被拒绝,而不是忽略。interval 可以是 hourly、daily、weekly 或 total;
如果省略,则会像 Metrics 标签页一样根据时间范围自动选择——不超过 3 天时按小时,最多 30 天时按天,超过 30 天时按周——因此无论范围多长,默认图表都只有几十行;按小时查看一个月(721 行)则需要明确请求。
since / until 的格式与其他地方相同,默认值为过去 7 天。filters 使用指标所属实体的字段,因此 span 指标会按 span 字段筛选。
breakdown 会按 tags、name、error_info、error_type、
model、provider、span_type、guardrail_name 或 metadata.<key> 拆分每个时间桶。并非每项指标都支持这些分组方式,其中有七项完全不支持;工具会在调用后端前识别并说明,并在有可回答相同问题的指标时指出该指标。有三类指标会一次返回多个序列(时长按 p50/p90/p99、反馈分数按名称、token 用量按键),而后端在分组时一次只能绘制其中一个,因此由 series= 选择:百分位数、分数名称或用量键。时长默认使用 p50,token 用量默认使用 total_tokens;所用值会回显在第一行。
空时间桶会被省略,并在下方统计数量,因此安静的月份只显示几行,而不是一列零值;没有 trace 的时间桶不会显示速率,而不是报告为零。
查询 schema("list.project_metric") 可查看指标表、时间间隔和各指标的分组矩阵。
项目的名称。 score_name 会列出项目中记录的反馈分数名称,online_rule 会列出项目配置的自动化规则评估器;大多数此类名称都来自这里。两者都是 read("project", …) 所包含的相同列表,提供完整分页结果,适用于概览中有上限的版本无法满足需求时。
list(entity_type="score_name", project_name="demo")
list(entity_type="online_rule", project_name="demo")
write
通用写入分发器。传入 operation + data,分发器会校验 payload、应用相应的 REST 动词,并返回后端响应。
操作:
| 操作 | 功能 |
|---|---|
trace.create | 记录单个 trace(或批量记录)。作为 span / score / comment 的父级。 |
trace.update | 完成或修改现有 trace。 |
span.create | 在现有 trace 上记录 span(或批量记录)。 |
score.create | 为 trace、span 或 thread 添加数值反馈分数。 |
comment.create | 为 trace、span 或 thread 添加自由文本评论。 |
prompt_version.save | 保存新的 prompt 版本(如果不存在,则按名称创建 prompt)。 |
dataset.create | 创建数据集 — type: "test_suite" 会将其设为评估测试套件。 |
dataset_item.upsert | 将条目写入或更新到数据集(始终使用 envelope 结构)。 |
experiment.create | 创建一个限定于数据集的实验。 |
experiment_item.create | 将 trace + dataset_item 行关联到实验。 |
thread.close | 关闭 thread(标记为非活动)。传入 thread_id 和项目。 |
thread.open | 重新打开已关闭的 thread。传入 thread_id 和项目。 |
agent_insights_job.enable | 为项目启用 Diagnostics(每日扫描,可安全重复调用)。 |
agent_insights_job.trigger | 立即运行 Diagnostics 扫描,覆盖过去 24 小时。 |
agent_insights_issue.resolve | 将 Diagnostics 问题标记为已处理(请先询问用户)。 |
agent_insights_issue.close | 将 Diagnostics 问题标记为无需处理(请先询问用户)。 |
agent_insights_issue.reopen | 将已解决或已关闭的 Diagnostics 问题重新放回未解决列表。 |
annotation_queue.create | 创建项目的标注队列,可选配自定义标注器视图。 |
annotation_queue.update | 修改标注队列;设置、替换或清除其标注器视图。 |
write(
operation="score.create",
data={
"target": "trace",
"target_id": "7f2e3c8a-…",
"name": "helpfulness",
"value": 0.9,
"reason": "great recovery",
},
)
schema
调用任何写入操作前,请先检查其确切的 JSON 结构和必填字段——当你不确定 data 应该是什么样时,这会很有帮助。返回 schema、OAuth scope 和一个通过校验的示例。纯查询,不会调用后端。
schema(operation="score.create")
schema(operation="prompt_version.save")
同一工具会针对 list.trace、list.span、list.thread 和
list.experiment 返回 list 工具中该实体的参考信息:每个可筛选字段及其类型和有效运算符、可排序字段、是否支持时间范围和全文搜索,以及两个筛选示例。
schema(operation="list.trace")
配置
这些配置用于本地服务器;每项设置都是一个环境变量。 Opik Cloud 上的托管服务器不接受这些设置。
身份 / 端点
| 变量 | 默认值 | 说明 |
|---|---|---|
OPIK_API_KEY | — | API 密钥,用于自托管 Comet,或用于未使用托管服务器的 Opik Cloud。开源版 Opik 不需要此项,除非部署添加了身份验证。 |
OPIK_WORKSPACE | unset | 工作区名称。在云端使用 API 密钥时,若未设置,则会发送 default,它会解析为你账户的默认工作区——如果你使用其他工作区,请显式设置,否则读取操作会悄无声息地从错误的工作区获取数据。使用 OAuth 时请留空(令牌中包含工作区信息);在本地/OSS 环境中也请留空(那里只有 default 这一个工作区)。 |
COMET_WORKSPACE | — | OPIK_WORKSPACE 的弃用别名(向后兼容)。如果两者都已设置,则以 OPIK_WORKSPACE 为准。 |
COMET_WORKSPACE_ID | unset | 可选的工作区 UUID。设置后会写入分析事件,并优先于解析出的工作区 UUID。通常不需要——OAuth 安装会自动从令牌中获取 UUID。 |
COMET_URL_OVERRIDE | https://www.comet.com | 设置为自托管 Comet 的主机,或设置为 https://dev.comet.com 以用于预发布环境。 |
OPIK_URL | 从 COMET_URL_OVERRIDE + /opik/api 派生 | 开源版 Opik 需要设置此项,因为它在 /api 提供 API(本地为 http://localhost:5173/api)。在 Comet 平台上,只有当 Opik 所在的主机/路径与 Comet UI 不同时才需要覆盖此项。 |
OPIK_DEFAULT_PROJECT_NAME | unset | 设置后,每个会话的 instructions 数据块会告知 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 | unset | OAuth 授权服务器 URL,会在 /.well-known/oauth-protected-resource (RFC 9728) 中公布,并用作 AS 发现探测的代理目标。MCP 宿主需要此项,才能通过 HTTP 启动 OAuth 流程。 |
OPIK_MCP_RESOURCE_URI | unset | 此服务器的规范公共 URI,会在受保护资源元数据中公布为 resource,并用于推导 WWW-Authenticate 提示。 |
OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S | 30 | opik-backend 的令牌内省返回“有效”结果后,在同一 OAuth 令牌的下一次请求再次进行内省之前,信任该结果的时长。此设置限制了逐请求验证带来的后端负载,以及过期令牌仍会被转发的时间窗口(该窗口也会在后端首次返回 401 时结束)。如果后端报告了令牌自身的 expires_at,则缓存时长不会超过该值。 |
OPIK_MCP_LOG_LEVEL | INFO | stderr 日志记录器的阈值。 |
选择传输方式
两种 bearer 格式,对应 HTTP 传输的两种契约。opik_mcp_at_… OAuth
访问令牌会在每次请求时通过 opik-backend 的令牌内省端点进行验证(结果会缓存,见 OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S);
过期或已撤销的令牌会收到带有 WWW-Authenticate: Bearer error="invalid_token" 的 HTTP 401 响应,MCP 宿主会据此触发静默的 refresh_token 授权。
Opik API 密钥不会在本地验证:它会原样转发给 opik-backend,由后者作为唯一的强制执行点。请根据部署方式选择传输方式:
| 场景 | 传输方式 |
|---|---|
| Opik Cloud | 无需运行任何服务:托管服务器 就是由 Comet 运行的 HTTP 服务器 |
| MCP 客户端和 Opik 位于同一台机器上(本地 OSS 安装) | stdio(推荐——最简单,无需端口或 OAuth 设置) |
| 本地 MCP 客户端 → 自托管 Opik | 使用部署所需环境变量的 stdio,或使用 OAuth 的 HTTP(OPIK_MCP_AS_URL 指向后端) |
| opik-mcp 与 opik-backend 位于同一边缘节点之后 | HTTP——bearer 令牌由后端逐请求验证 |
本地 OSS 安装注意事项:OSS 后端不会对请求进行身份验证,因此,位于其前面的 HTTP opik-mcp 与 OSS REST API 一样对外开放。在共享网络上,请保留默认的 127.0.0.1 绑定设置(并优先使用 stdio)。
遥测
| 变量 | 默认值 | 说明 |
|---|---|---|
OPIK_MCP_ANALYTICS_ENABLED | true | 设置为 false 可禁用所有非 Sentry 遥测。 |
| `OPIK_MCP_SENTRY_ENABLED | true | Set to false 可禁用所有 Sentry 遥测。 |
| ======= |
已知宿主限制
不同宿主允许单次工具调用运行的时长各不相同:
- Claude Code — 没有文档说明的工具调用超时限制。推荐使用。
- Cursor — 硬性超时为 60 秒,且进度不会重置计时 (上游问题)。
- MCP Inspector —
MAX_TOTAL_TIMEOUT限制总运行时长(默认 60 秒)。 对于耗时较长的操作,请在 Inspector UI 中调高此值。
如果调用卡住,请设置 OPIK_MCP_LOG_LEVEL=DEBUG 以记录完整请求日志。
故障排除
设置是否有效? 使用客户端配置中的环境变量启动服务器,并运行
--check:OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check。它会列出工作区及其检测到的项目,或说明需要修复的内容。服务器自身的错误也会说明需要更改什么,并提供相关文档页面的链接。
未读取 OPIK_API_KEY — 此变量没有传递到服务器进程。在 Claude Code / Cursor / VS Code 中,环境变量必须放在 MCP 服务器配置的 env 块中才会生效,而不是放在 shell 中;Codex 也只会转发 env_vars 中列出的名称。编辑配置后请启动新会话,因为客户端会在会话开始时读取配置。
请求被发送到开源版 Opik 的 /opik/api — COMET_URL_OVERRIDE 用于自托管 Comet 平台。开源版在 /api 提供 API:请改为设置 OPIK_URL=http://localhost:5173/api(或 https://<host>/api)。如果主机是本机,服务器会在启动时对此发出警告;--check 会返回“No Opik API at …”。
Cursor 调用在 60 秒时超时 — 这是 Cursor 的已知问题,与 opik-mcp 无关。可以缩小调用范围(使用更小的 size、缩短时间范围),或在没有硬性超时限制的 Claude Code 上运行相同操作。
未显示服务器、未打开登录页面、工作区错误、找不到 uvx。
这些问题已在文档的故障排除部分中说明。
uvx opik@latest mcp status 会列出所有已配置该服务器的客户端,以及其配置是否已发生偏差。
开发
git clone git@github.com:comet-ml/opik-mcp.git
cd opik-mcp
make install # uv sync --locked --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 --locked --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 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, analytics
├── tests/ ← pytest suites
├── scripts/ ← live-BE smoke + MCP-session smoke
├── legacy/typescript/ ← migration guide for the deprecated v2 TS server (source: tag `legacy-typescript-final`)
├── pyproject.toml
└── Makefile
获取帮助
- 如需报告错误或提出功能请求,请提交问题
- SDK / 后端文档请参阅 Opik 文档
- 如有疑问,请前往 Comet 社区 Slack
许可证
Apache-2.0。