Comet Opik

oficial

Consulte e analise seus logs, traces, prompts e todos os outros dados de telemetria dos seus LLMs em linguagem natural.

GitHub

212

O que você pode fazer com Comet Opik MCP?

Navegar por projetos, experimentos e traces — use list para explorar seu workspace com filtros opcionais de nome e paginação.
Inspecionar qualquer entidade por ID, nome ou URI — chame read em projetos, traces, spans, experimentos, prompts ou suítes de teste, com entidades filhas incluídas automaticamente.
Pedir ao Ollie para investigar regressões ou comparar experimentos — ask_ollie sintetiza respostas entre entidades e pode pontuar ou comentar traces em tempo real.
Registrar pontuações, comentários, traces e spans — envie operações write como score.create, trace.create ou span.create diretamente do chat.
Salvar versões de prompt e gerenciar suítes de teste — use write com prompt_version.save, test_suite.create ou test_suite_item.upsert.
Executar um experimento de avaliação completo — run_experiment realiza uma avaliação completa via Ollie usando um prompt, suíte de teste e avaliadores que você especificar.

Documentação

opik-mcp

Migrando do antigo npx opik-mcp? O servidor TypeScript está obsoleto e será descontinuado em 2026-11-15. Substitua npx -y opik-mcp por uvx opik-mcp@latest na configuração do seu cliente MCP. Guia completo: legacy/typescript/MIGRATION.md.

Servidor Model Context Protocol para Opik + Ollie. Conecte seu host de IA (Claude Code, Cursor, VS Code Copilot, MCP Inspector) diretamente ao seu workspace do Opik — leia traces, registre scores, salve versões de prompt e faça perguntas investigativas ao Ollie, tudo pelo chat.

Criado para engenheiros de LLM que já usam o Opik e querem controlá-lo pelo mesmo assistente de IA com o qual programam.

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

Instalação

opik-mcp é um pacote Python (requer Python 3.13+). A forma recomendada de executá-lo é com uvx, que busca e executa a versão mais recente publicada sob demanda — sem instalação global, sem malabarismos com virtualenv.

Instale o uv uma vez:

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

Você precisará de duas coisas do seu workspace do Opik:

OPIK_API_KEY — obtenha em comet.com/api/my/settings/.
OPIK_WORKSPACE — nome do seu workspace (minúsculas, como aparece na URL). Ex.: https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Opcional — o padrão é default (convenção do SDK do Opik), que é o correto para instalações locais/OSS; usuários da nuvem com um workspace nomeado devem configurá-lo. COMET_WORKSPACE é aceito como um alias obsoleto.

Nota de pré-lançamento: opik-mcp (Python) ainda não foi publicado no PyPI. Até que o primeiro lançamento no PyPI ocorra, substitua uvx opik-mcp em qualquer trecho abaixo por: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE é opcional. Omita a linha/chave OPIK_WORKSPACE em qualquer trecho abaixo e o servidor usará o workspace default (correto para instalações locais/OSS). Configure-o apenas se conectar a um workspace nomeado na nuvem.

Claude Code

Adicione o servidor com um comando:

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

Ou edite ~/.claude.json diretamente:

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

Reinicie o Claude Code. Verifique com /mcp — opik-mcp deve aparecer como conectado. Então, no chat, pergunte: "list my Opik projects" — o Claude chamará a ferramenta list e você verá os projetos do seu workspace.

Cursor

Edite ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto), ou abra 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>"
      }
    }
  }
}

Recarregue o Cursor; o ponto verde ao lado de opik-mcp no painel MCP confirma a conexão. Pergunte no chat: "list my Opik projects".

Timeout de 60s do Cursor. O Cursor impõe um timeout rígido de chamada de ferramenta que não reinicia com notificações de progresso. Turnos longos de ask_ollie falharão no Cursor. Veja Limitações conhecidas dos hosts.

VS Code Copilot

.vscode/mcp.json no seu workspace (ou User Settings JSON):

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

Recarregue a janela; o indicador MCP do Copilot Chat mostra opik-mcp quando o servidor estiver acessível. Pergunte no chat: "list my Opik projects".

MCP Inspector (teste manual)

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

Opik auto-hospedado

Adicione COMET_URL_OVERRIDE (e OPIK_URL se o Opik estiver em um caminho não padrão) ao mesmo bloco env na configuração do seu host:

{
  "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 e run_experiment estão disponíveis apenas no Comet Cloud — em instalações auto-hospedadas, essas chamadas falharão no despacho, então use read / list / write diretamente. Configurar OPIK_MCP_ANALYTICS_SOURCE="" faz sua instalação optar por não usar o rótulo de origem Comet na nuvem em eventos de telemetria.

Ferramentas

opik-mcp expõe uma superfície pequena e orientada a resultados — seis ferramentas que cobrem o ciclo de vida completo (ler → anotar → curar → criar → iterar).

Ferramenta	Propósito
`read`	Leitura universal por id / nome / URI `opik://`
`list`	Listagem universal com filtro de nome opcional + paginação
`ask_ollie`	Investigar / sintetizar via assistente integrado do Opik
`write`	Escrita universal — registrar traces/spans, score, comentar, salvar prompts, gerenciar suítes de teste e experimentos
`schema`	Inspecionar esquemas de operações de escrita (usado pelo LLM para construir payloads válidos)
`run_experiment`	Executar um experimento de avaliação ponta a ponta via Ollie

`read`

Uma ferramenta para qualquer pergunta "mostre-me X". Recebe um entity_type mais um id (UUID ou, para tipos nomeáveis, um nome) ou uma URI opik:// completa. Leituras compostas (trace, prompt) incorporam seus filhos para que uma única chamada retorne a imagem completa.

Entidades suportadas: project, trace, span, test_suite, experiment, prompt. A busca por nome está disponível para project, experiment, prompt, test_suite (mais lenta — duas chamadas de API — e pode retornar múltiplas correspondências).

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

`list`

Navegue por uma coleção com filtro de nome opcional e paginação. Tipos com escopo de projeto (trace, test_suite_item, prompt_version) exigem o UUID do pai.

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`

Para perguntas investigativas, síntese entre entidades ou qualquer coisa que precise de expertise no domínio do Opik. O Ollie tem acesso de leitura direto ao seu workspace e pode executar escritas (scores, comentários, itens de suíte de teste, versões de prompt) durante o fluxo quando solicitado.

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

Retorna o texto final do assistente mais um thread_id. Passe-o de volta em acompanhamentos para preservar o contexto — o Ollie não tem memória entre threads.

Modo YOLO (padrão). As escritas que o Ollie realiza durante o fluxo são executadas sem confirmação por ação. Cada auto-aprovação é registrada como uma linha de auditoria JSON no logger Python opik_mcp.audit. Para exigir confirmação, configure OPIK_MCP_AUTO_APPROVE=disabled — as solicitações de confirmação do Ollie então aparecem como erros tipados que você pode reemitir manualmente.

Disponível apenas no Comet Cloud.

`write`

Despachante universal de escrita. Passe operation + data e o despachante valida o payload, aplica o verbo REST correto e retorna a resposta do backend.

Operações:

Operação	O que faz
`trace.create`	Registra um único trace (ou um lote). Pai para spans / scores / comentários.
`trace.update`	Finaliza ou altera um trace existente.
`span.create`	Registra um span em um trace existente (ou um lote).
`score.create`	Anexa um score de feedback numérico a um trace, span ou thread.
`comment.create`	Anexa um comentário de texto livre a um trace, span ou thread.
`prompt_version.save`	Salva uma nova versão de prompt (cria o prompt pelo nome se não existir).
`test_suite.create`	Cria uma suíte de teste de avaliação.
`test_suite_item.upsert`	Insere ou atualiza itens em uma suíte de teste (sempre no formato envelope).
`experiment.create`	Cria um experimento com escopo em uma suíte de teste.
`experiment_item.create`	Anexa linhas de trace + dataset_item a um experimento.

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

`schema`

Inspecione a forma exata do JSON e os campos obrigatórios de qualquer operação de escrita antes de chamá-la — útil quando você não tem certeza de como data deve ser. Retorna o esquema, o escopo OAuth e um exemplo validado. Apenas consulta, sem chamada ao backend.

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

`run_experiment`

Execute um experimento de avaliação ponta a ponta via Ollie. Recebe um único dict experiment_config que espelha a forma do experimento do Opik (prompt, suíte de teste, scorers); o Ollie executa a rodada e grava os resultados de volta como um experimento do Opik.

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

Disponível apenas no Comet Cloud.

Configuração

Cada configuração é uma variável de ambiente. As obrigatórias estão em negrito.

Identidade / endpoint

Variável	Padrão	Notas
`OPIK_API_KEY`	—	Obrigatória para `ask_ollie` e qualquer leitura/escrita autenticada.
`OPIK_WORKSPACE`	`default`	Nome do workspace. Opcional — o fallback é `default` (convenção do SDK do Opik). Usuários da nuvem com um workspace nomeado devem configurá-lo.
`COMET_WORKSPACE`	—	Alias obsoleto para `OPIK_WORKSPACE` (compatibilidade retroativa). `OPIK_WORKSPACE` prevalece se ambos forem configurados.
`COMET_WORKSPACE_ID`	—	UUID opcional do workspace. Carimbado em eventos de análise quando configurado para que o BI possa unir por um id estável em vez do nome (mutável) do workspace.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Configure para seu host Comet auto-hospedado, ou `https://dev.comet.com` para staging.
`OPIK_URL`	derivado de `COMET_URL_OVERRIDE` + `/opik/api`	Substitua apenas se o Opik residir em um host/caminho diferente da UI do Comet.
`OPIK_DEFAULT_PROJECT_NAME`	não definido	Quando definido, o blob `instructions` por sessão instrui o LLM a passar isso como `project_name` em cada chamada de ferramenta, a menos que o usuário nomeie um projeto diferente.

Servidor / transporte

Variável	Padrão	Notas
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` para lançado pelo host, `streamable-http` para escutar em uma porta.
`OPIK_MCP_HOST`	`127.0.0.1`	Host de bind do uvicorn (apenas `streamable-http`).
`OPIK_MCP_PORT`	`8080`	Porta de bind do uvicorn (apenas `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	`true` para habilitar `--reload` do uvicorn (apenas dev).
`OPIK_MCP_AS_URL`	não definido	URL do Servidor de Autorização OAuth, anunciada em `/.well-known/oauth-protected-resource` (RFC 9728) e usada como alvo de proxy para sondas de descoberta AS. Necessária para hosts MCP iniciarem a dança OAuth sobre HTTP.
`OPIK_MCP_RESOURCE_URI`	não definido	URI pública canônica deste servidor, anunciada como `resource` nos metadados do recurso protegido e usada para derivar a dica `WWW-Authenticate`.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Limiar do logger stderr.

Escolhendo um transporte

O opik-mcp realiza nenhuma validação de credencial local no transporte HTTP: qualquer Authorization: Bearer … bem formado (uma chave de API do Opik ou um token de acesso OAuth opik_mcp_at_…) é encaminhado literalmente para o opik-backend, que é o ponto único de aplicação de autenticação. Escolha o transporte de acordo com o formato de implantação:

Cenário	Transporte
Cliente MCP e Opik na mesma máquina (instalação OSS local)	stdio (recomendado — mais simples, sem porta, sem configuração OAuth)
Cliente MCP local → Opik remoto (Comet cloud / auto-hospedado)	stdio com `OPIK_API_KEY`, ou HTTP com OAuth (`OPIK_MCP_AS_URL` apontando para o backend)
opik-mcp hospedado atrás da mesma borda que o opik-backend	HTTP — bearers são validados pelo backend por requisição

Nota para instalações OSS locais: o backend OSS não autentica requisições, então um opik-mcp HTTP na frente dele é tão aberto quanto a própria API REST OSS. Mantenha o bind padrão 127.0.0.1 (e prefira stdio) em redes compartilhadas.

Ollie / chamadas longas

Variável	Padrão	Notas
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` para exigir uma aprovação por ação antes que as escritas do Ollie durante o fluxo prossigam. Em hosts que anunciam a capacidade MCP `elicitation`, o usuário vê um prompt sim/não; em hosts mais simples, a solicitação aparece como um erro tipado que você pode reemitir manualmente.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Quanto tempo o prompt de confirmação do Ollie durante o fluxo pode esperar pelo usuário antes de ser tratado como cancelamento. `0` desabilita o limite (apenas debug).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Limite de polling para cold-start do pod do Ollie.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Intervalo de polling para cold-start.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Cadência do watchdog — emite um tick `notifications/progress` quando o pod está silencioso, mantendo os timeouts do host sob controle.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Limite máximo de silêncio do pod antes que `ask_ollie` aborte. `0` desabilita (apenas debug).

Telemetria

Eventos de uso anônimos (apenas tipo de evento + tempo — sem conteúdo de consulta). Um digest SHA-256 da sua chave de API é incluído para que o suporte possa encontrar sua conta; a chave bruta nunca sai do processo. Opt out: OPIK_MCP_ANALYTICS_ENABLED=false.

Variável	Padrão	Observações
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Defina como `false` para desabilitar toda a telemetria.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Substituição para staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Tag em cada evento (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	O receptor usa isso para marcar `on_prem=False`. Instalações on-prem devem substituir por `""` ou seu próprio domínio.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	Tempo limite de conexão HTTP.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	Tempo limite total da requisição HTTP.

Limites conhecidos do host

A especificação MCP permite que os hosts redefinam o tempo limite de chamada de ferramenta em notifications/progress — opik-mcp emite um por evento SSE do Ollie mais um heartbeat de watchdog de 15 segundos. A realidade é desigual:

Claude Code — sem tempo limite de chamada de ferramenta documentado; o heartbeat mantém a chamada viva até message_end. Recomendado.
Cursor — tempo limite rígido de 60s que não é redefinido no progresso (bug upstream). Turnos longos do Ollie falharão. Mantenha as consultas ask_ollie focadas.
MCP Inspector — MAX_TOTAL_TIMEOUT limita a duração total (padrão 60s). Aumente-o na interface do Inspector para operações longas.

Se uma chamada travar, defina OPIK_MCP_LOG_LEVEL=DEBUG — falhas de heartbeat (geralmente desconexões do host) são registradas em opik_mcp.ask_ollie no nível de depuração.

Solução de problemas

OPIK_API_KEY is required to use ask_ollie — a variável não está chegando ao processo do servidor. No Claude Code / Cursor / VS Code, as variáveis de ambiente só se aplicam quando dentro do bloco env da configuração do servidor MCP, não no seu shell. Reinicie o host após editar.

ask_ollie retorna "pod not ready" após 2 minutos — a inicialização a frio do pod do Ollie excedeu OPIK_MCP_POD_READY_TIMEOUT_S. Tente novamente — a segunda chamada geralmente atinge um pod aquecido.

ask_ollie / run_experiment falha com um erro de despacho no Opik auto-hospedado — essas ferramentas estão disponíveis apenas no Comet Cloud. Use read / list / write diretamente no auto-hospedado.

Chamada do Cursor atinge o tempo limite em 60s — bug conhecido do Cursor, não do opik-mcp. Encurte a consulta do Ollie ou execute a mesma operação no Claude Code, que não tem limite rígido.

Desenvolvimento

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

Alvos comuns:

Alvo	O que faz
`make install`	`uv sync --extra dev`
`make run`	Executa o servidor MCP (stdio por padrão).
`make run-dev`	Executa com log DEBUG + uvicorn `--reload`.
`make dev`	Executa via `mcp dev` (wrapper de modo dev do Inspector).
`make inspect`	Inicia o MCP Inspector contra um servidor em execução.
`make test`	`uv run pytest -q`.
`make test-live`	Teste ao vivo ponta a ponta contra `dev.comet.com` (defina `OPIK_API_KEY` + `OPIK_WORKSPACE`).
`make lint`	`ruff check` + verificação de formato.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Layout do repositório:

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

Obter ajuda

Abra uma issue para bugs e solicitações de funcionalidades
Documentação do Opik para documentação do SDK / backend
Comunidade Comet no Slack para perguntas

Atualizando da v2? O servidor TypeScript legado ainda é distribuído no npm como opik-mcp@^2 (npx -y opik-mcp); o código-fonte é preservado em legacy/typescript/. Consulte legacy/typescript/DEPRECATED.md para a política de suporte.

Licença

Apache-2.0.