opik/apps/opik-documentation/documentation/fern/docs-v2/prompt_engineering/mcp-server.mdx at 3b808fe085622833b5528cf06a58700bc2ff4276 · comet-ml/opik

headline	Opik's MCP server
og:description	Configure Opik's Python MCP server with Claude Code, Cursor, VS Code Copilot, Codex, and opencode to read traces, log scores, and manage prompts from your AI host.
og:site_name	Opik Documentation
og:title	Integrate with Opik's MCP server
title	Opik's MCP server

Opik's MCP server connects your AI host (Claude Code, Cursor, VS Code Copilot, Codex, opencode, 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, Codex, opencode), picks the right server for your Opik deployment, configures it, and then checks that the configuration it just wrote actually works.

Prefer not to use the CLI? You can wire up any host by hand — skip to [Manual setup](#manual-setup). The CLI ships with the `opik` Python package. The `opik mcp` commands require **version 2.1.3 or later**:

```bash
pip install --upgrade "opik>=2.1.3"
```

```bash opik mcp configure ```

This reuses your existing Opik configuration (`~/.opik.config`). If you
haven't configured Opik yet, the wizard offers to do it for you first.

`opik configure` also offers to run this for you at the end of its setup,
naming the hosts it found:

> Cursor detected. Register the Opik MCP server with it? (y/N)

The CLI finishes by making a real call with the credentials it wrote, so you already know they work:

```text
Cursor: Added 'opik-mcp' in ~/.cursor/mcp.json
Verified: connected to workspace acme-ai, 7 project(s) visible.
Restart your AI host to pick up the Opik MCP server, then ask it to 'list my Opik projects'.
```

If verification fails, the CLI says why instead of reporting success — a
registered server whose credentials are wrong would otherwise look identical
to a working one until your agent hit a 401 mid-conversation.

<Note>
If your host isn't detected, name it with `--host` (below) or use
[Manual setup](#manual-setup).
</Note>

The skill pack

The MCP server gives your assistant tools. The skill pack gives it the knowledge of how to use Opik — which integration to reach for, how to mark an entrypoint, how to build a test suite, how opik connect works. Most people want both:

opik skills configure

opik configure also offers it after the MCP step:

Install the Opik skill pack for Cursor? It teaches your assistant how to instrument code, run test suites, and use opik connect. (y/N)

Skills are plain SKILL.md directories, and assistants have converged on a shared user-level location, so one install covers all of them:

Assistant	Reads
Cursor, VS Code Copilot, Codex, opencode	`~/.agents/skills` directly
Claude Code	`~/.claude/skills`, which the CLI links to the shared copy

Because this is a user-level install, it is independent of your current directory — there is no project to be inside. It needs no Opik credentials either, so it works before opik configure.

opik skills configure --host codex --host claude-code   # specific assistants
opik skills configure --host all                        # every detected assistant
opik skills status                                      # what is installed
opik skills remove                                      # take it back out

opik configure --install-skills does the same non-interactively, for a Dockerfile or CI.

Already using [`npx skills add comet-ml/opik-skills`](https://github.com/comet-ml/opik-skills)? That writes to the same `~/.agents/skills` location, so the two are interchangeable. `opik skills status` reports a pack it did not install as coming from outside the CLI, and `opik skills configure` will replace it.

Scripts, containers, and coding agents

opik mcp configure only needs a terminal in order to ask which host to use. Name one with --host and it runs headless — which is what makes "set Opik up for me" something a coding agent can do in one step, and what lets the command work in a Dockerfile, a dotfiles repo, or CI:

# One host, no prompts, no terminal required
opik mcp configure --host claude-code

# Several hosts
opik mcp configure --host cursor --host codex

# Every host detected on this machine
opik mcp configure --host all

Valid values are claude-code, cursor, vscode, codex, opencode, and all. Naming a host installs for it whether or not it is currently detected, so a fresh container image can be configured before the editor is installed.

opik configure takes --install-mcp for the same purpose, and it is honoured without a terminal too:

opik configure --install-mcp --install-skills

`opik configure -y` deliberately does **not** register the MCP server: a blanket yes-to-everything should not reach into another tool's configuration files. Pass `--install-mcp` / `--install-skills` when you want them.

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.

A host keeps its MCP connection for the lifetime of its process. After changing your Opik configuration or re-running `opik mcp configure`, **restart your AI host** so it reconnects with the updated settings.

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; if it isn't on your PATH the CLI stops and prints the exact command to install it for your platform.

Workspaces

For the local server your workspace is written into the host's config, so it has to be the right one. If your Opik configuration doesn't name a workspace and your account has more than one, opik mcp configure refuses to continue rather than falling back to your account default:

Your Opik configuration does not name a workspace, but this account has 3:
acme-ai, acme-research, sandbox. The MCP server would fall back to your default
workspace and silently read from the wrong place. Run `opik configure` and choose
a workspace, then re-run `opik mcp configure`.

Guessing here is the one failure this CLI can produce that doesn't look like a failure: your agent would read real traces from the wrong workspace and report them confidently. Run opik configure, pick a workspace, and re-run.

Manual setup

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

There are two servers you can add by hand. [`opik mcp configure`](#quick-setup-with-the-opik-cli) picks the right one for you, but you can also add either directly in your AI host's MCP settings:

Hosted server (HTTP + OAuth) — available on Opik Cloud and any deployment that provides it. No API key is stored; your host signs in through the browser.
Local server (uvx opik-mcp, stdio) — runs on your machine with your credentials in the host's env block.

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.

Add the server with one command:

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

Or edit `~/.claude.json` directly:

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

Restart Claude Code and complete the browser sign-in when prompted, then ask
in the chat: **"list my Opik projects"**.

</Tab>
<Tab title="Cursor">

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

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

Reload Cursor and complete the browser sign-in when prompted.

</Tab>
<Tab title="VS Code Copilot">

Create or open `.vscode/mcp.json` in your workspace:

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

Reload the window and complete the browser sign-in when prompted.

</Tab>

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.

`opik-mcp` is now a Python package. If you previously ran the npx-based JavaScript server, use the `uvx opik-mcp` commands below in place of `npx -y opik-mcp`. `OPIK_WORKSPACE` is **optional** — you can omit the `OPIK_WORKSPACE` line/key entirely and the server uses the `default` workspace (correct for local/OSS installs). The snippets below include it for completeness; set it only if you connect to a named cloud workspace.

Add the server with one command:

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

Or edit `~/.claude.json` directly:

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

Restart Claude Code, verify with `/mcp` (`opik-mcp` should appear as
connected), and then ask in the chat: **"list my Opik projects"**.

</Tab>
<Tab title="Cursor">

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project), or open
**Cmd+Shift+J → Features → Model Context Protocol**:

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

Reload Cursor; the green dot next to `opik-mcp` in the MCP panel confirms
the connection. Ask in chat: **"list my Opik projects"**.

<Tip>
**Cursor 60s timeout.** Cursor enforces a hard tool-call timeout that does
not reset on progress notifications. Long `ask_ollie` turns will fail on
Cursor — see [Known host limits](#known-host-limits).
</Tip>

</Tab>
<Tab title="VS Code Copilot">

Create or open `.vscode/mcp.json` in your workspace (or run the
**MCP: Open User Configuration** command to add it globally):

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

Reload the window. The Copilot Chat **MCP** indicator shows `opik-mcp` once
the server is reachable. Ask in chat: **"list my Opik projects"**.

</Tab>
<Tab title="Codex">

Add the server with one command:

```bash
codex mcp add opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env OPIK_WORKSPACE=<your-workspace> \
  -- uvx opik-mcp
```

Or add an `[mcp_servers.opik-mcp]` table to `~/.codex/config.toml`:

```toml
[mcp_servers.opik-mcp]
command = "uvx"
args = ["opik-mcp"]

[mcp_servers.opik-mcp.env]
OPIK_API_KEY = "<your-key>"
OPIK_WORKSPACE = "<your-workspace>"
```

Confirm with `codex mcp get opik-mcp`, then ask in the chat:
**"list my Opik projects"**.

<Note>
`opik mcp configure --host codex` drives the `codex` CLI rather than editing
`config.toml`, so your comments and formatting are left alone. If the `codex`
CLI isn't on your `PATH` it tells you to add the table by hand instead of
rewriting your TOML.
</Note>

</Tab>
<Tab title="opencode">

Edit `~/.config/opencode/opencode.json` (or the file in
`$OPENCODE_CONFIG_DIR`). Note that opencode uses its own vocabulary: `local`
rather than `stdio`, one `command` list holding the executable and its
arguments, and `environment` rather than `env`:

```json
{
  "mcp": {
    "opik-mcp": {
      "type": "local",
      "command": ["uvx", "opik-mcp"],
      "environment": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      },
      "enabled": true
    }
  }
}
```

Restart opencode, then ask in the chat: **"list my Opik projects"**.

</Tab>
<Tab title="MCP Inspector">

For manual testing or debugging, run the inspector against `opik-mcp`:

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

The inspector opens in your browser and lets you call each tool directly.

</Tab>

**Self-hosted Opik.** Add `COMET_URL_OVERRIDE` to the `env` block (and `OPIK_URL` if Opik lives at a non-default path). `ask_ollie` and `run_experiment` are available on Comet Cloud only — on self-hosted those calls fail at dispatch; use `read` / `list` / `write` directly.

Using the MCP server

The tools at a glance

Tool	Purpose
`read`	Universal read by id / name / `opik://` URI.
`list`	Universal list with optional name filter and pagination.
`ask_ollie`	Investigate or synthesize via the Opik in-product assistant.
`write`	Universal write — log traces/spans, score, comment, save prompts, manage test suites and experiments.
`schema`	Introspect write-operation schemas (used by the LLM to construct valid payloads).
`run_experiment`	Run an evaluation experiment end-to-end via Ollie.

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

Navigation Menu

Uh oh!

Quick setup with the Opik CLI

The skill pack

Scripts, containers, and coding agents

Check your setup

Opik Cloud and self-hosted deployments

Opik Cloud (hosted server)

Self-hosted and local (local server)

Workspaces

Manual setup

Hosted server (Opik Cloud)

Local server (uvx)

Using the MCP server

The tools at a glance

Browsing your workspace

Scoring, commenting, saving prompts

Asking Ollie

Ollie & auto-approve

Known host limits

Example conversation

Uh oh!

FilesExpand file tree

mcp-server.mdx

Latest commit

History

mcp-server.mdx

File metadata and controls

Quick setup with the Opik CLI

The skill pack

Scripts, containers, and coding agents

Check your setup

Opik Cloud and self-hosted deployments

Opik Cloud (hosted server)

Self-hosted and local (local server)

Workspaces

Manual setup

Hosted server (Opik Cloud)

Local server (uvx)

Using the MCP server

The tools at a glance

Browsing your workspace

Scoring, commenting, saving prompts

Asking Ollie

Ollie & auto-approve

Known host limits

Example conversation