Comet Opik

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

226

Bạn có thể làm gì với Comet Opik MCP?

Truy vấn trace theo dự án — Hỏi xem hôm nay có những trace nào trong một dự án bị lỗi, với bộ lọc theo thông tin lỗi, thời lượng hoặc mức sử dụng token.
Đọc mọi thực thể Opik — Lấy thông tin dự án, trace, span, tập dữ liệu, thử nghiệm, prompt, thread hoặc sự cố Diagnostics theo id, tên hoặc URI opik://.
Ghi điểm và nhận xét — Chấm điểm trace theo một chỉ số phản hồi kèm lý do, hoặc thêm nhận xét thông qua công cụ ghi.
Lưu phiên bản prompt — Soạn và lưu các phiên bản prompt mới cùng với tập dữ liệu và thử nghiệm.
Kiểm tra schema ghi — Yêu cầu schema của một thao tác ghi để tạo payload hợp lệ trước khi gửi.
Kiểm tra tình trạng dự án — Đọc thông tin dự án để xem số lượng trace, tỷ lệ lỗi, thời lượng trung bình và tổng chi phí trong 7 ngày qua.

Tài liệu

Máy chủ MCP Opik

Máy chủ Model Context Protocol (MCP) chính thức cho Opik, nền tảng mã nguồn mở về khả năng quan sát và đánh giá LLM, do Comet phát triển. Kết nối trực tiếp máy chủ AI của bạn (Claude Code, Cursor, VS Code Copilot, Codex, opencode hoặc bất kỳ ứng dụng khách MCP nào) với không gian làm việc Opik: đọc trace, ghi điểm số và lưu phiên bản prompt ngay trong cuộc trò chuyện.

Dành cho các kỹ sư LLM đã sử dụng Opik và muốn điều khiển Opik từ chính trợ lý AI mà họ dùng để viết mã.

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

Bắt đầu nhanh

Chỉ với một lệnh, bạn có thể thiết lập Opik trong các ứng dụng AI trên máy, bao gồm Claude Code. Lệnh này tìm Opik của bạn (Opik đã lưu trong ~/.opik.config, một phiên bản đang chạy trên localhost hoặc hỏi bạn chọn), đăng ký máy chủ MCP, cài đặt gói kỹ năng Opik và kiểm tra kết nối. Với Opik Cloud, bạn không cần xử lý khóa API: ứng dụng khách sẽ đăng nhập qua trình duyệt. Cần có uv và không cần Opik SDK:

uvx opik@latest mcp configure

Nếu không dùng terminal, chẳng hạn khi chạy từ tác nhân lập trình hoặc tập lệnh, hãy chỉ định ứng dụng khách:

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-client cũng nhận codex, cursor, vscode và opencode. Khi chạy theo cách này, lệnh sử dụng Opik đã lưu trong ~/.opik.config, bao gồm cả khóa API, hoặc Opik đang phản hồi trên localhost; nếu không tìm thấy, lệnh sẽ dừng và yêu cầu --deployment.

Khi được yêu cầu “install opik mcp”, tác nhân lập trình sẽ lấy đầy đủ các bước, bao gồm cả nội dung cần hỏi người dùng, từ uvx opik-mcp@latest --help. Các bước này giống với mục Cài đặt bằng tác nhân lập trình bên dưới.

Đăng ký máy chủ thủ công bằng các lệnh ứng dụng khách trong mục Thiết lập thủ công sẽ bỏ qua bước kiểm tra bạn đang dùng Opik nào và không cài đặt gói kỹ năng, vì vậy cách này dành cho các ứng dụng khách không được trình cài đặt hỗ trợ.

Opik của bạn	Máy chủ	Giao thức truyền tải	Đăng nhập
Opik Cloud (`www.comet.com`)	máy chủ được lưu trữ, do Comet vận hành	Streamable HTTP	qua trình duyệt (OAuth); không cần khóa API
Comet tự lưu trữ, Opik mã nguồn mở	máy chủ cục bộ, gói này	stdio	biến môi trường; chỉ cần khóa API nếu triển khai yêu cầu

Ứng dụng khách tải máy chủ MCP khi bắt đầu phiên, vì vậy hãy bắt đầu phiên mới sau khi thiết lập.

Hướng dẫn thiết lập, khắc phục sự cố và câu hỏi thường gặp: comet.com/docs/opik/mcp-server.

Opik Cloud: máy chủ được lưu trữ

Comet vận hành máy chủ tại https://www.comet.com/opik/api/v1/mcp. Ứng dụng khách kết nối qua HTTP và mở trình duyệt để đăng nhập lần đầu. Không cần cài đặt, không cần khóa API và không cần thiết lập không gian làm việc: máy chủ hoạt động trong không gian làm việc bạn chọn khi đăng nhập. Sau khi thêm máy chủ, hãy bắt đầu phiên mới và hỏi: “list my Opik projects”.

Lệnh Bắt đầu nhanh thiết lập máy chủ cho Claude Code, Codex, Cursor, VS Code Copilot và opencode, đồng thời cài đặt gói kỹ năng. Trong Claude Code, plugin thực hiện việc này chỉ bằng một lệnh. Các nút bên dưới thêm máy chủ vào Cursor hoặc VS Code chỉ với một cú nhấp; các cách đăng ký thủ công khác nằm trong mục Thiết lập thủ công.

Plugin Claude Code

Plugin opik cài đặt các kỹ năng Opik và đăng ký máy chủ MCP được lưu trữ cho Opik Cloud:

/plugin install opik --marketplace comet-ml/opik-mcp

Với Claude Code phiên bản cũ hơn 2.1.275, hãy chạy /plugin marketplace add comet-ml/opik-mcp, sau đó chạy /plugin install opik@opik. Các kỹ năng được tải dưới dạng opik:<skill>, chẳng hạn như opik:opik-instrument, và /mcp hiển thị máy chủ dưới tên plugin:opik:opik-cloud. Đây là máy chủ của Opik Cloud. Hãy bắt đầu phiên mới, sau đó đăng nhập từ /mcp → Authenticate. Với Comet tự lưu trữ có chạy máy chủ MCP OAuth, hãy thêm máy chủ bằng claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp; với mọi phiên bản Opik tự lưu trữ hoặc mã nguồn mở khác, hãy dùng lệnh Bắt đầu nhanh. Sau đó tắt plugin:opik:opik-cloud trong /mcp. Claude Code không tự cập nhật plugin từ marketplace này: hãy chạy /plugin marketplace update opik, sau đó /plugin update opik@opik, hoặc bật tự động cập nhật marketplace trong /plugin. Marketplace này cung cấp main, có thể mới hơn bản phát hành gần nhất. Bản cập nhật chỉ được cung cấp khi phiên bản plugin thay đổi, tức là ở mỗi lần phát hành.

Nếu trước đây bạn đã thêm opik-mcp tại cùng URL, Claude Code sẽ giữ bản của bạn và bỏ qua bản của plugin. Nếu bản của bạn là một máy chủ khác, chẳng hạn máy chủ cục bộ uvx opik-mcp, cả hai sẽ được tải: chạy claude mcp remove opik-mcp để chỉ giữ lại bản của plugin. Các kỹ năng trong gói kỹ năng cũng được tải cùng với bản sao của plugin; xóa chúng bằng npx skills remove --global --agent claude-code, lệnh này sẽ hỏi bạn muốn xóa những kỹ năng nào.

Opik tự lưu trữ và mã nguồn mở: máy chủ cục bộ

opik-mcp chạy trên máy của bạn: ứng dụng khách khởi chạy nó bằng uvx opik-mcp và giao tiếp qua stdio. Lệnh Bắt đầu nhanh thiết lập máy chủ từ ~/.opik.config của bạn hoặc từ Opik cục bộ; để đăng ký thủ công, xem mục Thiết lập thủ công. Chỉ cần cài uv một lần; lần đầu sử dụng, công cụ này sẽ tải gói và Python 3.13 nếu cần:

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

uvx opik-mcp dùng lại bản sao uv đã lưu trong bộ nhớ đệm nên khởi động nhanh; uv cache clean opik-mcp khiến lần khởi động tiếp theo tải bản phát hành mới nhất. uvx opik-mcp@latest truy vấn PyPI mỗi lần khởi động, làm tăng thời gian khoảng một giây rưỡi. Codex chờ mcp_optional_startup_grace_ms (mặc định là 1 s) để các máy chủ khởi động trước khi tạo danh sách công cụ đầu tiên, vì vậy nếu khởi động chậm, các công cụ có thể không xuất hiện trong lượt đầu tiên. Các lệnh chạy một lần trong README này (opik mcp configure, opik mcp status, --help, --check) có kèm @latest, nên không bao giờ chạy bản sao mà uv đã lưu trong bộ nhớ đệm từ nhiều tháng trước.

Các biến môi trường trỏ máy chủ đến Opik của bạn:

Opik của bạn	Biến môi trường
Opik mã nguồn mở trên máy này	`OPIK_URL=http://localhost:5173/api`
Opik mã nguồn mở trên máy chủ	`OPIK_URL=https://<host>/api`, và chỉ thêm `OPIK_API_KEY` nếu triển khai có bật xác thực
Nền tảng Comet tự lưu trữ (giao diện Opik nằm tại `https://<host>/opik`)	`COMET_URL_OVERRIDE=https://<host>`, `OPIK_WORKSPACE`, `OPIK_API_KEY`

Opik mã nguồn mở cung cấp API tại /api và chỉ có một không gian làm việc, default, nên không cần OPIK_WORKSPACE. COMET_URL_OVERRIDE sẽ trỏ máy chủ đến /opik/api, nơi Opik mã nguồn mở không cung cấp.
Comet tự lưu trữ có các không gian làm việc được đặt tên. Đặt OPIK_WORKSPACE thành phần nằm sau /opik/ trong URL Opik của bạn; nếu bỏ qua, các thao tác đọc sẽ dùng không gian làm việc mặc định của tài khoản mà không báo lỗi.
Comet tự lưu trữ có chạy máy chủ MCP OAuth (mặc định tắt) có thể dùng luồng lưu trữ tại https://<host>/opik/api/v1/mcp.
Thay mọi giá trị bằng giá trị thực. Máy chủ từ chối các tên không gian làm việc giữ nguyên giá trị giữ chỗ như <your-workspace> hoặc ${input:OPIK_WORKSPACE}; URL giữ chỗ sẽ được gửi nguyên trạng và không kết nối được.
OPIK_MCP_ANALYTICS_SOURCE="" trong khối env giúp bản cài đặt tự lưu trữ không gắn nhãn nguồn cloud-Comet cho các sự kiện telemetry.

Trước khi thêm máy chủ vào ứng dụng khách, hãy kiểm tra cài đặt: chạy máy chủ với cùng môi trường và --check. Lệnh này gọi Opik một lần, in ra không gian làm việc và số lượng dự án tìm thấy, hoặc hướng dẫn cần sửa gì kèm liên kết đến tài liệu, rồi thoát với mã 0 hoặc 1. Ứng dụng khách không thể cho bạn biết điều này trước khi bắt đầu phiên mới: Claude Code hiển thị trạng thái Connected ngay cả khi khóa sai, còn Codex không khởi chạy gì cho đến lúc đó.

OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check

Sau đó đăng ký máy chủ với ứng dụng khách của bạn: máy chủ cục bộ, thiết lập thủ công.

Cài đặt bằng tác nhân lập trình

Dành cho tác nhân AI được yêu cầu cài đặt máy chủ, chẳng hạn như “install opik mcp”. Mục tiêu là đăng ký máy chủ cho Opik của người dùng, cài đặt gói kỹ năng Opik và đăng nhập cho người dùng. Hãy xác định Opik nào đang được dùng trên máy này và chỉ hỏi người dùng những điều bạn không thể tự xác định: mỗi tin nhắn chỉ hỏi một câu, chờ câu trả lời rồi mới hỏi câu tiếp theo. Trình cài đặt ở bước 3 thực hiện toàn bộ thiết lập trong một lần chạy, vì vậy hãy hoàn tất bước 1 và 2 trước khi chạy. uvx opik-mcp@latest --help sẽ in các bước này.

Kiểm tra những gì đã có.
```
uvx opik@latest mcp status
```
Lệnh này hiển thị Opik được lưu trong ~/.opik.config (URL và không gian làm việc, không bao giờ hiển thị khóa) cùng các ứng dụng khách đã có máy chủ. Trong Claude Code, hãy chạy thêm claude mcp list: lệnh này hiển thị các connector của claude.ai và các mục được đăng ký dưới tên khác. Lệnh cũng in lệnh chạy của từng mục; lệnh chạy của mục npx cũ có thể chứa khóa API, vì vậy đừng lặp lại lệnh đó.
- Máy chủ cho https://www.comet.com/opik/api/v1/mcp dưới bất kỳ tên nào, chẳng hạn như connector claude.ai, nghĩa là máy chủ đã được đăng ký: đừng thêm máy chủ thứ hai. Chỉ cài gói kỹ năng bằng npx skills add comet-ml/opik-skills -g --all. Nếu máy chủ hiển thị ! Needs authentication, hãy chuyển sang bước 4.
- Trình cài đặt sẽ thay thế mục opik-mcp hiện có mà không hỏi, chẳng hạn mục dành cho máy chủ npx cũ. Hãy hỏi người dùng trước khi chạy.
Xác định Opik của người dùng.
- Đã lưu trong ~/.opik.config: hãy dùng cấu hình đó và cho người dùng biết bạn đang thiết lập Opik nào. Trình cài đặt đọc cấu hình này, bao gồm cả khóa API, nên không cần hỏi khóa.
- Không có ~/.opik.config: curl -s http://localhost:5173/api/is-alive/ping. Nếu có câu trả lời, đó là Opik mã nguồn mở trên máy này. Trong shell bị giới hạn, chẳng hạn shell của Codex, không nhận được câu trả lời có thể là do shell không có mạng chứ không phải do không có Opik.
- Không thuộc trường hợp nào ở trên: hãy hỏi, đừng tự chọn. URL Opik trong dự án, chẳng hạn OPIK_URL_OVERRIDE trong .env, sẽ giúp bạn đặt câu hỏi có/không. Nếu không: “Bạn dùng Opik nào: Opik Cloud (www.comet.com), Opik mã nguồn mở (URL của nó) hay nền tảng Comet tự lưu trữ (URL và không gian làm việc của nó)?”

Chạy trình cài đặt cho ứng dụng khách bạn đang dùng. Trình cài đặt cài gói kỹ năng Opik cùng với máy chủ, dù có hay không có --skills; hãy giữ lại cờ này trong lệnh bạn đưa cho người dùng chạy sau. Với Opik Cloud, trình cài đặt mở trình duyệt để đăng nhập và chờ một phút, vì vậy hãy báo trước cho người dùng.

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-client cũng nhận codex, cursor, vscode và opencode. Nếu Opik được lưu trong ~/.opik.config hoặc đang chạy trên localhost, hãy chạy lệnh như hiện tại: --deployment tạm thời cất cấu hình đã lưu, bao gồm cả khóa API. Nếu không thuộc hai trường hợp trên, hãy thêm cờ cho Opik mà người dùng đã nêu ở bước 2:

Opik của người dùng	Thêm
Opik Cloud, `www.comet.com`	`--deployment cloud`
Opik mã nguồn mở	`--deployment local`, và `--url <url>` nếu không chạy trên localhost
Nền tảng Comet tự lưu trữ, `/opik/` trong URL	`--deployment self-hosted --url <url> --workspace <workspace>`, với `OPIK_API_KEY` trong shell

Nếu lệnh thất bại, chẳng hạn do Opik không phản hồi, hãy cho người dùng biết nội dung lệnh đã in và những điều cần kiểm tra, chẳng hạn VPN hoặc URL. Đừng chuyển sang một Opik khác.

Đăng nhập với Opik Cloud. Nếu trình cài đặt báo máy chủ chưa đăng nhập, hãy yêu cầu người dùng chạy claude mcp login opik-mcp hoặc /mcp trong phiên Claude Code, thay vì tự chạy: lệnh này chờ trình duyệt. Connector claude.ai đăng nhập từ /mcp. Khi đăng nhập, người dùng sẽ được yêu cầu chọn không gian làm việc; nếu có, hãy nêu tên không gian làm việc được lưu trong ~/.opik.config.
Hoàn tất. Cho biết những gì đã cài đặt và việc gì còn cần làm. Nêu tên gói kỹ năng: các kỹ năng Opik, được cài đặt cho mọi dự án, giúp tác nhân biết cách tích hợp, đánh giá và gỡ lỗi bằng Opik. Ứng dụng khách tải máy chủ MCP và kỹ năng khi bắt đầu phiên: hãy yêu cầu người dùng bắt đầu phiên mới, rồi thử “list my Opik projects”.

Trong mọi trường hợp:

Đừng yêu cầu người dùng dán khóa API vào cuộc trò chuyện. Máy chủ được lưu trữ không cần khóa; nếu không, hãy lấy khóa từ môi trường shell ("$OPIK_API_KEY") hoặc để người dùng tự chạy lệnh.
Đừng đoán không gian làm việc. Đó là phần nằm sau comet.com/opik/ (hoặc /opik/ trên Comet tự lưu trữ) trong URL Opik của người dùng.
Đừng in ~/.claude.json hoặc ~/.opik.config: cả hai đều có thể chứa khóa API. uvx opik@latest mcp status và claude mcp list hiển thị thông tin cần thiết, còn trình cài đặt tự đọc cấu hình.
Nếu bước kiểm tra quyền chặn một lệnh, đừng tìm cách vượt qua. Hãy đưa cho người dùng lệnh cần chạy (trong Claude Code, ! trước khi chạy lệnh từ lời nhắc).

Với một client mà trình cài đặt không nhận diện, hãy đăng ký thủ công bằng các lệnh trong Thiết lập thủ công: máy chủ được lưu trữ cho Opik Cloud, máy chủ cục bộ cho các trường hợp còn lại.

Trước khi đăng ký máy chủ cục bộ, hãy chạy máy chủ với env bạn sẽ truyền và --check, đồng thời export OPIK_API_KEY trong shell thay vì ghi vào lệnh: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Lệnh thoát với mã 0 và cho biết workspace mà máy chủ nhận diện, hoặc in ra những gì cần sửa. Sau khi đăng ký, Claude Code báo Connected ngay cả khi khóa sai, còn Codex không có bước kiểm tra.
Claude Code từ chối thêm đè lên mục opik-mcp hiện có, vì vậy hãy xóa mục đó trước bằng claude mcp remove opik-mcp --scope user; add của Codex sẽ thay thế mục đó.
Sau khi đăng ký, trong Claude Code, chỉ đọc dòng trạng thái: claude mcp get opik-mcp | grep Status. Toàn bộ đầu ra sẽ in khối env, bao gồm cả API key. Máy chủ được lưu trữ hiển thị ! Needs authentication cho đến khi chạy claude mcp login opik-mcp. Codex không có lệnh khởi động máy chủ trước một phiên; codex mcp get opik-mcp hiển thị nội dung đã lưu, với các giá trị env được che.

Thiết lập thủ công (không kiểm tra Opik, không có gói skill)

Lệnh Bắt đầu nhanh thực hiện tất cả các bước này cho Claude Code, Codex, Cursor, VS Code Copilot và opencode, đồng thời kiểm tra bạn đang dùng Opik nào và cài đặt gói skill. Chỉ đăng ký thủ công khi dùng client khác hoặc muốn xem trình cài đặt ghi những gì. Coding agent cài đặt cho người dùng sẽ chạy trình cài đặt: xem Cài đặt bằng coding agent.

Máy chủ được lưu trữ (Opik Cloud)

Claude Code, thủ công

claude mcp add --scope user --transport http opik-mcp https://www.comet.com/opik/api/v1/mcp

Sau đó đăng nhập từ /mcp → Authenticate trong một phiên Claude Code. Thao tác này mở trình duyệt, vì vậy người ngồi trước bàn phím sẽ thực hiện; từ terminal của chính họ, claude mcp login opik-mcp cũng thực hiện tương tự. --scope user giúp máy chủ khả dụng trong mọi dự án; nếu không có tùy chọn này, Claude Code chỉ đăng ký máy chủ cho thư mục hiện tại. Qua SSH, claude mcp login opik-mcp --no-browser in URL đăng nhập để mở trên máy của bạn; bước cuối cần một terminal tương tác (ssh -t).

Codex, thủ công

codex mcp add opik-mcp --url https://www.comet.com/opik/api/v1/mcp

add mở trang đăng nhập; codex mcp login opik-mcp mở lại trang đó. Trong ~/.codex/config.toml, cùng máy chủ được khai báo như sau:

[mcp_servers.opik-mcp]
url = "https://www.comet.com/opik/api/v1/mcp"

Cursor, thủ công

Dùng nút bên dưới máy chủ được lưu trữ, hoặc thêm vào ~/.cursor/mcp.json:

{
  "mcpServers": {
    "opik-mcp": {
      "url": "https://www.comet.com/opik/api/v1/mcp"
    }
  }
}

VS Code Copilot, thủ công

Dùng nút bên dưới máy chủ được lưu trữ, hoặc thêm vào .vscode/mcp.json trong workspace hoặc vào mcp.json của người dùng (MCP: Open User Configuration):

{
  "servers": {
    "opik-mcp": {
      "type": "http",
      "url": "https://www.comet.com/opik/api/v1/mcp"
    }
  }
}

Các client khác

Bất kỳ client nào chấp nhận URL đều có thể dùng máy chủ được lưu trữ:

npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp

Client chỉ có thể khởi chạy lệnh cục bộ có thể truy cập máy chủ thông qua npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp.

Opik Cloud với API key

Khi không ai có thể hoàn tất đăng nhập bằng trình duyệt, chẳng hạn agent chạy không giám sát từ một script hoặc client không hỗ trợ MCP OAuth, hãy dùng API key từ comet.com/api/my/settings/ thay vào đó, với máy chủ cục bộ được trỏ đến Opik Cloud:

claude mcp add --scope user opik-mcp \
  --env OPIK_API_KEY="$OPIK_API_KEY" \
  --env OPIK_WORKSPACE=<workspace> \
  -- uvx opik-mcp

Các client khác dùng cùng hai biến trong khối env của chúng. Đặt OPIK_WORKSPACE thành phần nằm sau comet.com/opik/ trong URL Opik của bạn (https://www.comet.com/opik/acme-ai/projects → acme-ai). Nếu bỏ qua, máy chủ sẽ gửi default, được Comet phân giải thành workspace mặc định của tài khoản bạn, nên các lần đọc có thể lấy dữ liệu từ sai workspace mà không báo lỗi.

Máy chủ cục bộ (Opik tự lưu trữ và mã nguồn mở)

Các ví dụ dùng Opik mã nguồn mở chạy cục bộ. Với Comet tự lưu trữ, hãy thay bằng ba biến trong bảng. Sau khi thêm máy chủ, hãy bắt đầu một phiên mới và hỏi: "liệt kê các dự án Opik của tôi".

Claude Code, thủ công

claude mcp add --scope user opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp

Với Comet tự lưu trữ, khi khóa nằm trong OPIK_API_KEY của shell:

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

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

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

claude mcp get opik-mcp hiển thị ✔ Connected khi máy chủ khởi động. Điều đó không chứng minh URL hoặc khóa chính xác, vì chỉ một lệnh gọi công cụ mới truy cập Opik; --check (máy chủ cục bộ) mới làm được điều đó. Lệnh này cũng in khối env, bao gồm cả API key.

Codex, thủ công

codex mcp add opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp

Hoặc chỉnh sửa ~/.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 chỉ cấp cho máy chủ cục bộ các biến trong env và các tên trong env_vars, vì vậy khóa được export trong shell sẽ không được truyền đến máy chủ nếu không khai báo ở đó.

Cursor, thủ công

Thêm vào ~/.cursor/mcp.json (toàn cục) hoặc .cursor/mcp.json (dự án), hoặc dùng 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 giới hạn thời gian 60 giây. Cursor áp dụng giới hạn thời gian cứng cho lệnh gọi công cụ, không được đặt lại khi có thông báo tiến độ. Xem Giới hạn đã biết của host.

VS Code Copilot, thủ công

Thêm vào .vscode/mcp.json trong workspace, hoặc vào mcp.json của người dùng (MCP: Open User Configuration):

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

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

OPIK_URL=http://localhost:5173/api npx @modelcontextprotocol/inspector uvx opik-mcp

Bạn đang chuyển từ `npx opik-mcp`?

Máy chủ TypeScript (npm opik-mcp@2) đã lỗi thời và sẽ ngừng xử lý yêu cầu vào 2026-11-15. Với bản cài đặt mới, hãy chạy lệnh Bắt đầu nhanh; uvx opik-mcp là lệnh client chạy để khởi động máy chủ, không phải trình cài đặt. Để chuyển cấu hình hiện có trên Opik Cloud, hãy chuyển sang máy chủ được lưu trữ và bỏ API key. Nếu không, trong cấu hình MCP client, hãy thay npx -y opik-mcp bằng uvx opik-mcp. Một số biến env đã được đổi tên và các cờ dòng lệnh không còn được đọc: xem hướng dẫn chuyển đổi. Chính sách hỗ trợ: DEPRECATED.md. Mã nguồn TypeScript nằm ở git tag legacy-typescript-final.

Công cụ

opik-mcp cung cấp một tập công cụ nhỏ, tập trung vào kết quả, bao quát toàn bộ vòng đời (đọc → chú thích → tuyển chọn → tạo → lặp lại).

Công cụ	Mục đích
`read`	Đọc tổng quát theo id / tên / URI `opik://`
`list`	Liệt kê tổng quát, có thể lọc theo tên + phân trang
`write`	Ghi tổng quát — ghi trace/span, chấm điểm, bình luận, lưu prompt, quản lý dataset và experiment
`schema`	Xem lược đồ các thao tác ghi (LLM dùng để tạo payload hợp lệ)
`read_skill`	Đọc một trong các kỹ năng agent Opik đi kèm máy chủ này

`read`

Một công cụ cho mọi câu hỏi dạng "cho tôi xem X". Nhận một entity_type cùng với một id (UUID hoặc tên đối với các loại có thể đặt tên), hoặc một URI opik:// đầy đủ. Các lần đọc tổng hợp (trace, prompt, thread, agent_insights_issue) nhúng các mục con để một lần gọi trả về toàn bộ thông tin.

Bản ghi bạn chỉ định được trả về đầy đủ. Các mục con được nhúng thì không: nội dung của chúng được lấy bằng truncate=true của backend, vì vậy một trường lớn hơn khoảng 10 KB sẽ bị cắt trong ClickHouse và ảnh base64 được thay bằng "[image]" — nếu không, một tệp đính kèm được lặp lại trên 200 span sẽ tốn nhiều hơn mọi thứ khác trong lần đọc. Phản hồi cho biết điều đó trong spanBodies / messageBodies, và mọi mục con đều có thể được lấy đầy đủ qua read("span", id) hoặc read("trace", trace_id) riêng, vốn gọi đến các endpoint hoàn toàn không có tham số truncate.

Một tập hợp được nhúng cũng bị giới hạn về số lượng: 200 span, 200 lượt hội thoại, 100 phiên bản prompt. Vượt quá giới hạn đó, spansTruncated / messagesTruncated / versionsTruncated sẽ là true, và một dòng moreSpans / moreMessages / moreVersions bên cạnh sẽ ghi số lượng cùng lệnh gọi list(...) chính xác để tiếp tục từ vị trí phần được nhúng dừng lại.

Các thực thể được hỗ trợ: project, trace, span, dataset, dataset_item, experiment, prompt, thread, agent_insights_issue. Có thể tra cứu theo tên đối với project, experiment, prompt, dataset (chậm hơn — cần hai lệnh gọi API — và có thể trả về nhiều kết quả). thread và agent_insights_issue phạm vi theo dự án: truyền project_id hoặc project_name, hoặc một liên kết/URI có chứa dự án. Trước đây dataset và dataset_item được gọi là test_suite và test_suite_item; tên cũ vẫn được phân giải, nhưng không được giới thiệu và mã mới nên dùng tên mới.

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

Liên kết sao chép từ giao diện Opik có thể dùng làm id: liên kết thread hoặc liên kết trang Diagnostics có chứa dự án, nên không cần project_id và loại thực thể được lấy từ liên kết.

Lần đọc project trả lời câu hỏi "dự án của tôi đang hoạt động thế nào" chỉ trong một lần gọi. Lệnh trả về {project, summary, vocabulary, contains, url}: bản ghi, sau đó là bốn chỉ số mà trang Logs hiển thị dưới dạng thẻ (số lượng trace, tỷ lệ lỗi, thời lượng trung bình, tổng chi phí) trong 7 ngày gần nhất so với 7 ngày trước đó, chỉ tính lưu lượng từ SDK, như trên màn hình. since / until thay đổi khoảng thời gian đó; since="30d" là giá trị giao diện người dùng mở sẵn. Tỷ lệ hoặc giá trị trung bình trong khoảng thời gian không có trace sẽ trả về null, vì tỷ lệ lỗi 0% trong một tuần không có lưu lượng không có nghĩa là một tuần hoạt động tốt.

vocabulary là bản đồ cần có trước khi bạn hỏi bất kỳ điều gì khác: tên điểm phản hồi của dự án, các khóa sử dụng token và quy tắc tự động hóa chấm điểm trace. Đây là những tên cần dùng trong bộ lọc hoặc trong series= bên dưới; đoán tên sẽ trả về một trang trống trông như tin tốt. Tên điểm số và quy tắc bị giới hạn số lượng, nhưng luôn báo tổng số thực và nêu lệnh gọi để lấy phần còn lại; các khóa sử dụng được liệt kê đầy đủ vì không có cách nào khác để liệt kê chúng. contains nêu experiment, dataset, phiên bản prompt và lượt chạy tối ưu hóa mới nhất, nên câu hỏi "gần đây ở đây đã diễn ra những gì" không cần thêm bốn lần gọi. Phần nào tải thất bại sẽ được thông báo thay vì trông như trống, còn phần trống sẽ bị lược bỏ.

Lần đọc agent_insights_issue trả về {issue, example_trace_ids, details}: bản ghi vấn đề Diagnostics (tên, mô tả, nguyên nhân, cách khắc phục đề xuất, mức độ nghiêm trọng, trạng thái), các id trace đã loại trùng thể hiện vấn đề đó (cùng mẫu mà trang Diagnostics hiển thị — mở một trace bằng read("trace", id)), và phần phân tích theo ngày. Nội dung trace không được nhúng, nên lần đọc chỉ cần một lệnh gọi backend. since / until thu hẹp các hàng theo ngày; mặc định là toàn bộ thời gian. Khi máy chủ biết URL Opik và workspace của phiên, lần đọc cũng kèm theo url (trang Diagnostics của vấn đề) và trace_url_template (liên kết sâu đến bất kỳ trace mẫu nào), để trợ lý có thể đưa cho bạn liên kết có thể nhấp; trong phiên OAuth mà không thể phân giải workspace, các liên kết sẽ bị lược bỏ thay vì đoán.

Bản thân trace không có URL — không thể suy ra liên kết từ các trường mà read hoặc list trả về, và URL đoán sẽ trả về 404. Thay vào đó, hướng dẫn phiên nêu mẫu liên kết là .../v1/session/redirect/projects/?trace_id={trace_id}&path=..., để trợ lý điền id và đưa cho bạn một liên kết. Liên kết này đi qua chuyển hướng của opik-backend, nơi phân giải dự án và workspace từ trace, nên hoạt động trong trường hợp URL dự án trực tiếp không dùng được, kể cả trong phiên OAuth có workspace chưa được phân giải. Đây là cùng liên kết mà Python SDK in ra cho một trace.

`list`

Duyệt hoặc tìm kiếm một tập hợp có phân trang. Các loại có phạm vi theo dự án (trace, span, thread, agent_insights_issue, dataset_item, prompt_version) cần đối tượng cha: UUID hoặc tên dự án, UUID dataset hoặc UUID prompt.

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

Bộ lọc. trace, span, thread, experiment và dataset_item nhận chuỗi OQL, dùng cùng ngữ pháp với search_traces(filter_string=…) của SDK:

<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in

Chuỗi được đặt trong dấu ngoặc kép, số không có dấu ngoặc, duration tính bằng mili giây, ngày tháng là thời điểm ISO-8601 có múi giờ ("2026-09-08T10:00:00Z"). Điểm số và từ điển nhận một khóa: feedback_scores.accuracy < 0.5, metadata.environment = "prod". AND là connector duy nhất.

Giống như trang Logs của giao diện người dùng, danh sách trace, span và thread thêm source = "sdk" để các trace của evaluator, playground và experiment không gây vướng mắt; tự đặt tên source để xem chúng. Dòng đầu tiên của kết quả lặp lại bộ lọc đã áp dụng.

Bộ lọc không hợp lệ sẽ bị từ chối trước khi đến backend, kèm thông tin cần thiết để sửa: vị trí lỗi cú pháp, tên trường gần nhất, các toán tử hợp lệ cho kiểu của trường hoặc định dạng giá trị được mong đợi. Các trường có tập giá trị cố định (source, span type, thread status, visibility_mode) cũng được kiểm tra theo tập đó, bao gồm mọi phần tử trong danh sách in. source là trường duy nhất được backend tự xác thực; trường này trả về lỗi 500 thay vì 400 khi gặp giá trị không xác định, nên nếu không có bước kiểm tra trước thì source = "SDK" sẽ gây ra lỗi máy chủ khó hiểu khi có chữ cái viết hoa. Các trường còn lại được so sánh dưới dạng chuỗi và trả về một trang trống, trông như “không có kết quả khớp” dù thực chất là “không có giá trị như vậy”. Hãy hỏi schema("list.trace") (hoặc list.span, list.thread, list.experiment) để xem tài liệu tham khảo đầy đủ về các trường, bao gồm cả những giá trị được chấp nhận.

Tìm một trường hợp trong tập dữ liệu. list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key> để lọc theo các khóa mà tập dữ liệu được tạo từ đó, full_data để tìm chuỗi con trong toàn bộ payload (quét toàn bộ — hãy nêu tên khóa nếu có thể), cùng với id, tags, source, trace_id, span_id và dấu thời gian. data.<key> chỉ nhận sáu toán tử chuỗi (=, !=, contains, not_contains, starts_with, ends_with); backend trả về lỗi 400 khi so sánh, vì vậy thao tác này bị từ chối trước khi gọi. Endpoint không hỗ trợ sắp xếp hay tìm kiếm văn bản tự do — sort sẽ bị từ chối thay vì bị bỏ qua. read(entity_type="dataset_item", id=…) trả về toàn bộ một trường hợp, đây là cách đọc lại giá trị đã bị cắt trong bảng.

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

Với experiment_ids, danh sách tương tự sẽ dùng comparison — các trường hợp kèm theo từng lần chạy — và lọc theo các lần chạy (feedback_scores.<name>, output, duration). Đây là hai tập trường khác nhau trên hai endpoint backend: schema("list.dataset_item_case") là các trường hợp riêng của tập dữ liệu, schema("list.dataset_item") là comparison.

Sắp xếp. trace, span, thread và experiment nhận sort="<field> [asc|desc]", mặc định là desc, và chỉ một trường: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". Trường được đối chiếu với danh sách trường có thể sắp xếp của thực thể trước khi gọi, vì backend âm thầm bỏ qua các trường không thể dùng để sắp xếp. Trong các workspace rất lớn, backend bỏ hẳn thao tác sắp xếp; tiêu đề sẽ cho biết khi điều đó xảy ra.

dataset_item chỉ sắp xếp được trong comparison (cùng với experiment_ids): endpoint items không nhận tham số sắp xếp, vì vậy yêu cầu sắp xếp trong danh sách thông thường sẽ bị từ chối thay vì bị bỏ qua.

Khoảng thời gian và tìm kiếm. trace, span và thread nhận since và until, mỗi giá trị là một khoảng thời gian tương đối ("30m", "1h", "7d") hoặc một thời điểm ISO-8601 có múi giờ, nên không cần tự tính giờ cho “một giờ vừa qua”. Khoảng thời gian được tính theo thời điểm tạo bản ghi, cách này nhẹ cho backend và khớp với start_time trong vòng vài giây đối với lưu lượng trực tiếp. Để đặt mốc chính xác, hãy đặt start_time trong filters. Ba loại này cũng nhận search, văn bản tự do được khớp ở bất kỳ đâu trong id, name, input, output, metadata, tags và thread id. Tìm kiếm quét toàn bộ project trên backend, vì vậy lần gọi đầu tiên trên project lớn có thể mất hàng chục giây. Các lệnh gọi đó có thời gian chờ 60 giây. Thêm since sẽ giúp chúng chạy nhanh trở lại.

Đọc bảng. Thời lượng được gắn nhãn duration_ms / ttft_ms và hiển thị dưới dạng số mili giây nguyên; trường vẫn là duration trong filters và sort. Dấu thời gian được hiển thị đến giây và chi phí dưới dạng số thập phân thông thường. Các hàng project có last_updated_trace_at để bạn biết project nào có lưu lượng trực tiếp; các hàng thread hiển thị tin nhắn đầu tiên. Trang trống khi có bộ lọc thời gian sẽ cho biết trace gần nhất của project được ghi nhận khi nào; trang trống với source = "sdk" mặc định sẽ hướng dẫn cách xem các nguồn khác. Tên project_name bị viết sai sẽ trả về tên hiện có gần nhất.

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

Sự cố Diagnostics. agent_insights_issue là trang Diagnostics thông qua MCP: các lỗi lặp lại mà tác vụ Diagnostics của Opik đã nhóm cho một project, được xếp hạng như giao diện người dùng (lần xuất hiện gần nhất trước). Các cột là severity, status, total_occurrences (tổng mọi thời điểm), latest_count (ngày báo cáo gần nhất, con số được nhắc đến trong phần mô tả riêng của sự cố) và last_seen. Mặc định, danh sách hiển thị các sự cố đang mở; truyền status="resolved" hoặc "closed" để xem các trạng thái còn lại. read và list cũng được gọi là issue, tên mà giao diện người dùng dùng cho chúng; tên dài là tên trong enum entity_type, vì vậy thực thể đó không xuất hiện hai lần ở đó. Số lượng là tổng mọi thời điểm để khớp với giao diện người dùng; cùng since / until như với trace sẽ thu hẹp khoảng thời gian, được cắt theo ngày báo cáo UTC vì Diagnostics tổng hợp theo ngày.

Danh sách trống sẽ cho biết lý do, vì nếu không thì “không có gì hỏng” và “chưa ai bật Diagnostics” trông giống nhau. Có năm trạng thái: Diagnostics không khả dụng trên bản triển khai này, chưa được bật cho project này, đã tắt, đã bật nhưng chưa quét gần đây, hoặc đã bật và không phát hiện vấn đề, kèm thời điểm quét gần nhất. Các trạng thái có thể xử lý sẽ nêu tên lệnh cần gọi, và mọi trạng thái đều liên kết đến trang Diagnostics của project.

Danh sách không trống sẽ tự nêu ngày tháng. Các sự cố là những gì lần quét gần nhất đã nhóm, vì vậy câu trả lời kết thúc bằng Report covers data through <time>; nếu khoảng thời gian bạn yêu cầu kéo dài hơn mốc đó, câu trả lời sẽ nêu phần cuối chưa được bao phủ và cách xử lý: kích hoạt một lần quét lại khi phạm vi quét đủ xa về quá khứ, nếu không thì dùng trace thô với since được cung cấp. Nếu yêu cầu một tuần cho project được quét hằng đêm, ngày cuối cùng sẽ thiếu trong kết quả đã nhóm; thông tin này sẽ giải thích điều đó.

write("agent_insights_job.enable", {"project_name": "demo"}) bật Diagnostics. Từ đó trở đi, hệ thống quét hằng ngày và có thể gọi lại an toàn. write("agent_insights_job.trigger", …) quét 24 giờ gần nhất ngay bây giờ, không cần chờ lần chạy ban đêm. Cả hai đều yêu cầu quyền giống như khi đọc sự cố, và cả hai đều bị từ chối nếu bản triển khai không có Diagnostics.

Sự cố chuyển qua vòng đời bằng write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) — đã xử lý — hoặc …close nếu không đáng để xử lý, và …reopen để đưa cả hai trạng thái trở lại danh sách đang mở. Cả ba đều yêu cầu cùng một quyền và trả lời bằng liên kết đến chế độ xem mà sự cố đã chuyển sang, vì sự cố đã giải quyết không còn nằm trên trang mặc định. Việc một lỗi đã được khắc phục hay chưa là quyết định mang tính đánh giá, vì vậy chỉ dùng các thao tác này khi bạn yêu cầu: trợ lý không nên tự ý dọn dẹp danh sách trong lúc phân loại sự cố.

Số liệu theo thời gian. project_metric biểu đồ một số liệu cho project dưới dạng bảng các khoảng thời gian: số lượng trace, span và thread, thời lượng, tỷ lệ lỗi, chi phí, mức sử dụng token và điểm phản hồi. Công cụ này trả lời câu hỏi tiếp theo sau phần tổng quan: điều gì đã thay đổi và khi nào.

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

Các hàng là khoảng thời gian, không phải bản ghi, vì vậy page, size và sort sẽ bị từ chối thay vì bị bỏ qua. interval là hourly, daily, weekly hoặc total; nếu không chỉ định, công cụ sẽ chọn theo khoảng thời gian như tab Metrics — theo giờ tối đa 3 ngày, theo ngày tối đa 30 ngày, theo tuần nếu dài hơn — nên biểu đồ mặc định chỉ có vài chục hàng bất kể phạm vi, còn biểu đồ theo giờ cho cả tháng (721 hàng) là thứ bạn cần yêu cầu. since / until nhận cùng định dạng như ở mọi nơi khác và mặc định là 7 ngày gần nhất. filters dùng các trường của thực thể mà số liệu đề cập đến, vì vậy số liệu span sẽ được lọc theo các trường span.

breakdown chia từng khoảng thời gian theo tags, name, error_info, error_type, model, provider, span_type, guardrail_name hoặc metadata.<key>. Không phải số liệu nào cũng chấp nhận tất cả các trường này, và có bảy số liệu không chấp nhận trường nào; công cụ biết trường hợp nào và sẽ thông báo trước khi gọi backend, đồng thời nêu tên một số liệu khác trả lời cùng câu hỏi nếu có. Ba nhóm trả về nhiều chuỗi cùng lúc (thời lượng theo p50/p90/p99, điểm phản hồi theo tên, mức sử dụng token theo khóa), và backend chỉ biểu đồ một chuỗi tại một thời điểm khi nhóm, nên series= dùng để chọn chuỗi: một phân vị, tên điểm số hoặc khóa sử dụng. Thời lượng mặc định là p50 và mức sử dụng token mặc định là total_tokens; giá trị nào được dùng sẽ được lặp lại ở dòng đầu tiên.

Các khoảng thời gian trống sẽ bị lược bỏ và được đếm ở bên dưới, nên một tháng yên ắng chỉ có vài hàng thay vì một cột toàn số không; tỷ lệ trong khoảng thời gian không có trace sẽ không xuất hiện thay vì được báo là bằng không.

Hãy hỏi schema("list.project_metric") để xem bảng số liệu, các khoảng thời gian và ma trận nhóm theo từng số liệu.

Tên của một project. score_name liệt kê tên các điểm phản hồi được ghi nhận trong project, còn online_rule liệt kê các evaluator của quy tắc tự động hóa được cấu hình trên đó, đây là nguồn gốc của phần lớn các tên này. Cả hai đều là cùng danh sách mà read("project", …) cung cấp, đầy đủ và có phân trang, khi phiên bản bị giới hạn trong phần tổng quan là chưa đủ.

list(entity_type="score_name", project_name="demo")
list(entity_type="online_rule", project_name="demo")

`write`

Bộ điều phối ghi dữ liệu phổ dụng. Truyền operation + data, bộ điều phối sẽ 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 (hoặc một lô). Làm bản ghi cha cho span / điểm số / bình luận.
`trace.update`	Hoàn tất hoặc chỉnh sửa một trace hiện có.
`span.create`	Ghi một span trên trace hiện có (hoặc một lô).
`score.create`	Gắn điểm phản hồi dạng số vào trace, span hoặc thread.
`comment.create`	Gắn bình luận dạng văn bản tự do vào trace, span hoặc thread.
`prompt_version.save`	Lưu phiên bản prompt mới (tạo prompt theo tên nếu chưa có).
`dataset.create`	Tạo tập dữ liệu — `type: "test_suite"` biến nó thành bộ kiểm thử đánh giá.
`dataset_item.upsert`	Upsert các mục vào tập dữ liệu (luôn dùng dạng envelope).
`experiment.create`	Tạo experiment gắn với một tập dữ liệu.
`experiment_item.create`	Gắn các hàng trace + dataset_item vào experiment.
`thread.close`	Đóng thread (đánh dấu là không hoạt động). Truyền `thread_id` và project.
`thread.open`	Mở lại thread đã đóng. Truyền `thread_id` và project.
`agent_insights_job.enable`	Bật Diagnostics cho project (quét hằng ngày, có thể gọi lại an toàn).
`agent_insights_job.trigger`	Chạy quét Diagnostics ngay bây giờ, trong 24 giờ gần nhất.
`agent_insights_issue.resolve`	Đánh dấu sự cố Diagnostics là đã xử lý (trước tiên hãy hỏi người dùng).
`agent_insights_issue.close`	Đánh dấu sự cố Diagnostics là không đáng để xử lý (trước tiên hãy hỏi người dùng).
`agent_insights_issue.reopen`	Đưa sự cố Diagnostics đã giải quyết hoặc đã đóng trở lại danh sách đang mở.
`annotation_queue.create`	Tạo hàng đợi chú giải của project, có thể kèm chế độ xem chú giải tùy chỉnh.
`annotation_queue.update`	Thay đổi hàng đợi chú giải; đặt, thay thế hoặc xóa chế độ xem chú giải.

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

`schema`

Kiểm tra cấu trúc JSON chính xác và các trường bắt buộc của mọi thao tác ghi trước khi gọi — hữu ích khi bạn chưa chắc data cần có dạng như thế nào. Trả về schema, phạm vi OAuth và một ví dụ đã được xác thực. Chỉ tra cứu, không gọi backend.

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

Công cụ tương tự trả lời list.trace, list.span, list.thread và list.experiment bằng thông tin tham chiếu của công cụ list cho thực thể đó: mọi trường có thể lọc cùng kiểu dữ liệu và toán tử hợp lệ, các trường có thể sắp xếp, liệu có áp dụng khoảng thời gian và tìm kiếm văn bản tự do hay không, cùng hai bộ lọc ví dụ.

schema(operation="list.trace")

Cấu hình

Các biến này cấu hình máy chủ cục bộ; mỗi thiết lập là một biến môi trường. Máy chủ được lưu trữ trên Opik Cloud không sử dụng các biến này.

Danh tính / điểm cuối

Biến	Mặc định	Ghi chú
`OPIK_API_KEY`	—	Khóa API, dùng cho Comet tự lưu trữ hoặc Opik Cloud không có máy chủ được lưu trữ. Opik mã nguồn mở không cần khóa này, trừ khi bản triển khai bật xác thực.
`OPIK_WORKSPACE`	unset	Tên workspace. Trên cloud khi có khóa API, nếu không đặt thì sẽ gửi `default`, giá trị này phân giải thành workspace mặc định của tài khoản — hãy đặt rõ ràng nếu bạn làm việc trong workspace khác, nếu không các thao tác đọc sẽ âm thầm lấy dữ liệu từ sai workspace. Để trống khi dùng OAuth (token chứa thông tin này) và trên bản cục bộ/OSS (`default` là workspace duy nhất ở đó).
`COMET_WORKSPACE`	—	Bí danh đã lỗi thời của `OPIK_WORKSPACE` (để tương thích ngược). `OPIK_WORKSPACE` được ưu tiên nếu cả hai đều được đặt.
`COMET_WORKSPACE_ID`	unset	UUID workspace tùy chọn. Khi được đặt, giá trị này được ghi vào các sự kiện phân tích và được ưu tiên hơn giá trị đã phân giải. Hiếm khi cần — các bản cài đặt OAuth tự động lấy UUID từ token.
`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 môi trường staging.
`OPIK_URL`	được suy ra từ `COMET_URL_OVERRIDE` + `/opik/api`	Đặt biến này cho Opik mã nguồn mở, nơi API được cung cấp tại `/api` (cục bộ là `http://localhost:5173/api`). Trên nền tảng Comet, chỉ ghi đè nếu Opik nằm trên máy chủ/đường dẫn khác với giao diện Comet.
`OPIK_DEFAULT_PROJECT_NAME`	unset	Khi được đặt, khối `instructions` theo từng phiên sẽ hướng dẫn LLM truyền giá trị này dưới dạng `project_name` trong 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ủ / giao thức truyền tải

Biến	Mặc định	Ghi chú
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` khi được khởi chạy bởi host, `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ỉ dùng khi phát triển).
`OPIK_MCP_AS_URL`	unset	URL của máy chủ ủy quyền OAuth, được công bố trong `/.well-known/oauth-protected-resource` (RFC 9728) và dùng làm đích proxy cho các yêu cầu dò tìm AS. Cần thiết để các MCP host khởi tạo quy trình OAuth qua HTTP.
`OPIK_MCP_RESOURCE_URI`	unset	URI công khai chuẩn tắc của máy chủ này, được công bố dưới dạng `resource` trong siêu dữ liệu tài nguyên được bảo vệ và dùng để suy ra gợi ý `WWW-Authenticate`.
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	Thời gian tin cậy đối với câu trả lời "hợp lệ" từ quá trình kiểm tra token của opik-backend trước khi yêu cầu tiếp theo dùng cùng token OAuth phải kiểm tra lại. Giới hạn tải bổ sung lên backend do việc xác thực theo từng yêu cầu gây ra, cũng như khoảng thời gian token đã hết hạn vẫn được chuyển tiếp (khoảng thời gian này cũng kết thúc khi backend trả về 401 lần đầu tiên). Bị giới hạn theo `expires_at` của token nếu backend cung cấp giá trị này.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Ngưỡng mức độ ghi log ra stderr.

Chọn giao thức truyền tải

Hai dạng bearer, hai hợp đồng về giao thức truyền tải HTTP. Token truy cập OAuth opik_mcp_at_… được xác thực trên mọi yêu cầu thông qua điểm cuối kiểm tra token của opik-backend (có lưu bộ nhớ đệm, xem OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S); token hết hạn hoặc bị thu hồi sẽ nhận HTTP 401 kèm WWW-Authenticate: Bearer error="invalid_token", đây là tín hiệu để các MCP host dựa vào khi thực hiện quy trình cấp refresh_token âm thầm. Khóa API Opik không được xác thực cục bộ: khóa được chuyển tiếp nguyên trạng đến opik-backend, nơi chịu trách nhiệm thực thi duy nhất. Chọn giao thức truyền tải theo hình thức triển khai:

Tình huống	Giao thức truyền tải
Opik Cloud	Không cần chạy gì: máy chủ được lưu trữ chính là máy chủ này qua HTTP, do Comet vận hành
MCP client và Opik trên cùng một máy (bản cài OSS cục bộ)	stdio (khuyến nghị — đơn giản nhất, không cần cổng hay thiết lập OAuth)
MCP client cục bộ → Opik tự lưu trữ	stdio với các biến môi trường của bản triển khai, hoặc HTTP với OAuth (`OPIK_MCP_AS_URL` trỏ đến backend)
opik-mcp được phục vụ phía sau cùng một lớp biên với opik-backend	HTTP — backend xác thực bearer theo từng yêu cầu

Lưu ý cho các bản cài OSS cục bộ: backend OSS không xác thực yêu cầu, vì vậy opik-mcp chạy qua HTTP đặt phía trước nó cũng mở như chính REST API của OSS. Trên các mạng dùng chung, hãy giữ cấu hình bind mặc định 127.0.0.1 (và ưu tiên stdio).

Đo lường từ xa

Biến	Mặc định	Ghi chú
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Đặt thành `false` để tắt toàn bộ hoạt động đo lường từ xa không thuộc Sentry.
`OPIK_MCP_SENTRY_ENABLED	`true`	Set to `false` để tắt toàn bộ hoạt động đo lường từ xa của Sentry.
=======

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

Các host khác nhau về thời gian cho phép một lệnh gọi công cụ chạy:

Claude Code — không có thời hạn chờ của lệnh gọi công cụ được công bố. Khuyến nghị dùng.
Cursor — thời hạn cứng 60 giây, không được đặt lại khi có tiến triển (lỗi upstream).
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 kéo dài.

Nếu lệnh gọi bị treo, hãy đặt OPIK_MCP_LOG_LEVEL=DEBUG để ghi nhật ký toàn bộ yêu cầu.

Khắc phục sự cố

Thiết lập có hoạt động không? Chạy máy chủ với môi trường từ cấu hình client và --check: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Lệnh này cho biết workspace và các dự án mà máy chủ nhìn thấy, hoặc nêu cách khắc phục. Các lỗi của chính máy chủ cũng cho biết cần thay đổi gì và liên kết đến trang tài liệu tương ứng.

Không nhận được OPIK_API_KEY — biến này không được truyền đến tiến trình máy chủ. Trong Claude Code / Cursor / VS Code, biến môi trường chỉ có hiệu lực khi nằm trong khối env của cấu hình máy chủ MCP, không phải trong shell; Codex cũng chỉ chuyển tiếp các tên được liệt kê trong env_vars. Hãy bắt đầu phiên mới sau khi chỉnh sửa, vì client đọc cấu hình khi phiên bắt đầu.

Yêu cầu được gửi đến /opik/api trên Opik mã nguồn mở — COMET_URL_OVERRIDE dành cho nền tảng Comet tự lưu trữ. Bản mã nguồn mở cung cấp API tại /api: hãy đặt OPIK_URL=http://localhost:5173/api (hoặc https://<host>/api) thay thế. Máy chủ sẽ cảnh báo về việc này khi khởi động nếu host là máy này, và --check trả lời "Không có Opik API tại …".

Lệnh gọi trên Cursor hết thời gian chờ sau 60 giây — đây là lỗi đã biết của Cursor, không phải opik-mcp. Hãy thu hẹp lệnh gọi (giảm size, giới hạn khoảng thời gian chặt hơn) hoặc chạy cùng thao tác trên Claude Code, vốn không có giới hạn cứng.

Không thấy máy chủ, không mở được trang đăng nhập, sai workspace, không tìm thấy uvx. Các vấn đề này được đề cập trong phần khắc phục sự cố của tài liệu. uvx opik@latest mcp status liệt kê mọi client đã cấu hình máy chủ và cho biết cấu hình của chúng có bị sai lệch hay không.

Phát triển

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

Các mục tiêu thường dùng:

Mục tiêu	Chức năng
`make install`	`uv sync --locked --extra dev`
`make run`	Chạy máy chủ MCP (mặc định dùng stdio).
`make run-dev`	Chạy với ghi log DEBUG + `--reload` của uvicorn.
`make dev`	Chạy qua `mcp dev` (trình bao bọc chế độ phát triển của Inspector).
`make inspect`	Khởi chạy MCP Inspector để kết nối với máy chủ đang chạy.
`make test`	`uv run pytest -q`.
`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`.

Cấu trúc kho mã:

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

Nhận trợ giúp

Báo cáo vấn đề về lỗi và yêu cầu tính năng
Tài liệu Opik về tài liệu SDK / backend
Slack cộng đồng Comet để đặt câu hỏi

Giấy phép

Apache-2.0.

Comet Opik

Bạn có thể làm gì với Comet Opik MCP?

Tài liệu

Máy chủ MCP Opik

Bắt đầu nhanh

Opik Cloud: máy chủ được lưu trữ

Plugin Claude Code

Opik tự lưu trữ và mã nguồn mở: máy chủ cục bộ

Cài đặt bằng tác nhân lập trình

Thiết lập thủ công (không kiểm tra Opik, không có gói skill)

Máy chủ được lưu trữ (Opik Cloud)

Claude Code, thủ công

Codex, thủ công

Cursor, thủ công

VS Code Copilot, thủ công

Các client khác

Opik Cloud với API key

Máy chủ cục bộ (Opik tự lưu trữ và mã nguồn mở)

Claude Code, thủ công

Codex, thủ công

Cursor, thủ công

VS Code Copilot, thủ công

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

Bạn đang chuyển từ npx opik-mcp?

Công cụ

read

list

write

schema

Cấu hình

Danh tính / điểm cuối

Máy chủ / giao thức truyền tải

Chọn giao thức truyền tải

Đo lường từ xa

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

Khắc phục sự cố

Phát triển

Nhận trợ giúp

Giấy phép

Bạn đang chuyển từ `npx opik-mcp`?

`read`

`list`

`write`

`schema`