Comet Opik MCP Server

공식

Opik 로그, 트레이스, 프롬프트 및 LLM의 기타 모든 텔레메트리 데이터를 자연어로 쿼리하고 분석합니다.

문서

opik-mcp

이전 npx opik-mcp에서 마이그레이션하시나요? TypeScript 서버는 더 이상 사용되지 않으며 2026-11-15에 종료됩니다. MCP 클라이언트 구성에서 npx -y opik-mcp를 **uvx opik-mcp@latest**로 교체하세요. 전체 가이드: legacy/typescript/MIGRATION.md.

Opik + Ollie를 위한 모델 컨텍스트 프로토콜 서버. AI 호스트(Claude Code, Cursor, VS Code Copilot, MCP Inspector)를 Opik 워크스페이스에 직접 연결하여 — 트레이스 읽기, 점수 기록, 프롬프트 버전 저장, Ollie에 조사 질문하기 등을 모두 채팅에서 수행할 수 있습니다.

이미 Opik을 실행 중이고 코딩에 사용하는 동일한 AI 어시스턴트에서 이를 구동하려는 LLM 엔지니어를 위해 제작되었습니다.

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

설치

opik-mcp은 Python 패키지입니다(Python 3.13+ 필요). 권장 실행 방법은 uvx이며, 이는 필요 시 최신 게시 버전을 가져와 실행합니다 — 전역 설치나 virtualenv 관리가 필요 없습니다.

uv를 한 번 설치하세요:

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

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

OPIK_API_KEY — comet.com/api/my/settings/에서 가져오세요.
OPIK_WORKSPACE — 워크스페이스 이름(URL에 표시되는 소문자). 예: https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. 선택 사항 — 기본값은 default(Opik SDK 규칙)이며, 로컬/OSS 설치에 적합합니다. 명명된 워크스페이스를 사용하는 클라우드 사용자는 설정해야 합니다. COMET_WORKSPACE은 더 이상 사용되지 않는 별칭으로 허용됩니다.

사전 출시 참고: 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 워크스페이스를 사용합니다(로컬/OSS 설치에 적합). 명명된 클라우드 워크스페이스에 연결하는 경우에만 설정하세요.

Claude Code

하나의 명령으로 서버를 추가하세요:

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

또는 ~/.claude.json을 직접 편집하세요:

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

Claude Code를 다시 시작하세요. /mcp로 확인 — opik-mcp이 연결된 것으로 나타나야 합니다. 그런 다음 채팅에서 **"내 Opik 프로젝트 나열"**이라고 요청하세요 — Claude가 list 도구를 호출하고 워크스페이스의 프로젝트를 볼 수 있습니다.

Cursor

~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트)을 편집하거나, Cmd+Shift+J → 기능 → 모델 컨텍스트 프로토콜을 여세요:

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

Cursor를 다시 로드하세요. MCP 패널에서 opik-mcp 옆의 녹색 점이 연결을 확인해 줍니다. 채팅에서 **"내 Opik 프로젝트 나열"**이라고 요청하세요.

Cursor 60초 시간 초과. Cursor는 진행 알림에서 재설정되지 않는 하드 도구 호출 시간 초과를 적용합니다. 긴 ask_ollie 턴은 Cursor에서 실패합니다. 알려진 호스트 제한을 참조하세요.

VS Code Copilot

워크스페이스(또는 사용자 설정 JSON)의 .vscode/mcp.json:

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

창을 다시 로드하세요. 서버에 연결 가능하면 Copilot Chat MCP 표시기에 opik-mcp이 나타납니다. 채팅에서 **"내 Opik 프로젝트 나열"**이라고 요청하세요.

MCP Inspector (수동 테스트)

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

자체 호스팅 Opik

호스트 구성의 동일한 env 블록에 COMET_URL_OVERRIDE(및 Opik이 기본 경로가 아닌 곳에 있는 경우 OPIK_URL)을 추가하세요:

{
  "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 및 run_experiment은 Comet Cloud에서만 사용 가능합니다 — 자체 호스팅에서는 이러한 호출이 디스패치 시 실패하므로 read / list / write을 직접 사용하세요. OPIK_MCP_ANALYTICS_SOURCE=""을 설정하면 원격 분석 이벤트에서 클라우드-Comet 소스 레이블이 설치에서 제외됩니다.

도구

opik-mcp는 전체 수명 주기(읽기 → 주석 달기 → 큐레이션 → 작성 → 반복)를 다루는 작고 결과 지향적인 표면 — 여섯 가지 도구를 노출합니다.

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

`read`

"X 보여줘" 질문을 위한 하나의 도구. entity_type과 id (UUID 또는 이름 지정 가능 유형의 경우 이름) 또는 전체 opik:// URI를 사용합니다. 복합 읽기 (trace, prompt)는 자식을 인라인으로 포함하므로 단일 호출로 전체 그림을 반환합니다.

지원 엔티티: 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")          # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")

`list`

선택적 이름 필터와 페이지 매김으로 컬렉션을 탐색합니다. 프로젝트 범위 유형(trace, test_suite_item, prompt_version)은 부모 UUID가 필요합니다.

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`

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

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

어시스턴트의 최종 텍스트와 thread_id을 반환합니다. 후속 질문에 이를 다시 전달하여 컨텍스트를 유지하세요 — Ollie는 스레드 간 메모리가 없습니다.

YOLO 모드(기본값). Ollie가 중간 스트림에서 수행하는 쓰기는 작업별 확인 없이 실행됩니다. 각 자동 승인은 opik_mcp.audit Python 로거에 JSON 감사 행으로 기록됩니다. 대신 확인을 요구하려면 OPIK_MCP_AUTO_APPROVE=disabled을 설정하세요 — 그러면 Ollie의 확인 요청이 수동으로 다시 실행할 수 있는 유형 오류로 표시됩니다.

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

`write`

범용 쓰기 디스패처. operation + data을 전달하면 디스패처가 페이로드를 검증하고, 올바른 REST 동사를 적용하며, 백엔드 응답을 반환합니다.

작업:

작업	수행 내용
`trace.create`	단일 트레이스(또는 배치)를 기록합니다. 스팬 / 점수 / 댓글의 부모.
`trace.update`	기존 트레이스를 완료하거나 수정합니다.
`span.create`	기존 트레이스에 스팬(또는 배치)을 기록합니다.
`score.create`	트레이스, 스팬 또는 스레드에 숫자 피드백 점수를 첨부합니다.
`comment.create`	트레이스, 스팬 또는 스레드에 자유 텍스트 댓글을 첨부합니다.
`prompt_version.save`	새 프롬프트 버전을 저장합니다(없는 경우 이름으로 프롬프트 생성).
`test_suite.create`	평가 테스트 스위트를 생성합니다.
`test_suite_item.upsert`	테스트 스위트에 항목을 Upsert합니다(항상 엔벨로프 형태).
`experiment.create`	테스트 스위트로 범위가 지정된 실험을 생성합니다.
`experiment_item.create`	실험에 트레이스 + dataset_item 행을 첨부합니다.

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

`schema`

호출하기 전에 쓰기 작업의 정확한 JSON 형태와 필수 필드를 검사합니다 — data이 어떻게 생겼는지 확실하지 않을 때 유용합니다. 스키마, OAuth 범위, 검증된 예제 하나를 반환합니다. 순수 조회이며 백엔드 호출은 없습니다.

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

`run_experiment`

Ollie를 통해 평가 실험을 엔드 투 엔드로 실행합니다. Opik의 실험 형태(프롬프트, 테스트 스위트, 스코어러)를 반영하는 단일 experiment_config dict를 사용합니다. Ollie가 실행을 수행하고 결과를 Opik 실험으로 다시 기록합니다.

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

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

구성

모든 설정은 환경 변수입니다. 필수 항목은 굵게 표시됩니다.

ID / 엔드포인트

변수	기본값	참고
`OPIK_API_KEY`	—	`ask_ollie` 및 모든 인증된 읽기/쓰기에 필요합니다.
`OPIK_WORKSPACE`	`default`	워크스페이스 이름. 선택 사항 — `default`(Opik SDK 규칙)으로 폴백합니다. 명명된 워크스페이스를 사용하는 클라우드 사용자는 설정해야 합니다.
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE`의 더 이상 사용되지 않는 별칭(하위 호환). 둘 다 설정된 경우 `OPIK_WORKSPACE`이 우선합니다.
`COMET_WORKSPACE_ID`	—	선택적 워크스페이스 UUID. 설정 시 분석 이벤트에 포함되어 BI가 (변경 가능한) 워크스페이스 이름 대신 안정적인 ID로 조인할 수 있습니다.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	자체 호스팅 Comet 호스트로 설정하거나 스테이징의 경우 `https://dev.comet.com`로 설정합니다.
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api`에서 파생	Opik이 Comet UI와 다른 호스트/경로에 있는 경우에만 재정의합니다.
`OPIK_DEFAULT_PROJECT_NAME`	설정 안 됨	설정 시 세션별 `instructions` blob이 LLM에 사용자가 다른 프로젝트를 지정하지 않는 한 모든 도구 호출에서 이를 `project_name`로 전달하도록 지시합니다.

서버 / 전송

변수	기본값	참고
`OPIK_MCP_TRANSPORT`	`stdio`	호스트 실행의 경우 `stdio`, 포트에서 수신 대기하려면 `streamable-http`.
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn 바인드 호스트(`streamable-http` 전용).
`OPIK_MCP_PORT`	`8080`	uvicorn 바인드 포트(`streamable-http` 전용).
`OPIK_MCP_RELOAD`	`false`	uvicorn `--reload`를 활성화하려면 `true`(개발 전용).
`OPIK_MCP_AS_URL`	설정 안 됨	OAuth 인증 서버 URL, `/.well-known/oauth-protected-resource`(RFC 9728)에 광고되며 AS-디스커버리 프로브의 프록시 대상으로 사용됩니다. MCP 호스트가 HTTP를 통해 OAuth 댄스를 부트스트랩하는 데 필요합니다.
`OPIK_MCP_RESOURCE_URI`	설정 안 됨	이 서버의 표준 공개 URI, 보호된 리소스 메타데이터에 `resource`으로 광고되며 `WWW-Authenticate` 힌트를 파생하는 데 사용됩니다.
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr 로거 임계값.

전송 선택

opik-mcp는 HTTP 전송에서 로컬 자격 증명 유효성 검사를 수행하지 않습니다: 올바른 형식의 Authorization: Bearer …(Opik API 키 또는 opik_mcp_at_… OAuth 액세스 토큰)은 그대로 opik-backend로 전달되며, 이는 단일 인증 시행 지점입니다. 배포 형태에 따라 전송을 선택하세요:

시나리오	전송
MCP 클라이언트와 Opik이 동일한 머신에 있음(로컬 OSS 설치)	stdio(권장 — 가장 간단, 포트 없음, OAuth 설정 없음)
로컬 MCP 클라이언트 → 원격 Opik(Comet 클라우드 / 자체 호스팅)	`OPIK_API_KEY`를 사용한 stdio, 또는 OAuth를 사용한 HTTP(`OPIK_MCP_AS_URL`이 백엔드를 가리킴)
opik-backend와 동일한 에지 뒤에 호스팅된 opik-mcp	HTTP — 베어러는 요청별로 백엔드에서 유효성이 검사됩니다

로컬 OSS 설치 참고: OSS 백엔드는 요청을 인증하지 않으므로 그 앞의 HTTP opik-mcp는 OSS REST API 자체만큼 개방적입니다. 공유 네트워크에서는 기본 127.0.0.1 바인드를 유지하고 stdio를 선호하세요.

Ollie / 긴 호출

변수	기본값	참고
`OPIK_MCP_AUTO_APPROVE`	`enabled`	Ollie의 중간 스트림 쓰기가 진행되기 전에 작업별 승인을 요구하려면 `disabled`. MCP `elicitation` 기능을 광고하는 호스트에서는 사용자에게 예/아니요 프롬프트가 표시됩니다. 덜 똑똑한 호스트에서는 요청이 수동으로 다시 실행할 수 있는 유형 오류로 표시됩니다.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie의 중간 스트림 확인 프롬프트가 취소로 처리되기 전에 사용자를 기다릴 수 있는 시간. `0`은 바인드를 비활성화합니다(디버그 전용).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie 포드 콜드 스타트 폴링 한도.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	콜드 스타트 폴링 간격.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	워치독 주기 — 포드가 조용할 때 `notifications/progress` 틱을 내보내 호스트 시간 초과를 방지합니다.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	`ask_ollie`이 중단되기 전 포드 침묵에 대한 하드 상한. `0`은 비활성화합니다(디버그 전용).

원격 분석

익명 사용 이벤트(이벤트 유형 + 타이밍만 — 쿼리 내용 없음). API 키의 SHA-256 다이제스트가 포함되어 지원팀이 계정을 찾을 수 있습니다. 원시 키는 프로세스를 떠나지 않습니다. 옵트아웃: OPIK_MCP_ANALYTICS_ENABLED=false.

변수	기본값	설명
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	모든 원격 측정을 비활성화하려면 `false`로 설정하세요.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	스테이징용 재정의.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	모든 이벤트에 태그 지정 (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	수신자가 `on_prem=False`를 표시하는 데 사용합니다. 온프레미스 설치 시 `""` 또는 자체 도메인으로 재정의해야 합니다.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP 연결 타임아웃.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP 총 요청 타임아웃.

알려진 호스트 제한 사항

MCP 사양에 따르면 호스트는 notifications/progress에서 도구 호출 타임아웃을 재설정할 수 있습니다. — opik-mcp는 Ollie SSE 이벤트당 하나씩, 그리고 15초 감시 하트비트를 내보냅니다. 실제 상황은 제각각입니다:

Claude Code — 문서화된 도구 호출 타임아웃이 없으며, 하트비트가 message_end까지 호출을 유지합니다. 권장됩니다.
Cursor — 60초의 하드 타임아웃이 있으며, 진행 상황에서 재설정되지 않습니다 (업스트림 버그). 긴 Ollie 실행은 실패합니다. ask_ollie 쿼리를 집중적으로 유지하세요.
MCP Inspector — MAX_TOTAL_TIMEOUT가 총 지속 시간을 제한합니다(기본값 60초). 긴 작업의 경우 Inspector UI에서 값을 높이세요.

호출이 멈추면 OPIK_MCP_LOG_LEVEL=DEBUG를 설정하세요 — 하트비트 실패(일반적으로 호스트 연결 해제)는 opik_mcp.ask_ollie에 디버그 수준으로 기록됩니다.

문제 해결

OPIK_API_KEY is required to use ask_ollie — 변수가 서버 프로세스에 도달하지 않습니다. Claude Code / Cursor / VS Code에서 환경 변수는 셸이 아닌 MCP 서버 구성의 env 블록 내에서만 적용됩니다. 편집 후 호스트를 다시 시작하세요.

ask_ollie이 2분 후 "pod not ready"를 반환합니다 — Ollie 파드 콜드 스타트가 OPIK_MCP_POD_READY_TIMEOUT_S를 초과했습니다. 다시 시도하세요 — 두 번째 호출은 일반적으로 웜 파드에 도달합니다.

자체 호스팅 Opik에서 ask_ollie / run_experiment이 디스패치 오류로 실패합니다 — 이러한 도구는 Comet Cloud에서만 사용할 수 있습니다. 자체 호스팅에서는 read / list / write을 직접 사용하세요.

Cursor 호출이 60초에 타임아웃됩니다 — Cursor의 알려진 버그이며, opik-mcp 문제가 아닙니다. Ollie 쿼리를 줄이거나, 하드 제한이 없는 Claude Code에서 동일한 작업을 실행하세요.

개발

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

일반적인 대상:

대상	수행 작업
`make install`	`uv sync --extra dev`
`make run`	MCP 서버 실행(기본값 stdio).
`make run-dev`	DEBUG 로깅 + uvicorn `--reload`으로 실행.
`make dev`	`mcp dev`을 통해 실행(Inspector 개발 모드 래퍼).
`make inspect`	실행 중인 서버에 대해 MCP Inspector 시작.
`make test`	`uv run pytest -q`.
`make test-live`	`dev.comet.com`에 대한 실시간 종단 간 테스트(`OPIK_API_KEY` + `OPIK_WORKSPACE` 설정).
`make lint`	`ruff check` + 형식 검사.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

저장소 레이아웃:

opik-mcp/
├── src/opik_mcp/        ← server, tools, ask_ollie, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

도움 받기

버그 및 기능 요청은 이슈 열기
SDK / 백엔드 문서는 Opik 문서
질문은 Comet 커뮤니티 Slack

v2에서 업그레이드하시나요? 레거시 TypeScript 서버는 여전히 npm에 opik-mcp@^2 (npx -y opik-mcp)로 제공되며, 소스는 legacy/typescript/ 아래에 보존되어 있습니다. 지원 정책은 legacy/typescript/DEPRECATED.md를 참조하세요.

라이선스

Apache-2.0.