Opik MCP server advanced setup

uvx opik mcp configure covers the five clients it detects. This page is for everything else: writing the config yourself, checking what each client points at, and the difference between the hosted and local server.

Which setup do I need?

Start from where your Opik runs:

Your Opik	Server to use	What you need
Opik Cloud (`www.comet.com`)	Hosted, or local	Browser sign-in for the hosted server; an API key and workspace for the local one
A dedicated or self-hosted Comet deployment, such as `https://<company>.comet-hosted.com`	Local	An API key, your workspace, and the address you open Comet at
Open-source Opik, such as `http://localhost:5173`	Local	Your Opik URL; no API key

The hosted server does not take API keys: there are no headers to add to its URL. If all you have is an API key, use the local server.

Check what’s configured

Each AI client keeps its own copy of the MCP configuration, and it isn’t updated when your Opik configuration changes. To see what every detected client points at:

uvx opik mcp status

  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 flagged ✗ OUT OF SYNC has drifted from your Opik configuration — re-run uvx opik mcp configure to fix it.

A client keeps its MCP connection for the lifetime of its process. After changing your Opik configuration or re-running setup, restart your AI client so it reconnects.

Hosted or local server

uvx opik mcp configure picks the right one automatically. The difference matters when you configure by hand:

	Hosted server	Local server
Available on	Opik Cloud, and any deployment that provides it	Everywhere, and with `--local-server`
Transport	HTTP at `https://www.comet.com/opik/api/v1/mcp`	`uvx opik-mcp` over stdio
Credentials	Browser sign-in (OAuth); no API key stored	`OPIK_API_KEY` in the client’s config
Workspace	Chosen at sign-in	Written into the client’s config
Needs `uv`	Only for the setup command	Yes, every run

On 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, setup stops rather than guessing — otherwise your agent would read real traces from the wrong workspace and report them confidently. Run uvx opik configure, pick a workspace, then re-run uvx opik mcp configure.

Set it up by hand

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.

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

Every client below asks for the same URL:

Remote MCP server URL

https://www.comet.com/opik/api/v1/mcp

This URL is Opik Cloud’s. Dedicated and self-hosted Comet deployments don’t run the hosted server by default, so the same path on your own address, such as https://<company>.comet-hosted.com/opik/api/v1/mcp, answers 404 Not Found. Use the local server there. Turning on MCP OAuth adds the sign-in routes, not the MCP server itself.

Claude Code

Cursor

VS Code Copilot

Codex

Claude Desktop

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

Or edit ~/.claude.json:

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

Restart Claude Code, complete the browser sign-in, then ask your assistant:

Check it worked

List my Opik projects.

Local server

The local server runs on demand via uvx opik-mcp, with your credentials in the client’s env block.

OPIK_WORKSPACE is optional — omit it and the server uses the default workspace, which is correct for local and OSS installs. Set it only if you connect to a named cloud workspace.

Claude Code

Cursor

VS Code Copilot

Codex

opencode

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:

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

Restart Claude Code and verify with /mcp.

Self-hosted and dedicated deployments

On a dedicated or self-hosted Comet deployment, use the local server and tell it where your Comet is. You need three values:

Variable	Value	Where to find it
`COMET_URL_OVERRIDE`	The address you open Comet at, with no `/opik` and no trailing slash, such as `https://<company>.comet-hosted.com`	Your browser’s address bar. The server adds `/opik/api` itself
`OPIK_API_KEY`	Your API key	Account settings, or the user menu at the top right of Comet
`OPIK_WORKSPACE`	Your workspace name	The address bar, right after `/opik/`

Claude Code

Cursor

Other clients

claude mcp add --transport stdio opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env OPIK_WORKSPACE=<your-workspace> \
  --env COMET_URL_OVERRIDE=https://<company>.comet-hosted.com \
  -- uvx opik-mcp

Or edit ~/.claude.json, or .mcp.json in your project:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>",
        "COMET_URL_OVERRIDE": "https://<company>.comet-hosted.com"
      }
    }
  }
}

Restart Claude Code and verify with /mcp.

Or let the CLI write it. Set OPIK_API_KEY in your environment first; it is not read from the command line:

uvx opik mcp configure --ai-client cursor --deployment self-hosted --local-server \
  --url https://<company>.comet-hosted.com --workspace <your-workspace>

Open-source Opik. Set OPIK_URL to the full Opik REST base instead, such as http://localhost:5173/api, and leave out OPIK_API_KEY and OPIK_WORKSPACE. Use OPIK_URL as well on a Comet deployment where Opik lives at a non-default path.

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

--ai-client takes claude-code (or claude), cursor, vscode, codex, opencode, or all; repeat it for several. --skills installs the skill pack without asking, --no-skills skips it.

Credentials come from ~/.opik.config, or from OPIK_API_KEY and OPIK_WORKSPACE already in the environment, such as a CI secret — do not paste the key into the command line. A saved Opik that needs a key and has none stops and asks for OPIK_API_KEY. With no ~/.opik.config, no OPIK_URL_OVERRIDE or OPIK_API_KEY, and no --deployment, it uses a local Opik that answers at http://localhost:5173.

--deployment picks which Opik to connect to instead, and sets the saved configuration aside for that run. cloud needs no API key: the client signs in through the browser. self-hosted reads the key from OPIK_API_KEY only, and the workspace from --workspace or OPIK_WORKSPACE.

uvx opik mcp configure --ai-client cursor --deployment cloud
uvx opik mcp configure --ai-client cursor --deployment local --url http://opik.internal:5173
uvx opik mcp configure --ai-client cursor --deployment self-hosted --url https://comet.example.com --workspace <workspace>