Comet-ML/Opik-MCP

**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.
---
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:
Without a terminal, as from a coding agent or a script, name the client:
--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.
| Your Opik | Server | Transport | Sign-in |
|---|---|---|---|
| Opik Cloud (www.comet.com) | the hosted server, run by Comet | Streamable HTTP | in the browser (OAuth); no API key |
| Self-hosted Comet, open-source Opik | the local server, this package | stdio | env vars; an API key only where the deployment needs one |
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. 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.
---
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:
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:
| Your Opik | Env vars |
|---|---|
| Open-source Opik on this machine | OPIK_URL=http://localhost:5173/api |
| Open-source Opik on a server | OPIK_URL=https:// /api, plus OPIK_API_KEY only if the deployment adds authentication |
| Self-hosted Comet platform (the Opik UI is at https:// /opik) | COMET_URL_OVERRIDE=https:// , OPIK_WORKSPACE, OPIK_API_KEY |
- 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:// /opik/api/v1/mcp.
- Substitute every value. The server refuses a placeholder workspace such as