Opik's MCP server

One command connects your coding assistant to your traces and teaches it how to create them in the first place. It needs uv and no Opik SDK:

$
uvx opik mcp configure

One click for Cursor and VS Code, or a prompt you paste into any coding agent. All three use the Opik Cloud hosted server and sign in through the browser:

CursorVS CodeInstall prompt

The Cursor and VS Code buttons add the server only. The copied prompt has your agent detect the coding agents on your machine, ask which ones to set up, install the server and the skills for them, and verify with a real call. Another client, or a self-hosted Opik? See Manual setup.

What this unlocks

Things you can ask for and get in one turn, without leaving your editor:

Quick setup with the Opik CLI

The CLI detects your AI client (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.

$
curl -LsSf https://astral.sh/uv/install.sh | sh

1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

$
uvx opik mcp configure

Check your setup

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

$
uvx opik mcp status

It prints your active Opik configuration, then each AI client 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 client:
  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 client that has drifted is flagged ✗ OUT OF SYNC — re-run uvx opik mcp configure to fix it.

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

$
uvx opik configure status

From a script or CI

Setup writes into your AI client’s own configuration, so a run with no terminal writes nothing unless you name the client:

$
uvx opik mcp configure --ai-client cursor --skills

Credentials come from ~/.opik.config or from OPIK_API_KEY and OPIK_WORKSPACE already present in the environment, such as a CI secret; do not paste the key into the command line. --ai-client takes claude-code, cursor, vscode, codex, opencode, or all for every client detected on the machine; repeat it for several. --skills installs the skill pack without asking, --no-skills skips it. A run that names nothing and has no terminal, a CI job or a Docker build, writes nothing.

Start using it

Paste any of these into your assistant. Start with the first — it exercises the whole loop, so if it works, everything is wired up.

Add Opik tracing to this project, then run it and show me the trace you created.

List my Opik projects and tell me which one this repo is logging to.

Look at the last 20 traces in Opik and tell me what's slowest and what's failing.

Build an Opik test suite from my recent traces, then run it and show me the scores.

From then on your assistant can check its own work against real traces every time you change something.

The tools you’ll have

Your assistant gets five tools and picks between them on its own. This is here so you know what it can reach for:

Running an evaluation end to end is the skill pack’s job, not a tool’s: the opik-evaluate skill drives the Opik SDK, and the MCP tools record and read the results. That is why the command above installs both.

To see a payload shape yourself, ask “show me the schema for trace.create” — or read the full list.

Opik Cloud and self-hosted deployments

uvx 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 client signs in with a browser-based OAuth flow on first connect, so:

• No API key is stored in the client’s config — you authenticate through OAuth in the browser.
• uv is only needed for the setup command. There is no local process to run afterwards.
• Your workspace is selected during the OAuth sign-in, so a hosted server shows no workspace in uvx 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 client’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, uvx 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 `uvx opik configure` and choose
a workspace, then re-run `uvx 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 uvx opik configure, pick a workspace, and re-run.

Manual setup

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

On Opik Cloud, any MCP client can take the hosted server in one line:

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

add-mcp writes the URL into Windsurf, Zed, Gemini CLI, Claude Desktop, Goose, Cline, Kiro and a dozen more. The client has to support browser sign-in (OAuth) for remote MCP servers; without it the hosted endpoint answers 401. On a self-hosted deployment, replace the URL with your own API base plus /v1/mcp, or use the local server.

For the skill pack on a client the CLI doesn’t cover, the community skills CLI knows the skill directories for 76+ agents (needs Node.js):

$
npx skills add comet-ml/opik-skills

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 client config. Point your client 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 client’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
}

Example conversation

A typical investigative loop using Claude Code:

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

Claude: (calls list, then read on the failing traces) 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>.

Troubleshooting

Before anything else: run uvx opik mcp status, then start a new session in your client. Most problems end there.

FAQ