comet-ml/opik-mcp

기존의 TypeScript 서버는 지원 중단(deprecated) 예정이며 2026-11-15에 종료됩니다. MCP 클라이언트 설정에서 npx opik-mcp를 uvx opik-mcp@latest로 교체하세요. 전체 가이드는 legacy/typescript/MIGRATION.md를 참조하세요.

Opik + Ollie를 위한 Model Context Protocol (MCP) 서버.
당신의 AI 호스트(Claude Code, Cursor, VS Code Copilot, MCP Inspector)를 Opik 워크스페이스에 직접 연결하세요 — 채팅창에서 바로 트레이스(traces)를 읽고, 점수(scores)를 기록하며, 프롬프트 버전(prompt versions)을 저장하고, Ollie에게 조사 질문을 던질 수 있습니다.

이미 Opik을 사용 중이며, 코딩할 때 사용하는 동일한 AI 어시스턴트에서 Opik을 제어하고자 하는 LLM 엔지니어들을 위해 구축되었습니다.

사용자: "왜 'gpt-4o-rerank-v3' 실험의 사실성(factuality)이 퇴보했나요?"
Claude: → ask_ollie → 실험 + 트레이스 읽기 → "세 개의 트레이스가 실패한 이유는..."
사용자: "트레이스 7f2e…의 유용성(helpfulness) 점수는 0.9이며, 이유는 '훌륭한 회복(great recovery)'입니다."
...

opik-mcp는 Python 패키지입니다 (Python 3.13+ 필요). 권장되는 실행 방식은 uvx를 사용하는 것이며, 이는 전역 설치나 가상 환경(virtualenv) 관리 없이 필요할 때 최신 배포 버전을 가져와 실행합니다.

uv를 한 번 설치하세요:

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

Opik 워크스페이스에서 다음 두 가지가 필요합니다:

— OPIK_API_KEY: comet.com/api/my/settings/에서 가져오세요.
— 워크스페이스 이름 (URL에 표시된 대로 소문자 사용). 예: OPIK_WORKSPACE가 https://www.comet.com/acme-ai/...라면 → OPIK_WORKSPACE=acme-ai.

선택 사항 — 기본값은 default (Opik SDK 관례)이며, 이는 로컬/OSS 설치에 적합합니다. 이름이 지정된 워크스페이스를 사용하는 클라우드 사용자는 이를 설정해야 합니다. COMET_WORKSPACE는 지원 중단 예정인 별칭(deprecated alias)으로 허용됩니다.

사전 출시 노트: opik-mcp (Python)는 아직 PyPI에 게시되지 않았습니다. 첫 PyPI 출시가 이루어지기 전까지는 아래의 모든 코드 스니펫에서 uvx opik-mcp를 uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp로 교체하여 사용하세요.

OPIK_WORKSPACE는 선택 사항입니다. 아래의 모든 스니펫에서 OPIK_WORKSPACE 라인/키를 생략하면 서버는 default를 사용합니다.

workspace (로컬/OSS 설치 시에는 생략 가능). 이름이 지정된 클라우드 워크스페이스에 연결하는 경우에만 설정하세요.

다음 명령어로 서버를 추가합니다:

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

또는 ~/.claude.json을 직접 수정하세요:

{
"mcpServers": {
"opik-mcp": {
...

Claude Code를 재시작합니다. /mcp 명령어로 opik-mcp가 연결된 상태로 나타나는지 확인하세요.

그 다음, 채팅에서 **"list my Opik projects"**라고 요청하세요. Claude가 list 도구 (tool)를 호출하여 워크스페이스의 프로젝트들을 보여줄 것입니다.

~/.cursor/mcp.json (글로벌) 또는 .cursor/mcp.json (프로젝트)을 편집하거나, Cmd+Shift+J → Features → Model Context Protocol을 여세요:

{
"mcpServers": {
"opik-mcp": {
...

Cursor를 다시 로드하세요. MCP 패널의 opik-mcp 옆에 있는 초록색 점이 연결되었음을 확인해 줍니다. 채팅에서 **"list my Opik projects"**라고 요청하세요.

Cursor는 60초 타임아웃이 있습니다. Cursor는 진행 상황 알림(progress notifications)에 의해 초기화되지 않는 엄격한 도구 호출 (tool-call) 타임아웃을 적용합니다. 긴 ask_ollie 작업은 Cursor에서 실패할 수 있습니다. 알려진 호스트 제한 사항(Known host limits)을 참조하세요.

워크스페이스의 .vscode/mcp.json (또는 사용자 설정 JSON)을 편집하세요:

{
"servers": {
"opik-mcp": {
...

창을 다시 로드하세요. 서버에 접속할 수 있게 되면 Copilot Chat의 MCP 인디케이터에 opik-mcp가 표시됩니다. 채팅에서 **"list my Opik projects"**라고 요청하세요.

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

호스트 설정의 동일한 env 블록에 COMET_URL_OVERRIDE를 추가하세요 (Opik이 기본 경로가 아닌 곳에 있는 경우 OPIK_URL도 추가).

{
"mcpServers": {
"opik-mcp": {
...

ask_ollie 및 run_experiment는 Comet Cloud에서만 사용할 수 있습니다. 셀프 호스팅 (self-hosted) 환경에서는 이러한 호출이 디스패치(dispatch) 단계에서 실패하므로, read / list / write를 직접 사용하세요. OPIK_MCP_ANALYTICS_SOURCE=""를 설정하면 텔레메트리 (telemetry) 이벤트에서 귀하의 설치 환경이 cloud-Comet 소스 레이블에서 제외됩니다.

opik-mcp

결과 중심의 작은 인터페이스를 제공합니다. 전체 라이프사이클(읽기(read) → 주석 달기(annotate) → 큐레이션(curate) → 작성(author) → 반복(iterate))을 아우르는 6가지 도구가 포함되어 있습니다.

도구	목적
read	ID / 이름 / opik:// URI를 통한 범용 읽기
list	선택적 이름 필터 및 페이지네이션(pagination)을 포함한 범용 목록 조회
ask_ollie	Opik 제품 내 어시스턴트를 통한 조사 및 합성
write	범용 쓰기 — 트레이스(traces)/스팬(spans) 기록, 점수 매기기(score), 댓글 달기, 프롬프트 저장, 테스트 스위트(test suites) 및 실험(experiments) 관리
schema	쓰기 작업 스키마(schema) 조사 (LLM이 유효한 페이로드를 구성하는 데 사용)
run_experiment	Ollie를 통해 엔드 투 엔드(end-to-end) 평가 실험 실행

"X를 보여줘"라는 모든 질문에 대응하는 하나의 도구입니다. entity_type과 id(UUID 또는 이름 지정이 가능한 타입의 경우 이름) 또는 전체 opik:// URI를 인자로 받습니다. 복합 읽기(trace, prompt)는 자식 요소들을 인라인(inline)으로 포함하므로, 단 한 번의 호출로 전체 그림을 반환합니다.

지원되는 엔티티(entities): project, trace, span, test_suite, experiment, prompt. project, experiment, prompt, test_suite에 대해서는 이름 기반 조회가 가능합니다 (이 방식은 두 번의 API 호출이 필요하여 더 느리며, 여러 개의 일치 항목을 반환할 수 있습니다).

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo") # 이름 조회
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")

선택적 이름 필터와 페이지네이션을 사용하여 컬렉션을 탐색합니다. 프로젝트 범위의 타입(trace, test_suite_item, prompt_version)은 부모 UUID가 필요합니다.

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank") # 이름 부분 문자열 필터
list(entity_type="trace", project_id="<project-uuid>") # 특정 프로젝트의 트레이스

조사 목적의 질문, 엔티티 간 합성(cross-entity synthesis), 또는 Opik 도메인 전문 지식이 필요한 모든 작업에 사용됩니다. Ollie는 귀하의 워크스페이스에 대한 직접적인 읽기 권한을 가지고 있으며, 요청 시 스트림 중간에 쓰기 작업(점수 매기기, 댓글, 테스트 스위트 항목, 프롬프트 버전)을 실행할 수 있습니다.

ask_ollie(query="'demo' 프로젝트의 span이 왜 이번 주에 지난주보다 느린가요?")
ask_ollie(query="실험 A와 B의 사실성 (factuality)을 비교하세요. A의 하위 5개 trace에 대해 이유와 함께 0.2점을 부여하세요.")

어시스턴트의 최종 텍스트와 thread_id를 반환합니다. 문맥을 유지하기 위해 후속 질문 시 이 ID를 다시 전달하세요. Ollie는 스레드 간의 메모리를 보유하지 않습니다.

YOLO 모드 (기본값). Ollie가 수행하는 쓰기 작업은 각 작업에 대한 확인 절차 없이 스트림 중간에 실행됩니다. 모든 자동 승인은 opik_mcp.audit Python 로거에 JSON 감사 행(audit row)으로 기록됩니다. 대신 확인을 요구하려면 OPIK_MCP_AUTO_APPROVE=disabled로 설정하세요. 그러면 Ollie의 확인 요청이 수동으로 재발행할 수 있는 입력 오류(typed errors)로 나타납니다.

Comet Cloud에서만 사용할 수 있습니다.

범용 쓰기 디스패처 (Universal write dispatcher). operation과 data를 전달하면 디스패처가 페이로드 (payload)를 검증하고, 적절한 REST 동사 (verb)를 적용하며, 백엔드 응답을 반환합니다.

작업 (Operations):

작업 (Operation)	기능
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	새로운 프롬프트 버전을 저장합니다 (누락된 경우 이름으로 프롬프트 생성).
test_suite.create	평가 테스트 스위트 (test suite)를 생성합니다.
test_suite_item.upsert	테스트 스위트에 항목을 upsert 합니다 (항상 envelope 형태).
experiment.create	테스트 스위트 범위 내의 실험 (experiment)을 생성합니다.
experiment_item.create	experiment에 trace + dataset_item 행을 첨부합니다.

write(operation="score.create", data={
"target": "trace",
"target_id": "7f2e3c8a-…",
...

쓰기 작업을 호출하기 전에 해당 작업의 정확한 JSON 형태와 필수 필드를 검사하세요. 이는 data가 무엇인지 확실하지 않을 때 유용합니다.

어떻게 생겼는지 보여줍니다. 스키마 (schema), OAuth 범위 (scope), 그리고 검증된 예시 하나를 반환합니다. 백엔드 호출 없이 순수 조회(Pure lookup)만 수행합니다.

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

Ollie를 통해 평가 실험 (evaluation experiment)을 엔드 투 엔드 (end-to-end)로 실행합니다. Opik의 실험 형태 (프롬프트 (prompt), 테스트 스위트 (test suite), 스코어러 (scorers))를 반영하는 단일 experiment_config 딕셔너리 (dict)를 인자로 받습니다. Ollie는 실행을 수행하고 그 결과를 Opik 실험으로 다시 기록합니다.

run_experiment(experiment_config={
"test_suite_name": "qa-eval-v2",
"prompt_name": "welcome-msg",
...

Comet Cloud에서만 사용 가능합니다.

모든 설정은 환경 변수 (environment variable)입니다. 굵게 표시된 항목은 필수 항목입니다.

| 변수 (Variable) | 기본값 (Default) | 비고 (Notes) |
|---|---|:|
| OPIK_API_KEY | — | ask_ollie 및 모든 인증된 읽기/쓰기에 필수입니다. |
| OPIK_WORKSPACE | default | 워크스페이스 (Workspace) 이름. 선택 사항 — 미설정 시 default로 대체됩니다 (Opik SDK 관례). 이름이 지정된 워크스페이스를 사용하는 클라우드 사용자는 이를 설정해야 합니다. |
| COMET_WORKSPACE | — | OPIK_WORKSPACE의 지원 중단된 별칭 (하위 호환성용). 두 값이 모두 설정된 경우 OPIK_WORKSPACE가 우선합니다. |
| COMET_WORKSPACE_ID | — | 선택 사항인 워크스페이스 UUID. 설정 시 분석 이벤트에 기록되어, BI가 (변경 가능한) 워크스페이스 이름 대신 안정적인 ID로 조인 (join)할 수 있게 합니다. |
| COMET_URL_OVERRIDE | https://www.comet.com | 자체 호스팅하는 Comet 호스트 또는 스테이징 (staging)을 위한 https://dev.comet.com으로 설정합니다. |
| OPIK_URL | COMET_URL_OVERRIDE + /opik/api에서 유도됨 | Opik이 Comet UI와 다른 호스트/경로에 있는 경우에만 재정의합니다. |
| OPIK_DEFAULT_PROJECT_NAME | 미설정 (unset) | 설정 시, 세션별 instructions 블롭 (blob)이 LLM에게 사용자가 다른 프로젝트를 지정하지 않는 한 모든 도구 호출 (tool call) 시 이를 project_name으로 전달하도록 지시합니다. |

변수 (Variable)	기본값 (Default)	비고 (Notes)
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	uvicorn --reload를 활성화하려면 true로 설정 (개발용)
OPIK_MCP_AS_URL	미설정 (unset)	OAuth 권한 부여 서버 (Authorization Server, AS) URL. /.well-known/oauth-protected-resource (RFC 9728)에 공지되며 AS-discovery 프로브의 프록시 타겟으로 사용됩니다. MCP 호스트가 HTTP를 통해 OAuth 인증 절차 (OAuth dance)를 부트스트랩하는 데 필요합니다.
OPIK_MCP_RESOURCE_URI	미설정 (unset)	이 서버의 정식 공개 URI (Canonical public URI). 보호된 리소스 (protected-resource) 메타데이터의 resource로 공지되며 WWW-Authenticate 힌트를 도출하는 데 사용됩니다.
OPIK_MCP_LOG_LEVEL	INFO	stderr 로거 임계값 (threshold)

opik-mcp는 HTTP 전송 시 로컬 자격 증명 검증을 수행하지 않습니다: 형식이 올바른 모든 Authorization: Bearer … (Opik API 키 또는 opik_at_… OAuth 액세스 토큰)는 인증 강제의 단일 지점인 opik-backend로 그대로 전달됩니다. 배포 형태에 따라 전송 방식 (transport)을 선택하세요:

시나리오 (Scenario)	전송 방식 (Transport)
MCP 클라이언트와 Opik이 동일한 머신에 있는 경우 (로컬 OSS 설치)	stdio (권장 — 가장 간단하며, 포트나 OAuth 설정이 필요 없음)
...

로컬 OSS 설치 시 참고 사항: OSS 백엔드는 요청을 인증하지 않으므로, 그 앞에 있는 HTTP opik-mcp는 OSS REST API 자체만큼이나 개방되어 있습니다. 공유 네트워크 환경에서는 기본값인 127.0.0.1 바인드를 유지하십시오 (그리고 stdio를 우선적으로 사용하십시오).

변수 (Variable)	기본값 (Default)	비고 (Notes)
OPIK_MCP_AUTO_APPROVE	enabled	Ollie의 미드스트림 (mid-stream) 쓰기가 진행되기 전, 각 작업에 대한 승인을 요구하려면 disabled로 설정하십시오. MCP elicitation 기능을 지원하는 호스트에서는 사용자가 예/아니오(yes/no) 프롬프트를 보게 되며, 지원하지 않는 호스트에서는 요청이 수동으로 재발행할 수 있는 타입 에러 (typed error)로 나타납니다.
OPIK_MCP_ELICIT_TIMEOUT_SECONDS	60	Ollie의 미드스트림 확인 프롬프트가 취소로 처리되기 전까지 사용자의 응답을 기다리는 시간입니다. 0으로 설정하면 이 제한을 비활성화합니다 (디버그 용도로만 사용).
OPIK_MCP_POD_READY_TIMEOUT_S	120	Ollie 포드 (pod) 콜드 스타트 (cold-start) 폴링 (poll) 상한값입니다.
OPIK_MCP_POD_READY_INTERVAL_S	2	콜드 스타트 폴링 간격입니다.
OPIK_MCP_HEARTBEAT_INTERVAL_S	15.0	워치독 (Watchdog) 주기 — 포드가 침묵할 때 notifications/progress 틱을 방출하여 호스트 타임아웃 (timeout)을 방지합니다.
OPIK_MCP_STREAM_IDLE_TIMEOUT_S	300.0	ask_ollie가 중단되기 전까지 허용되는 포드 침묵의 최대 한계치입니다. 0으로 설정하면 비활성화됩니다 (디버그 용도로만 사용).

익명 사용 이벤트 (이벤트 유형 + 타이밍만 포함 — 쿼리 내용은 포함되지 않음). 기술 지원팀이 귀하의 계정을 찾을 수 있도록 API 키의 SHA-256 다이제스트 (digest)가 포함되지만, 원본 키는 프로세스를 절대 벗어나지 않습니다. 거부 (Opt out): OPIK_MCP_ANALYTICS_ENABLED=false