Opik's MCP server

Opik’s MCP server connects your AI host (Claude Code, Cursor, VS Code Copilot, MCP Inspector) directly to your Opik workspace — read traces, log scores, save prompt versions, and ask Ollie investigative questions, all from the chat.

Quick setup with the Opik CLI

The fastest way to connect the MCP server is the Opik CLI. It detects your AI host (Claude Code, Cursor, VS Code Copilot), picks the right server for your Opik deployment, and configures it for you.

$
pip install --upgrade "opik>=2.1.3"

$
opik mcp configure

Check your setup

Each AI host keeps its own copy of the MCP configuration, which isn’t updated automatically when your Opik configuration changes. To see what every detected host points at — and whether it still matches your current Opik configuration — run:

$
opik mcp status

It prints your active Opik configuration, then each assistant that has the Opik MCP server configured: the config file it lives in, the server it reports to (hosted or local), its workspace, and whether it has drifted from your Opik configuration.

Your Opik configuration
    File          ~/.opik.config
    Environment   https://www.comet.com/opik/api
    Workspace     my-workspace
Opik MCP server — configured for 1 AI assistant:
  Claude Code
    Config        ~/.claude.json
    Connection    Hosted (HTTP + OAuth)
    Reports to    https://www.comet.com/opik/api/v1/mcp
    Status        ✓ in sync with your Opik configuration

A host that has drifted is flagged ✗ OUT OF SYNC — re-run opik mcp configure to fix it.

To view just your active Opik configuration (file path, environment, workspace):

$
opik configure status

Opik Cloud and self-hosted deployments

opik mcp configure works the same whether you’re on Opik Cloud, self-hosted, or a local install — it sets up the right server for your deployment automatically.

Opik Cloud (hosted server)

On Opik Cloud, the CLI registers the hosted MCP server over HTTP. Your AI host signs in with a browser-based OAuth flow on first connect, so:

• No API key is stored in the host’s config — you authenticate through OAuth in the browser.
• uv is not required — there is no local process to run.
• Your workspace is selected during the OAuth sign-in, so a hosted server shows no workspace in opik mcp status.

Self-hosted and local (local server)

If no hosted server is available for your environment, the CLI sets up the local server, which runs on demand via uvx opik-mcp. This requires uv — install it with brew install uv (macOS) or curl -LsSf https://astral.sh/uv/install.sh | sh.

Manual setup

Prefer to wire it up yourself, or your host wasn’t detected? Configure any host by hand below.

Hosted server (Opik Cloud)

The hosted server connects over HTTP and signs in with a browser-based OAuth flow on first connect — no API key is stored in the host config. Point your host at your deployment’s MCP endpoint, which is your Opik API base plus /v1/mcp. On Opik Cloud that is https://www.comet.com/opik/api/v1/mcp.

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

1
{
2
  "mcpServers": {
3
    "opik-mcp": {
4
      "type": "http",
5
      "url": "https://www.comet.com/opik/api/v1/mcp"
6
    }
7
  }
8
}

Local server (uvx)

The local server runs on demand via uvx opik-mcp (requires uv), with your credentials passed through the host’s env block.

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

1
{
2
  "mcpServers": {
3
    "opik-mcp": {
4
      "type": "stdio",
5
      "command": "uvx",
6
      "args": ["opik-mcp"],
7
      "env": {
8
        "OPIK_API_KEY": "<your-key>",
9
        "OPIK_WORKSPACE": "<your-workspace>"
10
      }
11
    }
12
  }
13
}

Using the MCP server

The tools at a glance

Browsing your workspace

list my Opik projects

what was the most recent trace logged to the “demo” project?

show me trace <trace-id>

Scoring, commenting, saving prompts

score trace <trace-id> 0.9 on helpfulness with reason “great recovery”

comment “retry with temperature=0” on span <span-id>

save the following text as a new version of the “rerank-system” prompt: …

For the full set of write operations and their payload shapes, ask the host “show me the schema for trace.create” (calls the schema tool) or see the README.

Asking Ollie

For investigative or cross-entity questions:

why are spans in the “demo” project slower this week than last?

compare experiments “rerank-v2” and “rerank-v3” on factuality

ask_ollie returns a thread_id you can pass back on follow-ups to preserve context. For more about Ollie itself, see Ollie. See Ollie & auto-approve below before running write-style prompts in shared workspaces.

Ollie & auto-approve

By default, writes that Ollie performs mid-stream (scores, comments, prompt versions, test-suite items) execute without a per-action confirmation step. Each auto-approved write is logged as a JSON audit row on the opik_mcp.audit Python logger.

To require manual confirmation instead, set OPIK_MCP_AUTO_APPROVE=disabled in the server’s env block. Ollie’s confirmation requests then surface as typed errors that you can re-issue manually.

ask_ollie and run_experiment are available on Comet Cloud only — on self-hosted those calls fail at dispatch; use read / list / write directly.

Known host limits

• Cursor enforces a 60-second hard tool-call timeout that does not reset on progress notifications. Long ask_ollie turns will fail on Cursor. For long-running investigations, use Claude Code or VS Code Copilot.

Example conversation

A typical investigative loop using Claude Code:

You: Why did the experiment “gpt-4o-rerank-v3” regress on factuality?

Claude: (calls ask_ollie) Three traces failed because the reranker dropped the system message. The remaining 12 traces scored above 0.8…

You: Score the bottom 3 traces 0.2 with reason “dropped system message”.

Claude: (calls write with score.create ×3) Done — three scores recorded on traces <id-1>, <id-2>, <id-3>.