Comet Opik

Máy chủ Opik MCP

Máy chủ Giao thức Ngữ cảnh Mô hình (MCP) chính thức cho Opik, nền tảng quan sát và đánh giá LLM mã nguồn mở, được xây dựng bởi Comet. 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ào không gian làm việc Opik của bạn: đọc trace, ghi điểm, lưu phiên bản prompt, và hỏi Ollie, trợ lý AI tích hợp trong sản phẩm của Opik, 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ừ chính trợ lý AI mà họ dùng để viết mã.

Đang chuyển đổi từ npx opik-mcp cũ? Máy chủ TypeScript đã ngừng hỗ trợ 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.

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, nó tải và chạy phiên bản mới nhất đã phát hành theo yêu cầu — không cần cài đặt toàn cục, không cần xử 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 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 của Opik SDK), đúng cho các bản cài đặt local/OSS; người dùng cloud với không gian làm việc có tên nên đặt nó. COMET_WORKSPACE được chấp nhận như một bí danh đã ngừng hỗ trợ.

Ghi chú trước 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 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 (đúng cho các bản cài đặt local/OSS). Chỉ đặt nó nếu bạn kết nối với một không gian làm việc cloud có 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 ~/.claude.json trực tiếp:

{
  "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ẽ xuất hiện như đã 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 của 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 → Features → 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".

Giới hạn thời gian chờ 60 giây của Cursor. Cursor áp dụng thời gian chờ cứng cho lệnh gọi công cụ không được đặ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. 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 ở một đườ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 phân phối, vì vậy hãy sử dụng read / list / write trực tiếp. Đặt OPIK_MCP_ANALYTICS_SOURCE="" sẽ loại bỏ bản cài đặt của bạn khỏi nhãn nguồn cloud-Comet trên các sự kiện telemetry.

---

Công cụ

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

Công cụ	Mục đích
read	Đọc phổ quát theo id / tên / URI opik://
list	Liệt kê 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 qua trợ lý tích hợp trong sản phẩm Opik
write	Ghi phổ quát — ghi trace/span, chấm điểm, bình luận, lưu prompt, quản lý bộ kiểm thử & thí nghiệm
schema	Kiểm tra nội bộ các lược đồ thao tác ghi (được LLM sử dụng để xây dựng payload hợp lệ)
run_experiment	Chạy một thí nghiệm đánh giá từ đầu đến cuối qua Ollie

read

Một công cụ cho bất kỳ câu hỏi "hiển thị X cho tôi". Nhận một entity_type cùng với một id (UUID hoặc, đối với các loại có tên, một tên) hoặc một URI opik:// đầy đủ. Các thao tác đọc tổng hợp (trace, prompt) nhúng 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 theo 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 và phân trang tùy chọn. 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 đa 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 đọ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 các thao tác 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 để giữ ngữ cảnh — Ollie không có bộ nhớ giữa 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 thực thi mà không có xác nhận theo từng hành động. Mỗi lần tự phê duyệt được ghi lại dưới dạng một hàng kiểm toán JSON trên logger 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 đó xuất hiện dưới dạng lỗi có kiểu mà bạn có thể gửi lại thủ công.

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

write

Bộ phân phối ghi phổ quát. Truyền operation + data và bộ phân 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 trace duy nhất (hoặc một lô). Cha cho spans / điểm / bình luận.
trace.update	Hoàn tất hoặc sửa đổi một trace hiện có.
span.create	Ghi một span trên một trace hiện có (hoặc một lô).
score.create	Đính kèm điểm phản hồi dạng số vào một trace, span, hoặc luồng.
comment.create	Đính kèm bình luận dạng văn bản tự do vào một trace, span, 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 envelope).
experiment.create	Tạo một thí nghiệm có phạm vi trong một bộ kiểm thử.
experiment_item.create	Đính kèm các hàng trace + 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

Kiểm tra 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 có lệnh 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 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 hiện 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 cài đặt đều là một biến môi trường. Các biến bắt buộc được in đậm.

Danh tính / đ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ỳ thao tác đọ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 — dự phòng về default (quy ước Opik SDK). Người dùng cloud với không gian làm việc có tên nên đặt nó.
COMET_WORKSPACE	—	Bí danh đã ngừng hỗ trợ 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	chưa đặt	Khi được đặt, khối instructions theo phiên cho LLM biết để truyền giá trị này làm 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ủ / truyền tải

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ủ bind của uvicorn (chỉ streamable-http).
OPIK_MCP_PORT	8080	Cổng bind của uvicorn (chỉ streamable-http).
OPIK_MCP_RELOAD	false	true để bật --reload của uvicorn (chỉ dev).
OPIK_MCP_AS_URL	chưa đặt	URL Máy chủ Ủy quyền OAuth, được quảng cáo 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 quy trình OAuth qua HTTP.
OPIK_MCP_RESOURCE_URI	chưa đặt	URI công khai chuẩn của máy chủ này, được quảng cáo 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 logger stderr.

Chọn một phương thức truyền tải

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

Kịch bản	Truyền tải
Máy khách MCP và Opik trên cùng một máy (bản cài đặt OSS cục bộ)	stdio (khuyến nghị — đơn giản nhất, không cần cổng, không cần thiết lập OAuth)
Máy khách MCP cục bộ → Opik từ xa (cloud Comet / 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ữ phía sau cùng một edge với opik-backend	HTTP — các bearer được backend xác thực theo từng 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 các yêu cầu, vì vậy một opik-mcp HTTP phía trước nó cũng mở như chính API REST OSS. Giữ bind 127.0.0.1 mặc định (và ưu tiên stdio) trên các mạng dùng chung.

Ollie / 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 theo 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 cáo khả năng MCP elicitation, người dùng thấy lời nhắc có/không; trên các máy chủ kém thông minh hơn, yêu cầu xuất hiện dưới dạng lỗi có kiểu mà bạn có thể gửi 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 nguội pod Ollie.
OPIK_MCP_POD_READY_INTERVAL_S	2	Khoảng thời gian thăm dò khởi động nguội.
OPIK_MCP_HEARTBEAT_INTERVAL_S	15.0	Nhịp watchdog — phát ra một tick notifications/progress khi pod im lặng, giữ cho các thời gian chờ của máy chủ không bị vượt quá.
OPIK_MCP_STREAM_IDLE_TIMEOUT_S	300.0	Trần cứng về 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).

Telemetry

Sự kiện sử dụng ẩn danh (chỉ loại sự kiện và thời gian — không có nội dung truy vấn). Một bản băm 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 tất cả 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	Bộ thu sử 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 của họ.
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 yêu cầu HTTP.

---

Giới hạn máy chủ đã biết

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

• Claude Code — không có thời gian chờ gọi công cụ được ghi lại; nhịp tim giữ cho cuộc gọi sống cho đến khi message_end. Được khuyến nghị.
• Cursor — thời gian chờ 60 giây cứng 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. 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ị đó trong giao diện Inspector cho các thao tác dài.

Nếu một cuộc gọi bị kẹt, hãy đặt OPIK_MCP_LOG_LEVEL=DEBUG — các lỗi nhịp tim (thường là máy chủ 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, các biến môi trường chỉ áp dụng khi bên 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 máy chủ sau khi chỉnh sửa.

ask_ollie trả về "pod not ready" sau 2 phút — quá trình khởi động nguội của pod Ollie vượt quá OPIK_MCP_POD_READY_TIMEOUT_S. Thử lại — cuộc gọi thứ hai thường chạm vào một pod ấm.

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

Cuộc gọi Cursor hết thời gian ở 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 thao tác tương tự trên Claude Code, nơi không có giới hạn cứng.

---

Phát triển

git clone git@github.com: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ế độ dev của Inspector).
make inspect	Khởi chạy MCP Inspector chống lạ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 chống lạ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
• Slack cộng đồng Comet cho các câu hỏi

---

Nâng cấp từ v2? Máy chủ TypeScript kế thừa vẫn được phát hành trên npm dưới dạng opik-mcp@^2 (npx -y opik-mcp); mã nguồn được giữ nguyên dưới legacy/typescript/. Xem legacy/typescript/DEPRECATED.md cho chính sách hỗ trợ.

---

Giấy phép

Apache-2.0.