Comet Opik MCP Server

chính thức

Truy vấn và phân tích nhật ký Opik, dấu vết, lời nhắc và tất cả dữ liệu đo từ xa khác từ các LLM của bạn bằng ngôn ngữ tự nhiên.

GitHub

211

Tài liệu

opik-mcp

Đang di chuyển từ npx opik-mcp cũ? Máy chủ TypeScript đã ngừng phát triển và sẽ ngừng hoạt động vào 2026-11-15. Thay npx -y opik-mcp bằng uvx opik-mcp@latest trong cấu hình máy khách MCP của bạn. Hướng dẫn đầy đủ: legacy/typescript/MIGRATION.md.

Máy chủ Model Context Protocol cho Opik + Ollie. Kết nối trực tiếp máy chủ AI của bạn (Claude Code, Cursor, VS Code Copilot, MCP Inspector) với không gian làm việc Opik — đọc vết, ghi điểm, lưu phiên bản prompt, và hỏi Ollie các câu hỏi điều tra, tất cả từ trong chat.

Được xây dựng cho các kỹ sư LLM đã chạy Opik và muốn điều khiển nó từ cùng một trợ lý AI mà họ dùng để viết mã.

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

Cài đặt

opik-mcp là một gói Python (yêu cầu Python 3.13+). Cách khuyến nghị để chạy nó là uvx, tải về và chạy phiên bản mới nhất được xuất bản theo yêu cầu — không cần cài đặt toàn cục, không cần quản lý virtualenv.

Cài đặt uv một lần:

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

Bạn sẽ cần hai thứ từ không gian làm việc Opik của mình:

OPIK_API_KEY — lấy nó từ comet.com/api/my/settings/.
OPIK_WORKSPACE — tên không gian làm việc của bạn (chữ thường, như xuất hiện trong URL). Ví dụ: https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Tùy chọn — mặc định là default (quy ước Opik SDK), phù hợp cho các bản cài đặt cục bộ/OSS; người dùng đám mây có không gian làm việc được đặt tên nên thiết lập nó. COMET_WORKSPACE được chấp nhận như một bí danh cũ.

Lưu ý trước khi phát hành: opik-mcp (Python) chưa được xuất bản lên PyPI. Cho đến khi bản phát hành PyPI đầu tiên ra mắt, hãy thay thế uvx opik-mcp trong bất kỳ đoạn mã nào bên dưới bằng: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE là tùy chọn. Bỏ qua dòng/khóa OPIK_WORKSPACE trong bất kỳ đoạn mã nào bên dưới và máy chủ sẽ sử dụng không gian làm việc default (phù hợp cho các bản cài đặt cục bộ/OSS). Chỉ thiết lập nó nếu bạn kết nối đến một không gian làm việc đám mây được đặt tên.

Claude Code

Thêm máy chủ bằng một lệnh:

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

Hoặc chỉnh sửa trực tiếp ~/.claude.json:

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

Khởi động lại Claude Code. Xác minh bằng /mcp — opik-mcp sẽ hiển thị là đã kết nối. Sau đó, trong chat, hãy hỏi: "liệt kê các dự án Opik của tôi" — Claude sẽ gọi công cụ list và bạn sẽ thấy các dự án trong không gian làm việc của mình.

Cursor

Chỉnh sửa ~/.cursor/mcp.json (toàn cục) hoặc .cursor/mcp.json (dự án), hoặc mở Cmd+Shift+J → Tính năng → Model Context Protocol:

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

Tải lại Cursor; chấm xanh bên cạnh opik-mcp trong bảng MCP xác nhận kết nối. Hỏi trong chat: "liệt kê các dự án Opik của tôi".

Cursor timeout 60 giây. Cursor áp đặt một giới hạn thời gian cứng cho lệnh gọi công cụ và không đặt lại khi có thông báo tiến trình. Các lượt ask_ollie dài sẽ thất bại trên Cursor. Xem Giới hạn máy chủ đã biết.

VS Code Copilot

.vscode/mcp.json trong không gian làm việc của bạn (hoặc JSON Cài đặt Người dùng):

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

Tải lại cửa sổ; chỉ báo MCP của Copilot Chat hiển thị opik-mcp khi máy chủ có thể truy cập được. Hỏi trong chat: "liệt kê các dự án Opik của tôi".

MCP Inspector (kiểm thử thủ công)

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

Opik tự lưu trữ

Thêm COMET_URL_OVERRIDE (và OPIK_URL nếu Opik nằm ở đường dẫn không mặc định) vào cùng khối env trong cấu hình máy chủ của bạn:

{
  "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 và run_experiment chỉ khả dụng trên Comet Cloud — trên bản tự lưu trữ, các lệnh gọi đó sẽ thất bại khi gửi đi, vì vậy hãy sử dụng trực tiếp read / list / write. Thiết lập OPIK_MCP_ANALYTICS_SOURCE="" sẽ loại bỏ nhãn nguồn Comet đám mây trên các sự kiện đo lường từ xa của bạn.

Công cụ

opik-mcp cung cấp một bề mặt nhỏ gọn, hướng kết quả — sáu công cụ bao phủ toàn bộ vòng đời (đọc → chú thích → tuyển chọn → tạo mới → lặp lại).

Công cụ	Mục đích
`read`	Đọc phổ quát theo id / tên / URI `opik://`
`list`	Danh sách phổ quát với bộ lọc tên tùy chọn + phân trang
`ask_ollie`	Điều tra / tổng hợp thông qua trợ lý trong sản phẩm Opik
`write`	Ghi phổ quát — ghi vết/nhịp, chấm điểm, bình luận, lưu prompt, quản lý bộ kiểm thử & thí nghiệm
`schema`	Xem xét lược đồ thao tác ghi (được LLM sử dụng để tạo payload hợp lệ)
`run_experiment`	Chạy một thí nghiệm đánh giá từ đầu đến cuối thông qua Ollie

`read`

Một công cụ cho bất kỳ câu hỏi "hiển thị X" nào. Nhận một entity_type cộng với một id (UUID hoặc, đối với các loại có thể đặt tên, một tên) hoặc một URI opik:// đầy đủ. Các lần đọc tổng hợp (trace, prompt) bao gồm các phần tử con của chúng để một lệnh gọi duy nhất trả về bức tranh đầy đủ.

Các thực thể được hỗ trợ: project, trace, span, test_suite, experiment, prompt. Tra cứu dựa trên tên khả dụng cho project, experiment, prompt, test_suite (chậm hơn — hai lệnh gọi API — và có thể trả về nhiều kết quả khớp).

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

`list`

Duyệt một bộ sưu tập với bộ lọc tên tùy chọn và phân trang. Các loại có phạm vi dự án (trace, test_suite_item, prompt_version) yêu cầu UUID cha của chúng.

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`

Dành cho các câu hỏi điều tra, tổng hợp chéo thực thể, hoặc bất cứ điều gì cần chuyên môn về miền Opik. Ollie có quyền truy cập đọc trực tiếp vào không gian làm việc của bạn và có thể thực hiện ghi (điểm, bình luận, mục bộ kiểm thử, phiên bản prompt) giữa luồng khi được yêu cầu.

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.")

Trả về văn bản cuối cùng của trợ lý cộng với một thread_id. Truyền lại nó trong các lần theo dõi để bảo toàn ngữ cảnh — Ollie không có bộ nhớ xuyên suốt các luồng.

Chế độ YOLO (mặc định). Các thao tác ghi mà Ollie thực hiện giữa luồng sẽ thực thi mà không cần xác nhận từng hành động. Mỗi lần tự động phê duyệt được ghi lại dưới dạng một hàng JSON kiểm toán trên trình ghi nhật ký Python opik_mcp.audit. Để yêu cầu xác nhận thay vào đó, hãy đặt OPIK_MCP_AUTO_APPROVE=disabled — các yêu cầu xác nhận của Ollie sau đó sẽ hiển thị dưới dạng lỗi có kiểu mà bạn có thể phát hành lại thủ công.

Chỉ khả dụng trên Comet Cloud.

`write`

Bộ điều phối ghi phổ quát. Truyền operation + data và bộ điều phối xác thực payload, áp dụng động từ REST phù hợp, và trả về phản hồi từ backend.

Các thao tác:

Thao tác	Chức năng
`trace.create`	Ghi một vết đơn (hoặc một lô). Cha cho các nhịp / điểm / bình luận.
`trace.update`	Hoàn thiện hoặc sửa đổi một vết hiện có.
`span.create`	Ghi một nhịp trên một vết hiện có (hoặc một lô).
`score.create`	Đính kèm điểm phản hồi số vào một vết, nhịp, hoặc luồng.
`comment.create`	Đính kèm bình luận văn bản tự do vào một vết, nhịp, hoặc luồng.
`prompt_version.save`	Lưu một phiên bản prompt mới (tạo prompt theo tên nếu thiếu).
`test_suite.create`	Tạo một bộ kiểm thử đánh giá.
`test_suite_item.upsert`	Upsert các mục vào một bộ kiểm thử (luôn ở dạng bao).
`experiment.create`	Tạo một thí nghiệm trong phạm vi một bộ kiểm thử.
`experiment_item.create`	Đính kèm các hàng vết + dataset_item vào một thí nghiệm.

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

`schema`

Xem xét hình dạng JSON chính xác và các trường bắt buộc của bất kỳ thao tác ghi nào trước khi bạn gọi nó — hữu ích khi bạn không chắc data nên trông như thế nào. Trả về lược đồ, phạm vi OAuth, và một ví dụ đã xác thực. Tra cứu thuần túy, không gọi backend.

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

`run_experiment`

Chạy một thí nghiệm đánh giá từ đầu đến cuối thông qua Ollie. Nhận một dict experiment_config duy nhất phản ánh hình dạng thí nghiệm của Opik (prompt, bộ kiểm thử, bộ chấm điểm); Ollie thực thi lần chạy và ghi kết quả trở lại dưới dạng một thí nghiệm Opik.

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

Chỉ khả dụng trên Comet Cloud.

Cấu hình

Mọi thiết lập là một biến môi trường. Các biến bắt buộc được in đậm.

Định danh / điểm cuối

Biến	Mặc định	Ghi chú
`OPIK_API_KEY`	—	Bắt buộc cho `ask_ollie` và bất kỳ đọc/ghi được xác thực nào.
`OPIK_WORKSPACE`	`default`	Tên không gian làm việc. Tùy chọn — mặc định về `default` (quy ước Opik SDK). Người dùng đám mây có không gian làm việc được đặt tên nên thiết lập nó.
`COMET_WORKSPACE`	—	Bí danh cũ cho `OPIK_WORKSPACE` (tương thích ngược). `OPIK_WORKSPACE` thắng nếu cả hai được đặt.
`COMET_WORKSPACE_ID`	—	UUID không gian làm việc tùy chọn. Được đóng dấu vào các sự kiện phân tích khi được đặt để BI có thể nối trên một id ổn định thay vì tên không gian làm việc (có thể thay đổi).
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Đặt thành máy chủ Comet tự lưu trữ của bạn, hoặc `https://dev.comet.com` cho staging.
`OPIK_URL`	suy ra từ `COMET_URL_OVERRIDE` + `/opik/api`	Ghi đè chỉ khi Opik nằm trên một máy chủ/đường dẫn khác với giao diện Comet.
`OPIK_DEFAULT_PROJECT_NAME`	bỏ trống	Khi được đặt, blob `instructions` mỗi phiên bảo LLM truyền giá trị này như `project_name` trên mọi lệnh gọi công cụ trừ khi người dùng chỉ định một dự án khác.

Máy chủ / vận chuyển

Biến	Mặc định	Ghi chú
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` cho máy chủ khởi chạy, `streamable-http` để lắng nghe trên một cổng.
`OPIK_MCP_HOST`	`127.0.0.1`	Máy chủ liên kết uvicorn (chỉ `streamable-http`).
`OPIK_MCP_PORT`	`8080`	Cổng liên kết uvicorn (chỉ `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	`true` để bật `--reload` của uvicorn (chỉ dành cho dev).
`OPIK_MCP_AS_URL`	bỏ trống	URL Máy chủ Ủy quyền OAuth, được quảng bá trong `/.well-known/oauth-protected-resource` (RFC 9728) và được sử dụng làm mục tiêu proxy cho các thăm dò khám phá AS. Bắt buộc để các máy chủ MCP khởi động vũ điệu OAuth qua HTTP.
`OPIK_MCP_RESOURCE_URI`	bỏ trống	URI công khai chính tắc của máy chủ này, được quảng bá là `resource` trong siêu dữ liệu tài nguyên được bảo vệ và được sử dụng để suy ra gợi ý `WWW-Authenticate`.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Ngưỡng trình ghi nhật ký stderr.

Chọn phương thức vận chuyển

opik-mcp thực hiện không xác thực cục bộ trên vận chuyển HTTP: bất kỳ Authorization: Bearer … hợp lệ nào (một khóa API Opik hoặc một mã thông báo truy cập OAuth opik_mcp_at_…) đều được chuyển tiếp nguyên văn đến opik-backend, đây là điểm duy nhất thực thi xác thực. Chọn phương thức vận chuyển theo hình dạng triển khai:

Kịch bản	Vận chuyển
MCP client và Opik trên cùng một máy (cài đặt OSS cục bộ)	stdio (khuyến nghị — đơn giản nhất, không cổng, không cần thiết lập OAuth)
MCP client cục bộ → Opik từ xa (Comet cloud / tự lưu trữ)	stdio với `OPIK_API_KEY`, hoặc HTTP với OAuth (`OPIK_MCP_AS_URL` trỏ đến backend)
opik-mcp được lưu trữ sau cùng một biên với opik-backend	HTTP — bearer được backend xác thực cho mỗi yêu cầu

Lưu ý cho các bản cài đặt OSS cục bộ: backend OSS không xác thực yêu cầu, vì vậy một opik-mcp HTTP trước nó sẽ mở như chính API REST OSS. Giữ liên kết 127.0.0.1 mặc định (và ưu tiên stdio) trên các mạng chia sẻ.

Ollie / các lệnh gọi dài

Biến	Mặc định	Ghi chú
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` để yêu cầu phê duyệt từng hành động trước khi các thao tác ghi giữa luồng của Ollie tiến hành. Trên các máy chủ quảng bá khả năng MCP `elicitation`, người dùng thấy một lời nhắc có/không; trên các máy chủ đơn giản hơn, yêu cầu hiển thị dưới dạng lỗi có kiểu mà bạn có thể phát hành lại thủ công.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Thời gian lời nhắc xác nhận giữa luồng của Ollie có thể chờ người dùng trước khi bị coi là hủy. `0` vô hiệu hóa giới hạn (chỉ gỡ lỗi).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Giới hạn thăm dò khởi động lạnh pod Ollie.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Khoảng thời gian thăm dò khởi động lạnh.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Nhịp giám sát — phát ra một tick `notifications/progress` khi pod im lặng, giữ cho các timeout của máy chủ không bị kích hoạt.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Trần cứng cho sự im lặng của pod trước khi `ask_ollie` hủy bỏ. `0` vô hiệu hóa (chỉ gỡ lỗi).

Đo lường từ xa

Các sự kiện sử dụng ẩn danh (chỉ loại sự kiện + thời gian — không có nội dung truy vấn). Một bản tóm tắt SHA-256 của khóa API của bạn được bao gồm để hỗ trợ có thể tìm thấy tài khoản của bạn; khóa thô không bao giờ rời khỏi tiến trình. Từ chối: OPIK_MCP_ANALYTICS_ENABLED=false.

Biến	Mặc định	Ghi chú
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Đặt thành `false` để tắt toàn bộ telemetry.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Ghi đè cho môi trường staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Gắn thẻ trên mọi sự kiện (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Receiver dùng giá trị này để đánh dấu `on_prem=False`. Các bản cài đặt on-prem nên ghi đè thành `""` hoặc tên miền riêng.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	Thời gian chờ kết nối HTTP.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	Thời gian chờ tổng của yêu cầu HTTP.

Giới hạn đã biết của host

Đặc tả MCP cho phép host đặt lại thời gian chờ gọi công cụ trên notifications/progress — opik-mcp phát ra một heartbeat cho mỗi sự kiện SSE của Ollie cộng với một watchdog 15 giây. Thực tế không đồng nhất:

Claude Code — không có thời gian chờ gọi công cụ được ghi nhận; heartbeat giữ cho lệnh gọi tồn tại cho đến message_end. Được khuyến nghị.
Cursor — giới hạn cứng 60 giây và không đặt lại khi có tiến trình (lỗi upstream). Các lượt Ollie dài sẽ thất bại. Hãy giữ các truy vấn ask_ollie tập trung.
MCP Inspector — MAX_TOTAL_TIMEOUT giới hạn tổng thời lượng (mặc định 60 giây). Tăng giá trị này trong giao diện Inspector cho các thao tác dài.

Nếu một lệnh gọi bị treo, hãy đặt OPIK_MCP_LOG_LEVEL=DEBUG — các lỗi heartbeat (thường là do host ngắt kết nối) được ghi lại trên opik_mcp.ask_ollie ở mức debug.

Khắc phục sự cố

OPIK_API_KEY is required to use ask_ollie — biến không đến được tiến trình máy chủ. Trong Claude Code / Cursor / VS Code, biến môi trường chỉ áp dụng khi nằm trong khối env của cấu hình máy chủ MCP, không phải shell của bạn. Khởi động lại host sau khi chỉnh sửa.

ask_ollie trả về "pod not ready" sau 2 phút — pod Ollie khởi động nguội vượt quá OPIK_MCP_POD_READY_TIMEOUT_S. Thử lại — lệnh gọi thứ hai thường sẽ đến một pod đã ấm.

ask_ollie / run_experiment thất bại với lỗi dispatch trên Opik tự lưu trữ — những công cụ đó chỉ khả dụng trên Comet Cloud. Sử dụng trực tiếp read / list / write trên bản tự lưu trữ.

Lệnh gọi Cursor hết thời gian chờ ở 60 giây — lỗi đã biết của Cursor, không phải opik-mcp. Hoặc rút ngắn truy vấn Ollie, hoặc chạy cùng thao tác đó trên Claude Code vốn không có giới hạn cứng.

Phát triển

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

Các mục tiêu phổ biến:

Mục tiêu	Chức năng
`make install`	`uv sync --extra dev`
`make run`	Chạy máy chủ MCP (stdio theo mặc định).
`make run-dev`	Chạy với ghi log DEBUG + uvicorn `--reload`.
`make dev`	Chạy qua `mcp dev` (trình bao bọc chế độ phát triển Inspector).
`make inspect`	Khởi chạy MCP Inspector với một máy chủ đang chạy.
`make test`	`uv run pytest -q`.
`make test-live`	End-to-end trực tiếp với `dev.comet.com` (đặt `OPIK_API_KEY` + `OPIK_WORKSPACE`).
`make lint`	`ruff check` + kiểm tra định dạng.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Bố cục kho lưu trữ:

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

Nhận trợ giúp

Mở một issue cho lỗi và yêu cầu tính năng
Tài liệu Opik cho tài liệu SDK / backend
Cộng đồng Comet Slack cho các câu hỏi

Đang nâng cấp từ v2? Máy chủ TypeScript cũ vẫn được xuất bản trên npm với tên opik-mcp@^2 (npx -y opik-mcp); mã nguồn được bảo tồn trong legacy/typescript/. Xem legacy/typescript/DEPRECATED.md để biết chính sách hỗ trợ.

Giấy phép

Apache-2.0.