Comet Opik

oficial

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

GitHub

226

O que você pode fazer com Comet Opik MCP?

Consultar rastros por projeto — Pergunte quais rastros de um projeto falharam hoje, com filtros por informações de erro, duração ou uso de tokens.
Ler qualquer entidade do Opik — Busque um projeto, rastro, span, conjunto de dados, experimento, prompt, thread ou problema de Diagnostics por id, nome ou URI opik://.
Registrar pontuações e comentários — Avalie um rastro com uma métrica de feedback e um motivo, ou adicione comentários por meio da ferramenta de escrita.
Salvar versões de prompts — Crie e armazene novas versões de prompts junto com conjuntos de dados e experimentos.
Inspecionar esquemas de escrita — Peça o esquema de uma operação de escrita para criar um payload válido antes de enviá-lo.
Verificar a saúde do projeto — Leia um projeto para obter a contagem de rastros, a taxa de erros, a duração média e o custo total dos últimos 7 dias.

Documentação

Servidor MCP do Opik

O servidor oficial do Model Context Protocol (MCP) para Opik, a plataforma de observabilidade e avaliação de LLMs de código aberto, desenvolvida pela Comet. Conecte seu host de IA (Claude Code, Cursor, VS Code Copilot, Codex, opencode ou qualquer cliente MCP) diretamente ao seu workspace do Opik: leia traces, registre pontuações e salve versões de prompts, tudo pelo chat.

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

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

Início rápido

Um comando configura o Opik nos clientes de IA da sua máquina, incluindo o Claude Code. Ele encontra seu Opik (o salvo em ~/.opik.config, um em execução no localhost ou pergunta qual você quer), registra o servidor MCP, instala o pacote de skills do Opik e verifica a conexão. No Opik Cloud, não há chave de API para gerenciar: seu cliente faz login no navegador. Ele precisa de uv e nenhum SDK do Opik:

uvx opik@latest mcp configure

Sem usar um terminal, como em um agente de programação ou script, especifique o cliente:

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

--ai-client também aceita codex, cursor, vscode e opencode. Quando executado dessa forma, usa o Opik salvo em ~/.opik.config, incluindo a chave de API, ou um que responda no localhost; caso contrário, para e pergunta por --deployment.

Um agente de programação solicitado a "install opik mcp" obtém todas as etapas, incluindo o que perguntar ao usuário, em uvx opik-mcp@latest --help. Elas são iguais às de Instalar com um agente de programação abaixo.

Registrar o servidor manualmente, usando os comandos do cliente em Configurar manualmente, ignora a verificação de qual Opik você usa e o pacote de skills, por isso é indicado para clientes não compatíveis com o instalador.

Seu Opik	Servidor	Transporte	Login
Opik Cloud (`www.comet.com`)	o servidor hospedado, operado pela Comet	Streamable HTTP	no navegador (OAuth); sem chave de API
Comet auto-hospedado, Opik de código aberto	o servidor local, este pacote	stdio	variáveis de ambiente; chave de API somente quando a implantação exigir

Os clientes carregam servidores MCP quando uma sessão começa, então inicie uma nova sessão depois.

Guia de configuração, solução de problemas e perguntas frequentes: comet.com/docs/opik/mcp-server.

Opik Cloud: o servidor hospedado

A Comet opera o servidor em https://www.comet.com/opik/api/v1/mcp. Seu cliente se conecta por HTTP e abre uma janela do navegador para login na primeira vez. Não há nada para instalar, nenhuma chave de API nem workspace para configurar: o servidor funciona no workspace escolhido durante o login. Depois de adicioná-lo, inicie uma nova sessão e pergunte: "list my Opik projects".

O comando de Início rápido configura isso para Claude Code, Codex, Cursor, VS Code Copilot e opencode, com o pacote de skills. No Claude Code, o plugin faz o mesmo com um único comando. Os botões abaixo adicionam o servidor ao Cursor ou ao VS Code com um clique; outras formas de registrá-lo manualmente estão em Configurar manualmente.

Plugin do Claude Code

O plugin opik instala as skills do Opik e registra o servidor MCP hospedado para o Opik Cloud:

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

No Claude Code anterior à versão 2.1.275, execute /plugin marketplace add comet-ml/opik-mcp, depois /plugin install opik@opik. As skills são carregadas como opik:<skill>, por exemplo opik:opik-instrument, e /mcp mostra o servidor como plugin:opik:opik-cloud. O servidor é o do Opik Cloud. Inicie uma nova sessão e faça login em /mcp → Authenticate. Para uma Comet auto-hospedada que executa o servidor OAuth do MCP, adicione o servidor com claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp; para qualquer outro Opik auto-hospedado ou de código aberto, use o comando de Início rápido. Em seguida, desative plugin:opik:opik-cloud em /mcp. O Claude Code não atualiza automaticamente um plugin deste marketplace: execute /plugin marketplace update opik, depois /plugin update opik@opik, ou ative a atualização automática do marketplace em /plugin. Este marketplace disponibiliza main, que pode estar à frente da última versão. Uma atualização só é disponibilizada quando a versão do plugin muda, a cada lançamento.

Se você já adicionou opik-mcp no mesmo URL, o Claude Code mantém sua cópia e ignora a do plugin. Se a sua for outro servidor, como o servidor local uvx opik-mcp, ambos serão carregados: execute claude mcp remove opik-mcp para manter apenas o do plugin. As skills do pacote de skills também são carregadas junto com as cópias do plugin; remova-as com npx skills remove --global --agent claude-code, que perguntará quais delas.

Opik auto-hospedado e de código aberto: o servidor local

opik-mcp é executado na sua máquina: o cliente o inicia com uvx opik-mcp e se comunica com ele por stdio. O comando de Início rápido configura o servidor a partir do seu ~/.opik.config ou de um Opik local; para registrá-lo manualmente, consulte Configurar manualmente. Instale uv uma vez; ele busca o pacote e, se necessário, o Python 3.13 no primeiro uso:

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

uvx opik-mcp reutiliza a cópia armazenada em cache pelo uv, então inicia rapidamente; uv cache clean opik-mcp faz com que a próxima inicialização busque a versão mais recente. uvx opik-mcp@latest consulta o PyPI a cada inicialização, o que acrescenta cerca de um segundo e meio. O Codex aguarda mcp_optional_startup_grace_ms (1 s por padrão) pelos servidores antes de criar a primeira lista de ferramentas, então uma inicialização mais lenta pode deixar as ferramentas de fora do primeiro turno. Os comandos pontuais deste README (opik mcp configure, opik mcp status, --help, --check) incluem @latest, então nunca executam uma cópia que o uv armazenou em cache há meses.

As variáveis de ambiente apontam o servidor para seu Opik:

Seu Opik	Variáveis de ambiente
Opik de código aberto nesta máquina	`OPIK_URL=http://localhost:5173/api`
Opik de código aberto em um servidor	`OPIK_URL=https://<host>/api`, além de `OPIK_API_KEY` somente se a implantação adicionar autenticação
Plataforma Comet auto-hospedada (a interface do Opik está em `https://<host>/opik`)	`COMET_URL_OVERRIDE=https://<host>`, `OPIK_WORKSPACE`, `OPIK_API_KEY`

O código aberto disponibiliza sua API em /api e tem um único workspace, default, então não precisa de OPIK_WORKSPACE. COMET_URL_OVERRIDE apontaria o servidor para /opik/api, que não é disponibilizado pelo código aberto.
Uma Comet auto-hospedada tem workspaces nomeados. Defina OPIK_WORKSPACE como o segmento após /opik/ no URL do seu Opik; se não for definido, as leituras virão do workspace padrão da sua conta, sem nenhum erro que indique isso.
Uma Comet auto-hospedada que executa o servidor OAuth do MCP (desativado por padrão) pode usar o fluxo hospedado em https://<host>/opik/api/v1/mcp.
Substitua todos os valores. O servidor rejeita um workspace de placeholder, como <your-workspace> ou ${input:OPIK_WORKSPACE}; um URL de placeholder é enviado como está e falha ao conectar.
OPIK_MCP_ANALYTICS_SOURCE="" no bloco env exclui uma instalação auto-hospedada do rótulo de origem cloud-Comet nos eventos de telemetria.

Antes de adicionar o servidor a um cliente, verifique as configurações: execute-o com o mesmo ambiente e --check. Ele faz uma chamada ao Opik e informa o workspace e quantos projetos encontrou, ou o que corrigir com um link para a documentação, e termina com código 0 ou 1. Um cliente não consegue informar isso antes de uma nova sessão: o Claude Code mostra Connected mesmo com uma chave incorreta, e o Codex não inicia nada até lá.

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

Em seguida, registre-o no seu cliente: o servidor local, manualmente.

Instalar com um agente de programação

Para um agente de IA solicitado a instalar o servidor, como em "install opik mcp". O objetivo é registrar o servidor para o Opik do usuário, instalar o pacote de skills do Opik e fazer login. Descubra qual Opik está nesta máquina e pergunte ao usuário somente o que não puder descobrir: uma pergunta por mensagem, aguardando cada resposta antes da próxima. O instalador na etapa 3 faz toda a configuração em uma única execução, então resolva as etapas 1 e 2 antes de executá-lo. uvx opik-mcp@latest --help exibe estas etapas.

Veja o que já existe.
```
uvx opik@latest mcp status
```
Ele mostra o Opik salvo em ~/.opik.config (URL e workspace, nunca a chave) e os clientes que já têm o servidor. No Claude Code, execute também claude mcp list: ele mostra os conectores do claude.ai e as entradas com outros nomes. Ele também exibe o comando de cada entrada, que, no caso de uma entrada npx antiga, pode conter uma chave de API: não a repita.
- Um servidor para https://www.comet.com/opik/api/v1/mcp com qualquer nome, como um conector do claude.ai, significa que ele já está registrado: não adicione outro. Instale apenas o pacote de skills com npx skills add comet-ml/opik-skills -g --all. Vá para a etapa 4 se o servidor aparecer como ! Needs authentication.
- O instalador substitui uma entrada opik-mcp existente sem perguntar, como uma do servidor npx antigo. Pergunte ao usuário antes de executá-lo.
Descubra qual Opik o usuário usa.
- Salvo em ~/.opik.config: use-o e informe ao usuário qual está configurando. O instalador lê essa configuração, incluindo a chave de API, então não peça uma chave.
- Nenhum ~/.opik.config: curl -s http://localhost:5173/api/is-alive/ping. Uma resposta indica um Opik de código aberto nesta máquina. Em um shell isolado, como o do Codex, a ausência de resposta pode significar que o shell não tem acesso à rede, e não que não há um Opik.
- Nenhum dos dois: pergunte e não escolha por conta própria. Um URL do Opik no projeto, como OPIK_URL_OVERRIDE em .env, permite fazer uma pergunta de sim ou não. Caso contrário: "Qual Opik você usa: Opik Cloud (www.comet.com), um Opik de código aberto (seu URL) ou uma plataforma Comet auto-hospedada (seu URL e workspace)?"

Execute o instalador para o cliente em que você está. Ele instala o pacote de skills do Opik junto com o servidor, com ou sem --skills; mantenha a flag no comando que você fornecer ao usuário para executar depois. No Opik Cloud, ele abre o navegador para login e aguarda um minuto, então avise o usuário antes.

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

--ai-client também aceita codex, cursor, vscode e opencode. Para um Opik salvo em ~/.opik.config ou em execução no localhost, execute-o como está: --deployment deixa de lado a configuração salva, incluindo a chave de API. Se nenhum dos dois estiver disponível, adicione a flag correspondente ao Opik que o usuário indicou na etapa 2:

Opik do usuário	Adicione
Opik Cloud, `www.comet.com`	`--deployment cloud`
Opik de código aberto	`--deployment local`, e `--url <url>` quando não estiver no localhost
Plataforma Comet auto-hospedada, `/opik/` no URL	`--deployment self-hosted --url <url> --workspace <workspace>`, com `OPIK_API_KEY` no shell

Se falhar, por exemplo, porque o Opik não responde, informe ao usuário o que foi exibido e o que verificar, como uma VPN ou o URL. Não mude para outro Opik.

Login, para o Opik Cloud. Se o instalador informar que o servidor ainda não está conectado, peça ao usuário para executar claude mcp login opik-mcp ou /mcp em uma sessão do Claude Code, em vez de executá-lo você mesmo: ele aguarda no navegador. Um conector do claude.ai faz login em /mcp. O login solicita um workspace; indique o salvo em ~/.opik.config, se houver.
Conclua. Diga o que foi instalado e o que falta. Mencione o pacote de skills: as skills do Opik, instaladas para todos os projetos, que ensinam o agente a instrumentar, avaliar e depurar com o Opik. Os clientes carregam servidores MCP e skills quando uma sessão começa: peça ao usuário para iniciar uma nova sessão e, em seguida, testar "list my Opik projects".

Em todos os casos:

Não peça ao usuário para colar uma chave de API no chat. O servidor hospedado não precisa de nenhuma; caso contrário, obtenha-a do ambiente do shell ("$OPIK_API_KEY") ou deixe o usuário executar o comando.
Não adivinhe o workspace. Ele é o segmento após comet.com/opik/ (ou /opik/ em uma Comet auto-hospedada) no URL do Opik do usuário.
Não exiba ~/.claude.json nem ~/.opik.config: ambos podem conter chaves de API. uvx opik@latest mcp status e claude mcp list mostram o que você precisa, e o instalador lê a configuração diretamente.
Se uma verificação de permissões bloquear um comando, não tente contorná-la. Forneça ao usuário o comando para executar (no Claude Code, ! antes de executá-lo pelo prompt). Para um cliente que o instalador não conhece, faça o registro manualmente com os comandos em Configure manualmente: o servidor hospedado para o Opik Cloud e o servidor local para os demais.
Antes de registrar o servidor local, execute-o com o ambiente que você vai passar e --check, com OPIK_API_KEY exportado no shell, em vez de escrito no comando: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Ele termina com código 0 e informa o workspace que detectou ou mostra o que precisa ser corrigido. Depois do registro, o Claude Code informa Connected mesmo com uma chave incorreta, e o Codex não faz nenhuma verificação.
O Claude Code se recusa a adicionar uma entrada opik-mcp já existente, então remova-a primeiro com claude mcp remove opik-mcp --scope user; o add do Codex a substitui.
Depois do registro, no Claude Code, leia apenas a linha de status: claude mcp get opik-mcp | grep Status. A saída completa exibe o bloco env, incluindo a chave da API. O servidor hospedado mostra ! Needs authentication até que claude mcp login opik-mcp seja executado. O Codex não tem nada que inicie o servidor antes de uma sessão; codex mcp get opik-mcp mostra o que foi armazenado, com os valores do ambiente ocultos.

Configure manualmente (sem verificação do Opik, sem pacote de skills)

O comando Início rápido faz tudo isso para Claude Code, Codex, Cursor, VS Code Copilot e opencode, além de verificar qual Opik você usa e instalar o pacote de skills. Faça o registro manualmente apenas para outro cliente ou para ver o que o instalador grava. Um agente de programação que instala para um usuário executa o instalador: consulte Instalar com um agente de programação.

Servidor hospedado (Opik Cloud)

Claude Code, manualmente

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

Em seguida, entre em /mcp → Authenticate em uma sessão do Claude Code. Uma janela do navegador será aberta, então a pessoa no teclado deve concluir o processo; no próprio terminal, claude mcp login opik-mcp faz o mesmo. --scope user disponibiliza o servidor em todos os projetos; sem essa opção, o Claude Code o registra apenas para o diretório atual. Por SSH, claude mcp login opik-mcp --no-browser exibe a URL de login para abrir na sua própria máquina; a última etapa precisa de um terminal interativo (ssh -t).

Codex, manualmente

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

add abre a tela de login; codex mcp login opik-mcp abre-a novamente. Em ~/.codex/config.toml, o mesmo servidor é:

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

Cursor, manualmente

Use o botão abaixo de servidor hospedado ou adicione a ~/.cursor/mcp.json:

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

VS Code Copilot, manualmente

Use o botão abaixo de servidor hospedado ou adicione a .vscode/mcp.json no workspace ou à sua mcp.json de usuário (MCP: Open User Configuration):

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

Outros clientes

Qualquer cliente que aceite uma URL pode usar o servidor hospedado:

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

Um cliente que só consiga iniciar comandos locais pode acessá-lo por meio de npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp.

Opik Cloud com uma chave de API

Quando ninguém puder concluir o login pelo navegador, como quando um agente é executado sem supervisão por um script ou um cliente não tem suporte a MCP OAuth, use uma chave de API de comet.com/api/my/settings/ em vez disso, com o servidor local apontado para o Opik Cloud:

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

Os outros clientes recebem as mesmas duas variáveis no bloco env. Defina OPIK_WORKSPACE como o segmento após comet.com/opik/ na URL do Opik (https://www.comet.com/opik/acme-ai/projects → acme-ai). Se omitido, o servidor envia default, que o Comet resolve para o workspace padrão da sua conta, então as leituras podem vir do workspace errado sem gerar um erro.

Servidor local (Opik auto-hospedado e de código aberto)

Os exemplos usam uma instância local do Opik de código aberto. Para um Comet auto-hospedado, substitua pelas três variáveis da tabela. Depois de adicionar o servidor, inicie uma nova sessão e pergunte: "list my Opik projects".

Claude Code, manualmente

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

Em um Comet auto-hospedado, com a chave no OPIK_API_KEY do 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

Ou edite ~/.claude.json diretamente:

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

claude mcp get opik-mcp mostra ✔ Connected quando o servidor inicia. Isso não comprova que a URL ou a chave estejam corretas, pois somente uma chamada de ferramenta chega ao Opik; --check (o servidor local) faz isso. Ele também exibe o bloco env, incluindo a chave da API.

Codex, manualmente

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

Ou edite ~/.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

O Codex fornece a um servidor local apenas as variáveis em env e os nomes em env_vars, então uma chave exportada no shell não chega até ele de outra forma.

Cursor, manualmente

Adicione a ~/.cursor/mcp.json (global) ou à .cursor/mcp.json (projeto), ou use Cmd+Shift+J → Features → Model Context Protocol:

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

Limite de 60 s do Cursor. O Cursor impõe um tempo limite rígido para chamadas de ferramentas que não é reiniciado com notificações de progresso. Consulte Limites conhecidos dos hosts.

VS Code Copilot, manualmente

Adicione a .vscode/mcp.json no workspace ou à sua mcp.json de usuário (MCP: Open User Configuration):

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

MCP Inspector (testes manuais)

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

Vindo de `npx opik-mcp`?

O servidor TypeScript (npm opik-mcp@2) está obsoleto e deixará de atender solicitações em 2026-11-15. Para uma nova instalação, execute o comando de Início rápido; uvx opik-mcp é o comando que um cliente executa para iniciar o servidor, não um instalador. Para migrar uma configuração existente no Opik Cloud, mude para o servidor hospedado e remova a chave da API. Caso contrário, na configuração do cliente MCP, substitua npx -y opik-mcp por uvx opik-mcp. Algumas variáveis de ambiente foram renomeadas e as flags de linha de comando não são mais lidas: consulte o guia de migração. Política de suporte: DEPRECATED.md. O código-fonte TypeScript está na tag git legacy-typescript-final.

Ferramentas

opik-mcp expõe uma interface pequena e orientada a resultados que cobre todo o ciclo de vida (ler → anotar → organizar → criar → iterar).

Ferramenta	Finalidade
`read`	Leitura universal por ID / nome / URI `opik://`
`list`	Listagem universal com filtro de nome opcional + paginação
`write`	Gravação universal — registrar traces/spans, pontuar, comentar, salvar prompts, gerenciar datasets e experimentos
`schema`	Inspecionar esquemas de operações de gravação (usados pelo LLM para construir payloads válidos)
`read_skill`	Ler uma das skills de agente do Opik incluídas neste servidor

`read`

Uma ferramenta para qualquer pergunta do tipo "mostre X". Recebe um entity_type e um id (UUID ou, para tipos que podem ser nomeados, um nome) ou uma URI opik:// completa. Leituras compostas (trace, prompt, thread, agent_insights_issue) incluem os itens filhos, para que uma única chamada retorne o quadro completo.

O registro que você nomeia é retornado por inteiro. Os itens filhos incluídos não: seus corpos são obtidos com o truncate=true do backend, então um campo com mais de ~10 KB é truncado no ClickHouse e imagens base64 são substituídas por "[image]" — repetir um anexo em 200 spans custaria mais do que todo o restante da leitura. A resposta informa isso em spanBodies / messageBodies, e qualquer item filho pode ser obtido por inteiro novamente por meio de seu próprio read("span", id) ou read("trace", trace_id), que acessam endpoints sem nenhum parâmetro truncate.

Uma coleção incluída também tem um limite de tamanho: 200 spans, 200 turnos, 100 versões de prompt. Acima disso, spansTruncated / messagesTruncated / versionsTruncated é true, e uma linha moreSpans / moreMessages / moreVersions ao lado informa a quantidade e a chamada list(...) exata para continuar de onde a parte incluída parou.

Entidades compatíveis: project, trace, span, dataset, dataset_item, experiment, prompt, thread, agent_insights_issue. A busca por nome está disponível para project, experiment, prompt, dataset (mais lenta — duas chamadas de API — e pode retornar várias correspondências). thread e agent_insights_issue são vinculados a um projeto: passe project_id ou project_name, ou um link/URI que inclua o projeto. dataset e dataset_item eram chamados de test_suite e test_suite_item; os nomes antigos ainda funcionam, mas não são divulgados, e o código novo deve usar os novos.

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

Um link copiado da interface do Opik funciona como id: um link de thread ou de uma página de Diagnostics inclui o projeto, então não é necessário project_id, e o tipo de entidade é obtido do link.

Uma leitura de project responde "como está o desempenho do meu projeto" em uma única chamada. Ela retorna {project, summary, vocabulary, contains, url}: o registro e, em seguida, os quatro indicadores exibidos como cartões na página Logs (contagem de traces, taxa de erros, duração média, custo total) dos últimos 7 dias em comparação com os 7 anteriores, somente tráfego do SDK, como na tela. since / until alteram esse período; since="30d" é o que a interface abre por padrão. Uma taxa ou média em um período sem traces é retornada como null, pois 0% de erros em uma semana sem tráfego parece indicar uma semana saudável.

vocabulary é o mapa necessário antes de fazer qualquer outra pergunta: os nomes das pontuações de feedback do projeto, as chaves de uso de tokens e as regras de automação que pontuam seus traces. Esses são os nomes usados em um filtro ou em series= abaixo, e adivinhá-los retorna uma página vazia que parece uma boa notícia. Os nomes das pontuações e as regras têm limite, mas o total real é sempre informado, junto com a chamada que retorna o restante; as chaves de uso são listadas por completo, pois nada mais as enumera. contains informa o experimento, o dataset, a versão de prompt e a execução de otimização mais recentes, para que "o que tem acontecido aqui" não exija mais quatro chamadas. Uma parte que não pôde ser carregada informa isso em vez de parecer vazia, e uma parte vazia é omitida.

Uma leitura de agent_insights_issue retorna {issue, example_trace_ids, details}: o registro do problema de Diagnostics (nome, descrição, causa, correção sugerida, gravidade, status), os IDs deduplicados dos traces que o apresentam (a mesma amostra exibida na página Diagnostics — abra um deles com read("trace", id)) e a divisão por dia. Os corpos dos traces não são incluídos, então a leitura continua sendo uma única chamada ao backend. since / until restringem as linhas por dia; o padrão é todo o período. Quando o servidor conhece a URL do Opik e o workspace da sessão, a leitura também inclui url (a página Diagnostics do problema) e trace_url_template (um link direto para qualquer um dos traces de exemplo), para que o assistente possa fornecer algo clicável; em uma sessão OAuth cujo workspace não pôde ser resolvido, os links são omitidos em vez de serem adivinhados.

Os traces não têm URL — não é possível derivar um link para eles dos campos retornados por read ou list, e um formato adivinhado resulta em 404. Em vez disso, as instruções da sessão especificam um modelo para ele, .../v1/session/redirect/projects/?trace_id={trace_id}&path=..., para que o assistente preencha um ID e forneça um link. Ele passa pelo redirecionamento do opik-backend, que resolve o projeto e o workspace a partir do trace, então funciona onde uma URL direta do projeto não funciona, inclusive em uma sessão OAuth com workspace não resolvido. É o mesmo link que o SDK Python imprime para um trace.

`list`

Navegue ou pesquise uma coleção com paginação. Os tipos vinculados a um projeto (trace, span, thread, agent_insights_issue, dataset_item, prompt_version) precisam do item pai: um UUID ou nome de projeto, um UUID de dataset ou um UUID de 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"')

Filtros. trace, span, thread, experiment e dataset_item aceitam uma string OQL, com a mesma gramática de search_traces(filter_string=…) do SDK:

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

Strings ficam entre aspas duplas, números não levam aspas, duration é expresso em milissegundos, datas são instantes ISO-8601 com fuso horário ("2026-09-08T10:00:00Z"). Pontuações e dicionários recebem uma chave: feedback_scores.accuracy < 0.5, metadata.environment = "prod". AND é o único conector.

Assim como na página Logs da interface, as listas de traces, spans e threads adicionam source = "sdk" para manter traces de avaliadores, playground e experimentos fora do caminho; informe source por conta própria para vê-los. A primeira linha da saída repete o filtro aplicado.

Um filtro inválido falha antes de chegar ao backend e informa o que é necessário para corrigi-lo: a posição de um erro de sintaxe, o nome de campo mais próximo, os operadores válidos para o tipo do campo ou o formato de valor esperado. Campos com um conjunto fechado de valores (source, span type, thread status, visibility_mode) também são verificados com base nele, incluindo cada elemento de uma lista in. source é o único que o backend valida por conta própria, e ele responde com 500 em vez de 400 para um valor desconhecido, então source = "SDK" seria, de outra forma, um erro de servidor opaco para uma letra maiúscula. Os demais são comparados como strings e respondem com uma página vazia, que significa "nenhuma correspondência" quando, na verdade, quer dizer "valor inexistente". Consulte schema("list.trace") (ou list.span, list.thread, list.experiment) para a referência completa dos campos, incluindo os valores aceitos.

Encontrar um caso em um dataset. list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key> para as chaves com as quais o dataset foi criado, full_data para uma substring de todo o payload (uma varredura completa — informe uma chave quando puder), além de id, tags, source, trace_id, span_id e os timestamps. data.<key> aceita apenas os seis operadores de string (=, !=, contains, not_contains, starts_with, ends_with); o backend responde com 400 a uma comparação, então ela é recusada antes da chamada. O endpoint não oferece ordenação nem busca de texto livre — sort é recusado em vez de ser descartado. read(entity_type="dataset_item", id=…) retorna um caso completo, permitindo recuperar um valor que a tabela cortou.

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

Com experiment_ids, a mesma lista passa a ser a comparação — os casos com cada execução anexada — e filtra pelas execuções (feedback_scores.<name>, output, duration). São dois conjuntos de campos diferentes em dois endpoints do backend: schema("list.dataset_item_case") são os próprios casos do dataset, schema("list.dataset_item") é a comparação.

Ordenação. trace, span, thread e experiment aceitam sort="<field> [asc|desc]", desc por padrão e apenas um campo: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". O campo é verificado em relação à lista de campos ordenáveis da entidade antes da chamada, porque o backend ignora silenciosamente os campos pelos quais não pode ordenar. Em workspaces muito grandes, o backend descarta a ordenação por completo; o cabeçalho informa quando isso acontece.

dataset_item só ordena uma comparação (com experiment_ids): o endpoint de itens não aceita parâmetro de ordenação, então uma ordenação em uma listagem simples é recusada em vez de ser descartada.

Intervalo de tempo e busca. trace, span e thread aceitam since e until, cada um como um intervalo relativo ("30m", "1h", "7d") ou um instante ISO-8601 com fuso horário, então "a última hora" não exige cálculos de horário. O intervalo é definido pelo horário de criação do registro, que é barato para o backend e corresponde a start_time com poucos segundos de diferença para tráfego em tempo real. Para um limite exato, coloque start_time em filters. Os mesmos três tipos aceitam search, texto livre que corresponde a qualquer parte do id, nome, entrada, saída, metadados, tags e id da thread. A busca varre todo o projeto no backend, então a primeira chamada em um projeto grande pode levar dezenas de segundos. Essas chamadas têm timeout de 60 segundos. Adicionar since as torna rápidas novamente.

Leitura da tabela. As durações são identificadas como duration_ms / ttft_ms e exibidas em milissegundos inteiros; o campo continua sendo duration em filters e sort. Os timestamps são exibidos até o segundo e os custos como decimais simples. As linhas de projeto incluem last_updated_trace_at para que você veja qual projeto tem tráfego em tempo real; as linhas de thread incluem a primeira mensagem. Uma página vazia com um intervalo de tempo informa quando o último trace do projeto foi registrado, e uma página vazia com o source = "sdk" padrão explica como ver as outras fontes. Um project_name com erro de digitação retorna o nome existente mais próximo.

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

Problemas de diagnóstico. agent_insights_issue é a página Diagnostics acessada pelo MCP: as falhas recorrentes que a tarefa Diagnostics do Opik agrupou para um projeto, ordenadas como na interface (as vistas mais recentemente aparecem primeiro). As colunas são severity, status, total_occurrences (soma de todo o período), latest_count (o dia do relatório mais recente, o número mencionado na descrição do próprio problema) e last_seen. Por padrão, os problemas abertos são listados; passe status="resolved" ou "closed" para ver os demais. read e list também aceitam issue, que é como a interface chama esses itens; o nome longo é o que consta no enum entity_type, para que essa entidade não apareça duas vezes. As contagens abrangem todo o período para corresponder à interface; o mesmo since / until usado para traces restringe o intervalo, truncado para dias de relatório em UTC porque Diagnostics agrega os dados por dia.

Uma lista vazia explica por que está vazia, pois, sem isso, "nada está quebrado" e "ninguém ativou o Diagnostics" parecem a mesma coisa. Há cinco estados: Diagnostics não está disponível nesta implantação, não está ativado para este projeto, foi desativado, está ativado mas não foi verificado recentemente ou está ativado e sem problemas, com o horário da última verificação. Os estados em que você pode agir indicam a chamada a fazer, e todos os estados incluem um link para a página Diagnostics do projeto.

Uma lista não vazia informa o período. Os problemas são os que a última verificação agrupou, então a resposta termina com Report covers data through <time>; quando o intervalo solicitado ultrapassa esse período, ela indica o trecho não coberto e como completá-lo: com um acionador, quando uma nova verificação abranger um período suficientemente longo; caso contrário, com traces brutos usando o since fornecido. Se você pedir uma semana para um projeto verificado todas as noites, o último dia não estará na resposta agrupada; é isso que esta mensagem explica.

write("agent_insights_job.enable", {"project_name": "demo"}) ativa o Diagnostics. A partir daí, ele verifica diariamente, e é seguro chamar novamente. write("agent_insights_job.trigger", …) verifica agora as últimas 24 horas, sem esperar pela execução noturna. Ambos exigem a mesma permissão necessária para ler os problemas, e ambos são recusados quando a implantação não oferece Diagnostics.

Um problema avança em seu ciclo de vida com write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) — tratado — ou …close quando não vale a pena agir, e …reopen para colocar qualquer um deles de volta na lista de abertos. Os três exigem a mesma permissão e respondem com um link para a visualização para a qual o problema foi movido, já que um problema resolvido não aparece mais na página padrão. Decidir se uma falha foi corrigida é uma questão de julgamento, então essas ações devem ser feitas quando você pedir: o assistente não deve organizar a lista enquanto faz a triagem.

Métricas ao longo do tempo. project_metric exibe uma métrica de um projeto como uma tabela de intervalos de tempo: contagens de traces, spans e threads, durações, taxas de erro, custos, uso de tokens e pontuações de feedback. Ela responde à pergunta que vem depois da visão geral: quando algo mudou?

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

As linhas são intervalos de tempo, não registros, então page, size e sort são recusados em vez de ignorados. interval é hourly, daily, weekly ou total; se omitido, acompanha o intervalo como a aba Metrics — por hora até 3 dias, por dia até 30 e por semana além disso —, então um gráfico padrão tem algumas dezenas de linhas, qualquer que seja o intervalo, e um mês por hora (721 linhas) é algo que você precisa solicitar. since / until aceitam os mesmos formatos usados em todos os outros lugares e têm como padrão os últimos 7 dias. filters usa os campos da entidade à qual a métrica se refere, então uma métrica de span é filtrada pelos campos de span.

breakdown divide cada intervalo por tags, name, error_info, error_type, model, provider, span_type, guardrail_name ou metadata.<key>. Nem todas as métricas aceitam todas essas opções, e sete não aceitam nenhuma; a ferramenta sabe quais são e informa isso antes de chamar o backend, indicando uma métrica que responda à mesma pergunta, quando houver. Três famílias retornam várias séries de uma só vez (uma duração como p50/p90/p99, uma pontuação de feedback por nome, uso de tokens por chave), e o backend exibe apenas uma delas por vez ao agrupar, então series= a seleciona: um percentil, um nome de pontuação ou uma chave de uso. A duração tem como padrão p50 e o uso de tokens, total_tokens; o valor usado é repetido na primeira linha.

Intervalos vazios são omitidos e contabilizados abaixo, então um mês tranquilo resulta em algumas linhas, em vez de uma coluna de zeros, e uma taxa em um intervalo sem traces fica ausente, em vez de ser informada como zero.

Consulte schema("list.project_metric") para ver a tabela de métricas, os intervalos e a matriz de agrupamento por métrica.

Nomes de um projeto. score_name lista os nomes de pontuações de feedback registrados em um projeto, e online_rule lista os avaliadores de regras de automação configurados nele, que são a origem da maioria desses nomes. Ambos são as mesmas listas que read("project", …) fornece, completas e paginadas, para quando a versão limitada da visão geral não for suficiente.

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

`write`

Dispatcher universal de gravação. Passe operation + data e o dispatcher valida o payload, aplica o verbo REST apropriado e retorna a resposta do backend.

Operações:

Operação	O que faz
`trace.create`	Registra um trace (ou um lote). É o pai de spans / pontuações / 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 uma pontuação numérica de feedback a um trace, span ou thread.
`comment.create`	Anexa um comentário em 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).
`dataset.create`	Cria um dataset — `type: "test_suite"` o transforma em um conjunto de testes de avaliação.
`dataset_item.upsert`	Insere ou atualiza itens em um dataset (sempre no formato envelope).
`experiment.create`	Cria um experimento associado a um dataset.
`experiment_item.create`	Anexa linhas de trace + dataset_item a um experimento.
`thread.close`	Fecha uma thread (marca-a como inativa). Passe `thread_id` e o projeto.
`thread.open`	Reabre uma thread fechada. Passe `thread_id` e o projeto.
`agent_insights_job.enable`	Ativa o Diagnostics para um projeto (verificações diárias, seguro repetir).
`agent_insights_job.trigger`	Executa agora uma verificação do Diagnostics, abrangendo as últimas 24 horas.
`agent_insights_issue.resolve`	Marca um problema do Diagnostics como tratado (pergunte ao usuário primeiro).
`agent_insights_issue.close`	Marca um problema do Diagnostics como não valendo a pena tratar (pergunte ao usuário primeiro).
`agent_insights_issue.reopen`	Coloca um problema do Diagnostics resolvido ou fechado de volta na lista de abertos.
`annotation_queue.create`	Cria uma fila de anotação de um projeto, opcionalmente com uma visualização personalizada para o anotador.
`annotation_queue.update`	Altera uma fila de anotação; define, substitui ou limpa a visualização do anotador.

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

`schema`

Inspecione o formato JSON exato e os campos obrigatórios de qualquer operação de gravação 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")

A mesma ferramenta responde a list.trace, list.span, list.thread e list.experiment com a referência da ferramenta list para essa entidade: todos os campos filtráveis com seus tipos e operadores válidos, os campos classificáveis, se uma janela de tempo e uma busca de texto livre se aplicam, e dois filtros de exemplo.

schema(operation="list.trace")

Configuração

Estas configurações definem o servidor local; cada configuração é uma variável de ambiente. O servidor hospedado no Opik Cloud não usa nenhuma delas.

Identidade / endpoint

Variável	Padrão	Observações
`OPIK_API_KEY`	—	Chave de API, para um Comet auto-hospedado ou para o Opik Cloud sem o servidor hospedado. O Opik de código aberto não precisa de nenhuma, a menos que a implantação adicione autenticação.
`OPIK_WORKSPACE`	unset	Nome do workspace. Na nuvem, com uma chave de API, se não estiver definido, envia `default`, que resolve para o workspace padrão da sua conta — defina-o explicitamente se você trabalha em outro workspace, ou as leituras virão silenciosamente do workspace errado. Deixe sem definir com OAuth (o token o contém) e no local/OSS (`default` é o único workspace nesses casos).
`COMET_WORKSPACE`	—	Alias obsoleto de `OPIK_WORKSPACE` (compatibilidade retroativa). `OPIK_WORKSPACE` tem prioridade se ambos estiverem definidos.
`COMET_WORKSPACE_ID`	unset	UUID opcional do workspace. Incluído nos eventos de análise quando definido e tem precedência sobre o valor resolvido. Raramente necessário — instalações OAuth obtêm o UUID automaticamente do token.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Defina como o host do seu Comet auto-hospedado ou como `https://dev.comet.com` para staging.
`OPIK_URL`	derivado de `COMET_URL_OVERRIDE` + `/opik/api`	Defina para o Opik de código aberto, que disponibiliza sua API em `/api` (`http://localhost:5173/api` localmente). Em uma plataforma Comet, substitua apenas se o Opik estiver em um host/caminho diferente da interface do Comet.
`OPIK_DEFAULT_PROJECT_NAME`	unset	Quando definido, o bloco `instructions` por sessão instrui o LLM a passar esse valor como `project_name` em cada chamada de ferramenta, a menos que o usuário especifique outro projeto.

Servidor / transporte

Variável	Padrão	Observações
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` para inicialização pelo host, `streamable-http` para escutar em uma porta.
`OPIK_MCP_HOST`	`127.0.0.1`	Host de bind do uvicorn (`streamable-http` apenas).
`OPIK_MCP_PORT`	`8080`	Porta de bind do uvicorn (`streamable-http` apenas).
`OPIK_MCP_RELOAD`	`false`	`true` para habilitar `--reload` do uvicorn (somente desenvolvimento).
`OPIK_MCP_AS_URL`	unset	URL do servidor de autorização OAuth, anunciada em `/.well-known/oauth-protected-resource` (RFC 9728) e usada como destino do proxy para sondagens de descoberta do AS. Necessária para que hosts MCP iniciem o fluxo OAuth por HTTP.
`OPIK_MCP_RESOURCE_URI`	unset	URI pública canônica deste servidor, anunciada como `resource` nos metadados do recurso protegido e usada para derivar a indicação `WWW-Authenticate`.
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	Por quanto tempo uma resposta "válida" da introspecção de token do opik-backend é considerada confiável antes que a próxima solicitação com o mesmo token OAuth consulte novamente. Limita a carga adicional no backend causada pela validação por solicitação e o período em que um token expirado ainda é encaminhado (esse período também termina na primeira resposta 401 do backend). Limitado pelo próprio `expires_at` do token quando o backend informa um valor.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Nível de registro do logger stderr.

Escolha de um transporte

Dois formatos de bearer, dois contratos para o transporte HTTP. Um token de acesso OAuth opik_mcp_at_… é validado em cada solicitação pelo endpoint de introspecção de token do opik-backend (em cache, consulte OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S); um token expirado ou revogado recebe HTTP 401 com WWW-Authenticate: Bearer error="invalid_token", que é o que os hosts MCP usam para acionar a concessão silenciosa refresh_token. Uma chave de API do Opik não é validada localmente: ela é encaminhada sem alterações ao opik-backend, que é seu único ponto de aplicação. Escolha o transporte de acordo com o formato da implantação:

Cenário	Transporte
Opik Cloud	Não é preciso executar nada: o servidor hospedado é este servidor por HTTP, executado pela Comet
Cliente MCP e Opik na mesma máquina (instalação OSS local)	stdio (recomendado — mais simples, sem porta nem configuração de OAuth)
Cliente MCP local → Opik auto-hospedado	stdio com as variáveis de ambiente da implantação ou HTTP com OAuth (`OPIK_MCP_AS_URL` apontando para o backend)
opik-mcp servido atrás da mesma borda que o opik-backend	HTTP — os bearers são validados pelo backend em cada solicitação

Observação para instalações OSS locais: o backend OSS não autentica solicitações, portanto um opik-mcp HTTP à sua frente fica 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.

Telemetria

Variável	Padrão	Observações
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Defina como `false` para desativar toda a telemetria que não seja do Sentry.
`OPIK_MCP_SENTRY_ENABLED	`true`	Set to `false` para desativar toda a telemetria do Sentry.
=======

Limitações conhecidas dos hosts

Os hosts diferem no tempo que permitem que uma única chamada de ferramenta seja executada:

Claude Code — não há tempo limite documentado para chamadas de ferramenta. Recomendado.
Cursor — tempo limite rígido de 60s que não é reiniciado com o progresso (bug upstream).
MCP Inspector — MAX_TOTAL_TIMEOUT limita a duração total (padrão: 60s). Aumente esse valor na interface do Inspector para operações longas.

Se uma chamada travar, defina OPIK_MCP_LOG_LEVEL=DEBUG para obter o log completo da solicitação.

Solução de problemas

A configuração funciona? Execute o servidor com o ambiente da configuração do cliente e --check: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Ele informa o workspace e os projetos que encontra ou diz o que corrigir. Os próprios erros do servidor também indicam o que alterar e incluem um link para a página de documentação correspondente.

OPIK_API_KEY não é detectado — 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 estão dentro do bloco env da configuração do servidor MCP, não no shell; o Codex também encaminha os nomes listados em env_vars. Inicie uma nova sessão depois de editar, pois os clientes leem a configuração quando a sessão começa.

As solicitações vão para /opik/api em um Opik de código aberto — COMET_URL_OVERRIDE é para uma plataforma Comet auto-hospedada. O código aberto disponibiliza sua API em /api: defina OPIK_URL=http://localhost:5173/api (ou https://<host>/api) em vez disso. O servidor avisa sobre isso na inicialização quando o host é esta máquina, e --check responde "No Opik API at …".

A chamada do Cursor expira após 60s — é um bug conhecido do Cursor, não do opik-mcp. Reduza o escopo da chamada (um size menor, uma janela mais restrita) ou execute a mesma operação no Claude Code, que não tem limite rígido.

Servidor não aparece, login não abre, workspace errado, uvx não encontrado. Esses casos são abordados na seção de solução de problemas da documentação. uvx opik@latest mcp status lista todos os clientes que têm o servidor configurado e informa se a configuração de cada um está desatualizada.

Desenvolvimento

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

Alvos comuns:

Alvo	O que faz
`make install`	`uv sync --locked --extra dev`
`make run`	Executa o servidor MCP (stdio por padrão).
`make run-dev`	Executa com registro DEBUG + `--reload` do uvicorn.
`make dev`	Executa via `mcp dev` (wrapper de modo de desenvolvimento do Inspector).
`make inspect`	Inicia o MCP Inspector conectado a um servidor em execução.
`make test`	`uv run pytest -q`.
`make lint`	`ruff check` + verificação de formatação.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Estrutura do repositório:

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

Obter ajuda

Abra uma issue para bugs e solicitações de recursos
Documentação do Opik para documentação do SDK / backend
Slack da comunidade Comet para dúvidas

Licença

Apache-2.0.

Comet Opik

O que você pode fazer com Comet Opik MCP?

Documentação

Servidor MCP do Opik

Início rápido

Opik Cloud: o servidor hospedado

Plugin do Claude Code

Opik auto-hospedado e de código aberto: o servidor local

Instalar com um agente de programação

Configure manualmente (sem verificação do Opik, sem pacote de skills)

Servidor hospedado (Opik Cloud)

Claude Code, manualmente

Codex, manualmente

Cursor, manualmente

VS Code Copilot, manualmente

Outros clientes

Opik Cloud com uma chave de API

Servidor local (Opik auto-hospedado e de código aberto)

Claude Code, manualmente

Codex, manualmente

Cursor, manualmente

VS Code Copilot, manualmente

MCP Inspector (testes manuais)

Vindo de npx opik-mcp?

Ferramentas

read

list

write

schema

Configuração

Identidade / endpoint

Servidor / transporte

Escolha de um transporte

Telemetria

Limitações conhecidas dos hosts

Solução de problemas

Desenvolvimento

Obter ajuda

Licença

Vindo de `npx opik-mcp`?

`read`

`list`

`write`

`schema`