opik-cloud

Opik MCP Server

The official Model Context Protocol (MCP) server for Opik, the open-source LLM observability and evaluation platform, built by Comet. Plug your AI host (Claude Code, Cursor, VS Code Copilot, Codex, opencode, or any MCP client) directly into your Opik workspace: read traces, log scores, and save prompt versions, all from the chat.

Built for LLM engineers who already run Opik and want to drive it from the same AI assistant they code with.

You:    "Which traces in project 'demo' failed today?"
Claude: → list(entity_type="trace", project_name="demo") → "Three traces failed…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

Quick start

One command sets Opik up in the AI clients on your machine, Claude Code included. It finds your Opik (the one saved in ~/.opik.config, one running on localhost, or it asks which), registers the MCP server, installs the Opik skill pack, and checks the connection. On Opik Cloud there is no API key to handle: your client signs in in the browser. It needs uv and no Opik SDK:

uvx opik@latest mcp configure

Without a terminal, as from a coding agent or a script, name the client:

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-client also takes codex, cursor, vscode and opencode. Run that way it uses the Opik saved in ~/.opik.config, API key included, or one answering on localhost, and otherwise stops and asks for --deployment.

A coding agent asked to "install opik mcp" gets the full steps, including what to ask the user, from uvx opik-mcp@latest --help. They are the same as Install with a coding agent below.

Registering the server by hand, with the client commands under Set it up by hand, skips the check of which Opik you use and the skill pack, so it is for clients the installer doesn't support.

Clients load MCP servers when a session starts, so start a new session afterwards.

Setup guide, troubleshooting and FAQ: comet.com/docs/opik/mcp-server.

Opik Cloud: the hosted server

Comet runs the server at https://www.comet.com/opik/api/v1/mcp. Your client connects over HTTP and opens a browser sign-in the first time. There is nothing to install, no API key, and no workspace to set: the server works in the workspace you pick when you sign in. After adding it, start a new session and ask: "list my Opik projects".

The Quick start command sets this up for Claude Code, Codex, Cursor, VS Code Copilot and opencode, with the skill pack. In Claude Code, the plugin does the same in one command. The buttons below add it to Cursor or VS Code in one click; other ways to register it by hand are under Set it up by hand.

Claude Code plugin

The opik plugin installs the Opik skills and registers the hosted MCP server for Opik Cloud:

/plugin install opik --marketplace comet-ml/opik-mcp

On Claude Code before 2.1.275, run /plugin marketplace add comet-ml/opik-mcp, then /plugin install opik@opik. The skills load as opik:<skill>, such as opik:opik-instrument, and /mcp shows the server as plugin:opik:opik-cloud. The server is Opik Cloud's. Start a new session, then sign in from /mcp → Authenticate. For a self-hosted Comet that runs the MCP OAuth server, add it with claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp; for any other self-hosted or open-source Opik, use the Quick start command. Then disable plugin:opik:opik-cloud in /mcp. Claude Code does not update a plugin from this marketplace on its own: run /plugin marketplace update opik, then /plugin update opik@opik, or turn on auto-update for the marketplace in /plugin. This marketplace serves main, which can be ahead of the last release. An update arrives only when the plugin's version changes, at each release.

If you added opik-mcp before at the same URL, Claude Code keeps your copy and skips the plugin's. If yours is another server, such as the local uvx opik-mcp, both load: run claude mcp remove opik-mcp to keep only the plugin's. Skills from the skill pack also load next to the plugin's copies; remove them with npx skills remove --global --agent claude-code, which asks which ones.

Self-hosted and open-source Opik: the local server

opik-mcp runs on your machine: the client starts it with uvx opik-mcp and talks to it over stdio. The Quick start command sets it up from your ~/.opik.config or a local Opik; to register it by hand, see Set it up by hand. Install uv once; it fetches the package, and Python 3.13 if needed, on first use:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv

uvx opik-mcp reuses the copy uv has cached, so it starts quickly; uv cache clean opik-mcp makes the next start fetch the newest release. uvx opik-mcp@latest asks PyPI on every start, which adds about a second and a half. Codex waits mcp_optional_startup_grace_ms (1 s by default) for servers before it builds the first tool list, so a slower start can leave the tools out of the first turn. The one-off commands in this README (opik mcp configure, opik mcp status, --help, --check) carry @latest, so they never run a copy uv cached months ago.

Env vars point the server at your Opik:

• Open source serves its API at /api and has one workspace, default, so it needs no OPIK_WORKSPACE. COMET_URL_OVERRIDE would point the server at /opik/api, which open source does not serve.
• A self-hosted Comet has named workspaces. Set OPIK_WORKSPACE to the segment after /opik/ in your Opik URL; left out, reads come from your account's default workspace, with no error to say so.
• A self-hosted Comet that runs the MCP OAuth server (off by default) can use the hosted flow instead, at https://<host>/opik/api/v1/mcp.
• Substitute every value. The server refuses a placeholder workspace such as <your-workspace> or ${input:OPIK_WORKSPACE}; a placeholder URL is sent as-is and fails to connect.
• OPIK_MCP_ANALYTICS_SOURCE="" in the env block opts a self-hosted install out of the cloud-Comet source label on telemetry events.

Before adding the server to a client, check the settings: run it with the same env and --check. It makes one call to Opik and prints the workspace and how many projects it sees, or what to fix with a link to the docs, and exits 0 or 1. A client can't tell you this before a new session: Claude Code shows Connected even with a wrong key, and Codex starts nothing until then.

OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check

Then register it with your client: the local server, by hand.

Install with a coding agent

For an AI agent asked to install the server, as in "install opik mcp". The aim is the server registered for the user's Opik, the Opik skill pack installed, and the user signed in. Work out which Opik from this machine, and ask the user only what it can't tell you: one question per message, each answer before the next. The installer in step 3 does the whole setup in one run, so settle steps 1 and 2 before you run it. uvx opik-mcp@latest --help prints these steps.

1. See what is there.

   uvx opik@latest mcp status
   

   It shows the Opik saved in ~/.opik.config (URL and workspace, never the key) and the clients that already have the server. In Claude Code, also run claude mcp list: it shows claude.ai connectors and entries under other names. It also prints each entry's command, which for an old npx entry can hold an API key: don't repeat it.

   • A server for https://www.comet.com/opik/api/v1/mcp under any name, such as a claude.ai connector, means it is registered: don't add a second one. Install the skill pack on its own with npx skills add comet-ml/opik-skills -g --all. Go to step 4 if the server shows ! Needs authentication.
   • The installer replaces an existing opik-mcp entry without asking, such as one for the old npx server. Ask the user before you run it.

2. Find the user's Opik.

   • Saved in ~/.opik.config: use it, and tell the user which one you are setting up. The installer reads it, API key included, so don't ask for a key.
   • No ~/.opik.config: curl -s http://localhost:5173/api/is-alive/ping. An answer is an open-source Opik on this machine. In a sandboxed shell, such as Codex's, no answer can mean the shell has no network rather than no Opik.
   • Neither: ask, and don't pick one yourself. An Opik URL in the project, such as OPIK_URL_OVERRIDE in .env, makes it a yes-or-no question. Otherwise: "Which Opik do you use: Opik Cloud (www.comet.com), an open-source Opik (its URL), or a self-hosted Comet platform (its URL and workspace)?"

3. Run the installer for the client you run in. It installs the Opik skill pack with the server, with or without --skills; keep the flag in a command you give the user to run later. On Opik Cloud it opens the browser sign-in and waits a minute for it, so tell the user first.

   uvx opik@latest mcp configure --ai-client claude-code --skills
   

   --ai-client also takes codex, cursor, vscode and opencode. For an Opik saved in ~/.opik.config or running on localhost, run it as it is: --deployment sets the saved config aside, API key included. With neither, add the flag for the Opik the user named in step 2:

   The user's Opik	Add
   Opik Cloud, www.comet.com	--deployment cloud
   Open-source Opik	--deployment local, and --url <url> when it is not on localhost
   A self-hosted Comet platform, /opik/ in its URL	--deployment self-hosted --url <url> --workspace <workspace>, with OPIK_API_KEY in the shell

   If it fails, as when the Opik doesn't answer, tell the user what it printed and what to check, such as a VPN or the URL. Don't switch to another Opik.

4. Sign-in, for Opik Cloud. If the installer reports the server as not