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.

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

On a self-hosted deployment this is your own Opik API base plus /v1/mcp, and the deployment has to run the MCP OAuth authorization server — it is off by default. See MCP OAuth for the flags. Where it is off, the endpoint has no sign-in routes at all, so use the local server instead.

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 Opik. Add COMET_URL_OVERRIDE to the env block, and OPIK_URL if 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

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. --ai-client takes claude-code, cursor, vscode, codex, opencode, or all; repeat it for several. --skills installs the skill pack without asking, --no-skills skips it.