Skip to content
Back to search

opik

MCP serverGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/comet-ml/opik-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/comet-ml/opik-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/comet-ml--opik-mcp/badge.svg)](/listings/comet-ml--opik-mcp)

HTML

<a href="/listings/comet-ml--opik-mcp"><img src="/api/listings/comet-ml--opik-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`](https://docs.astral.sh/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](#install-with-a-coding-agent) below.

Registering the server by hand, with the client commands under [Set it up by hand](#set-it-up-by-hand-no-opik-check-no-skill-pack), 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](#opik-cloud-the-hosted-server), run by Comet | Streamable HTTP | in the browser (OAuth); no API key | | Self-hosted Comet, open-source Opik | [the local server](#self-hosted-and-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](https://www.comet.com/docs/opik/mcp-server).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "opik",
  3. "owner": {
  4. "name": "Comet ML",
  5. "url": "https://github.com/comet-ml"
  6. },
  7. "metadata": {
  8. "description": "The opik plugin: the Opik agent skills and the hosted Opik MCP server."
  9. },
  10. "plugins": [
  11. {
  12. "name": "opik",
  13. "source": "./plugins/opik",
  14. "description": "Find what broke in your production agents, then test and fix it with Opik, the open-source LLM observability and evaluation platform from Comet."
  15. }
  16. ]
  17. }
README.md · README · 1,069 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Opik MCP Server
  2. **The official Model Context Protocol (MCP) server for [Opik](https://github.com/comet-ml/opik), the open-source LLM observability and evaluation platform, built by [Comet](https://www.comet.com).**
  3. Plug your AI host (Claude Code, Cursor, VS Code Copilot, Codex, opencode, or any
  4. MCP client) directly into your Opik workspace: read traces, log scores, and save
  5. prompt versions, all from the chat.
  6. Built for LLM engineers who already run Opik and want to drive it from the same
  7. AI assistant they code with.
  8. ```
  9. You: "Which traces in project 'demo' failed today?"
  10. Claude: → list(entity_type="trace", project_name="demo") → "Three traces failed…"
  11. You: "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
  12. Claude: → write(score.create) → done
  13. ```
  14. ---
  15. ## Quick start
  16. One command sets Opik up in the AI clients on your machine, Claude Code
  17. included. It finds your Opik (the one saved in `~/.opik.config`, one running on
  18. localhost, or it asks which), registers the MCP server, installs the Opik skill
  19. pack, and checks the connection. On Opik Cloud there is no API key to handle:
  20. your client signs in in the browser. It needs [`uv`](https://docs.astral.sh/uv/)
  21. and no Opik SDK:
  22. ```bash
  23. uvx opik@latest mcp configure
  24. ```
  25. Without a terminal, as from a coding agent or a script, name the client:
  26. ```bash
  27. uvx opik@latest mcp configure --ai-client claude-code --skills
  28. ```
  29. `--ai-client` also takes `codex`, `cursor`, `vscode` and `opencode`. Run that
  30. way it uses the Opik saved in `~/.opik.config`, API key included, or one
  31. answering on localhost, and otherwise stops and asks for `--deployment`.
  32. A coding agent asked to "install opik mcp" gets the full steps, including what
  33. to ask the user, from `uvx opik-mcp@latest --help`. They are the same as
  34. [Install with a coding agent](#install-with-a-coding-agent) below.
  35. Registering the server by hand, with the client commands under
  36. [Set it up by hand](#set-it-up-by-hand-no-opik-check-no-skill-pack), skips the check of which Opik you use
  37. and the skill pack, so it is for clients the installer doesn't support.
  38. | Your Opik | Server | Transport | Sign-in |
  39. |---|---|---|---|
  40. | Opik Cloud (`www.comet.com`) | [the hosted server](#opik-cloud-the-hosted-server), run by Comet | Streamable HTTP | in the browser (OAuth); no API key |
  41. | Self-hosted Comet, open-source Opik | [the local server](#self-hosted-and-open-source-opik-the-local-server), this package | stdio | env vars; an API key only where the deployment needs one |
  42. Clients load MCP servers when a session starts, so start a new session
  43. afterwards.
  44. Setup guide, troubleshooting and FAQ: [comet.com/docs/opik/mcp-server](https://www.comet.com/docs/opik/mcp-server).
  45. ---
  46. ## Opik Cloud: the hosted server
  47. Comet runs the server at `https://www.comet.com/opik/api/v1/mcp`. Your client
  48. connects over HTTP and opens a browser sign-in the first time. There is nothing
  49. to install, no API key, and no workspace to set: the server works in the
  50. workspace you pick when you sign in. After adding it, start a new session and
  51. ask: **"list my Opik projects"**.
  52. The [Quick start](#quick-start) command sets this up for Claude Code, Codex,
  53. Cursor, VS Code Copilot and opencode, with the skill pack. In Claude Code, the
  54. [plugin](#claude-code-plugin) does the same in one command. The buttons below add
  55. it to Cursor or VS Code in one click; other ways to register it by hand are under
  56. [Set it up by hand](#set-it-up-by-hand-no-opik-check-no-skill-pack).
  57. [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=opik-mcp&config=eyJ1cmwiOiJodHRwczovL3d3dy5jb21ldC5jb20vb3Bpay9hcGkvdjEvbWNwIn0%3D)
  58. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=opik-mcp&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.comet.com%2Fopik%2Fapi%2Fv1%2Fmcp%22%7D)
  59. ### Claude Code plugin
  60. The `opik` plugin installs the Opik skills and registers the hosted MCP server
  61. for Opik Cloud:
  62. ```
  63. /plugin install opik --marketplace comet-ml/opik-mcp
  64. ```
  65. On Claude Code before 2.1.275, run `/plugin marketplace add comet-ml/opik-mcp`,
  66. then `/plugin install opik@opik`. The skills load as `opik:<skill>`, such as
  67. `opik:opik-instrument`, and `/mcp` shows the server as `plugin:opik:opik-cloud`.
  68. The server is Opik Cloud's. Start a new session, then sign in from `/mcp` →
  69. **Authenticate**. For a self-hosted Comet that runs the MCP OAuth server, add
  70. it with `claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp`;
  71. for any other self-hosted or open-source Opik, use the
  72. [Quick start](#quick-start) command. Then disable `plugin:opik:opik-cloud` in
  73. `/mcp`. Claude Code does not update a plugin from
  74. this marketplace on its own: run `/plugin marketplace update opik`, then
  75. `/plugin update opik@opik`, or turn on auto-update for the marketplace in
  76. `/plugin`. This marketplace serves `main`, which can be ahead of the last
  77. release. An update arrives only when the plugin's version changes, at each
  78. release.
  79. If you added `opik-mcp` before at the same URL, Claude Code keeps your copy and
  80. skips the plugin's. If yours is another server, such as the local
  81. `uvx opik-mcp`, both load: run `claude mcp remove opik-mcp` to keep only the
  82. plugin's. Skills from the skill pack also load next to the plugin's copies;
  83. remove them with `npx skills remove --global --agent claude-code`, which asks
  84. which ones.
  85. ---
  86. ## Self-hosted and open-source Opik: the local server
  87. `opik-mcp` runs on your machine: the client starts it with `uvx opik-mcp` and
  88. talks to it over stdio. The [Quick start](#quick-start) command sets it up from
  89. your `~/.opik.config` or a local Opik; to register it by hand, see
  90. [Set it up by hand](#set-it-up-by-hand-no-opik-check-no-skill-pack). Install [`uv`](https://docs.astral.sh/uv/) once; it
  91. fetches the package, and Python 3.13 if needed, on first use:
  92. ```bash
  93. curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
  94. # or: brew install uv
  95. ```
  96. `uvx opik-mcp` reuses the copy uv has cached, so it starts quickly;
  97. `uv cache clean opik-mcp` makes the next start fetch the newest release.
  98. `uvx opik-mcp@latest` asks PyPI on every start, which adds about a second and a
  99. half. Codex waits `mcp_optional_startup_grace_ms` (1 s by default) for servers
  100. before it builds the first tool list, so a slower start can leave the tools out
  101. of the first turn. The one-off commands in this README (`opik mcp configure`,
  102. `opik mcp status`, `--help`, `--check`) carry `@latest`, so they never run a
  103. copy uv cached months ago.
  104. Env vars point the server at your Opik:
  105. | Your Opik | Env vars |
  106. |---|---|
  107. | Open-source Opik on this machine | `OPIK_URL=http://localhost:5173/api` |
  108. | Open-source Opik on a server | `OPIK_URL=https://<host>/api`, plus `OPIK_API_KEY` only if the deployment adds authentication |
  109. | Self-hosted Comet platform (the Opik UI is at `https://<host>/opik`) | `COMET_URL_OVERRIDE=https://<host>`, `OPIK_WORKSPACE`, `OPIK_API_KEY` |
  110. - Open source serves its API at `/api` and has one workspace, `default`, so it
  111. needs no `OPIK_WORKSPACE`. `COMET_URL_OVERRIDE` would point the server at
  112. `/opik/api`, which open source does not serve.
  113. - A self-hosted Comet has named workspaces. Set `OPIK_WORKSPACE` to the segment
  114. after `/opik/` in your Opik URL; left out, reads come from your account's
  115. default workspace, with no error to say so.
  116. - A self-hosted Comet that runs the MCP OAuth server (off by default) can use
  117. the hosted flow instead, at `https://<host>/opik/api/v1/mcp`.
  118. - Substitute every value. The server refuses a placeholder workspace such as
  119. `<your-workspace>` or `${input:OPIK_WORKSPACE}`; a placeholder URL is sent
  120. as-is and fails to connect.
  121. - `OPIK_MCP_ANALYTICS_SOURCE=""` in the `env` block opts a self-hosted install
  122. out of the cloud-Comet source label on telemetry events.
  123. Before adding the server to a client, check the settings: run it with the same
  124. env and `--check`. It makes one call to Opik and prints the workspace and how
  125. many projects it sees, or what to fix with a link to the docs, and exits 0 or 1.
  126. A client can't tell you this before a new session: Claude Code shows Connected
  127. even with a wrong key, and Codex starts nothing until then.
  128. ```bash
  129. OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check
  130. ```
  131. Then register it with your client: [the local server, by hand](#local-server-self-hosted-and-open-source-opik).
  132. ---
  133. ## Install with a coding agent
  134. For an AI agent asked to install the server, as in "install opik mcp". The aim
  135. is the server registered for the user's Opik, the Opik skill pack installed,
  136. and the user signed in. Work out which Opik from this machine, and ask the user
  137. only what it can't tell you: one question per message, each answer before the
  138. next. The installer in step 3 does the whole setup in one run, so settle steps
  139. 1 and 2 before you run it. `uvx opik-mcp@latest --help` prints these steps.
  140. 1. **See what is there.**
  141. ```bash
  142. uvx opik@latest mcp status
  143. ```
  144. It shows the Opik saved in `~/.opik.config` (URL and workspace, never the
  145. key) and the clients that already have the server. In Claude Code, also run
  146. `claude mcp list`: it shows claude.ai connectors and entries under other
  147. names. It also prints each entry's command, which for an old npx entry can
  148. hold an API key: don't repeat it.
  149. - A server for `https://www.comet.com/opik/api/v1/mcp` under any name, such
  150. as a claude.ai connector, means it is registered: don't add a second one.
  151. Install the skill pack on its own with
  152. `npx skills add comet-ml/opik-skills -g --all`. Go to step 4 if the
  153. server shows `! Needs authentication`.
  154. - The installer replaces an existing `opik-mcp` entry without asking, such
  155. as one for the old npx server. Ask the user before you run it.
  156. 2. **Find the user's Opik.**
  157. - Saved in `~/.opik.config`: use it, and tell the user which one you are
  158. setting up. The installer reads it, API key included, so don't ask for a
  159. key.
  160. - No `~/.opik.config`: `curl -s http://localhost:5173/api/is-alive/ping`.
  161. An answer is an open-source Opik on this machine. In a sandboxed shell,
  162. such as Codex's, no answer can mean the shell has no network rather than
  163. no Opik.
  164. - Neither: ask, and don't pick one yourself. An Opik URL in the
  165. project, such as `OPIK_URL_OVERRIDE` in `.env`, makes it a yes-or-no
  166. question. Otherwise: "Which Opik do you use: Opik Cloud (www.comet.com),
  167. an open-source Opik (its URL), or a self-hosted Comet platform (its URL
  168. and workspace)?"
  169. 3. **Run the installer** for the client you run in. It installs the Opik
  170. skill pack with the server, with or without `--skills`; keep the flag in a
  171. command you give the user to run later. On Opik Cloud it opens the browser
  172. sign-in and waits a minute for it, so tell the user first.
  173. ```bash
  174. uvx opik@latest mcp configure --ai-client claude-code --skills
  175. ```
  176. `--ai-client` also takes `codex`, `cursor`, `vscode` and `opencode`. For an
  177. Opik saved in `~/.opik.config` or running on localhost, run it as it is:
  178. `--deployment` sets the saved config aside, API key included. With neither,
  179. add the flag for the Opik the user named in step 2:
  180. | The user's Opik | Add |
  181. |---|---|
  182. | Opik Cloud, `www.comet.com` | `--deployment cloud` |
  183. | Open-source Opik | `--deployment local`, and `--url <url>` when it is not on localhost |
  184. | A self-hosted Comet platform, `/opik/` in its URL | `--deployment self-hosted --url <url> --workspace <workspace>`, with `OPIK_API_KEY` in the shell |
  185. If it fails, as when the Opik doesn't answer, tell the user what it printed
  186. and what to check, such as a VPN or the URL. Don't switch to another Opik.
  187. 4. **Sign-in, for Opik Cloud.** If the installer reports the server as not
  188. signed in yet, give the user `claude mcp login opik-mcp` to run, or `/mcp`
  189. in a Claude Code session, rather than running it yourself: it waits on the
  190. browser. A claude.ai connector signs in from `/mcp`. The sign-in asks for a
  191. workspace; name the one saved in `~/.opik.config`, if any.
  192. 5. **Finish.** Say what was installed and what is left. Name the skill pack:
  193. the [Opik skills](https://github.com/comet-ml/opik-skills#skills-in-this-pack),
  194. installed for every project, which teach the agent to instrument, evaluate
  195. and debug with Opik. Clients load MCP servers and skills when a session
  196. starts: ask the user to start a new session, then try
  197. **"list my Opik projects"**.
  198. On every path:
  199. - Don't ask the user to paste an API key into the chat. The hosted server needs
  200. none; otherwise take it from the shell environment (`"$OPIK_API_KEY"`), or let
  201. the user run the command.
  202. - Don't guess the workspace. It is the segment after `comet.com/opik/` (or
  203. `/opik/` on a self-hosted Comet) in the user's Opik URL.
  204. - Don't print `~/.claude.json` or `~/.opik.config`: both can hold API keys.
  205. `uvx opik@latest mcp status` and `claude mcp list` show what you need, and the
  206. installer reads the config itself.
  207. - If a permission check blocks a command, don't work around it. Give the user
  208. the command to run (in Claude Code, `!` before it runs it from the prompt).
  209. For a client the installer doesn't know, register by hand with the commands in
  210. [Set it up by hand](#set-it-up-by-hand-no-opik-check-no-skill-pack): the hosted server for Opik Cloud, the
  211. local server for the rest.
  212. - Before registering the local server, run it with the env you will pass and
  213. `--check`, with `OPIK_API_KEY` exported in the shell rather than written on
  214. the command:
  215. `OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check`. It exits 0
  216. and names the workspace it sees, or prints what to fix. Once registered,
  217. Claude Code reports Connected even with a wrong key, and Codex has no check.
  218. - Claude Code refuses to add over an existing `opik-mcp` entry, so remove it
  219. first with `claude mcp remove opik-mcp --scope user`; Codex's `add` replaces
  220. it.
  221. - After registering, in Claude Code, read only the status line:
  222. `claude mcp get opik-mcp | grep Status`. The full output prints the `env`
  223. block, API key included. The hosted server shows `! Needs authentication`
  224. until `claude mcp login opik-mcp` has run. Codex has nothing that starts the
  225. server before a session; `codex mcp get opik-mcp` shows what was stored, with
  226. env values masked.
  227. ---
  228. ## Set it up by hand (no Opik check, no skill pack)
  229. The [Quick start](#quick-start) command does all of this for Claude Code, Codex,
  230. Cursor, VS Code Copilot and opencode, and also checks which Opik you use and
  231. installs the skill pack. Register by hand only for another client, or to see
  232. what the installer writes. A coding agent installing for a user runs the
  233. installer: see [Install with a coding agent](#install-with-a-coding-agent).
  234. ### Hosted server (Opik Cloud)
  235. #### Claude Code, by hand
  236. ```bash
  237. claude mcp add --scope user --transport http opik-mcp https://www.comet.com/opik/api/v1/mcp
  238. ```
  239. Then sign in from `/mcp` → **Authenticate** in a Claude Code session. It opens
  240. a browser, so the person at the keyboard does it; from their own terminal,
  241. `claude mcp login opik-mcp` does the same. `--scope user` makes the server available in every project; without
  242. it, Claude Code registers it for the current directory only. Over SSH,
  243. `claude mcp login opik-mcp --no-browser` prints the sign-in URL to open on your
  244. own machine; the last step needs an interactive terminal (`ssh -t`).
  245. #### Codex, by hand
  246. ```bash
  247. codex mcp add opik-mcp --url https://www.comet.com/opik/api/v1/mcp
  248. ```
  249. `add` opens the sign-in; `codex mcp login opik-mcp` opens it again. In
  250. `~/.codex/config.toml` the same server is:
  251. ```toml
  252. [mcp_servers.opik-mcp]
  253. url = "https://www.comet.com/opik/api/v1/mcp"
  254. ```
  255. #### Cursor, by hand
  256. Use the button under [the hosted server](#opik-cloud-the-hosted-server), or add to
  257. `~/.cursor/mcp.json`:
  258. ```json
  259. {
  260. "mcpServers": {
  261. "opik-mcp": {
  262. "url": "https://www.comet.com/opik/api/v1/mcp"
  263. }
  264. }
  265. }
  266. ```
  267. #### VS Code Copilot, by hand
  268. Use the button under [the hosted server](#opik-cloud-the-hosted-server), or add to
  269. `.vscode/mcp.json` in your workspace or to your
  270. user `mcp.json` (**MCP: Open User Configuration**):
  271. ```json
  272. {
  273. "servers": {
  274. "opik-mcp": {
  275. "type": "http",
  276. "url": "https://www.comet.com/opik/api/v1/mcp"
  277. }
  278. }
  279. }
  280. ```
  281. #### Other clients
  282. Any client that takes a URL can use the hosted server:
  283. ```bash
  284. npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp
  285. ```
  286. A client that can only start local commands can reach it through
  287. `npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp`.
  288. #### Opik Cloud with an API key
  289. Where nobody can complete the browser sign-in, as when an agent runs unattended
  290. from a script or a client has no MCP OAuth support, use an API key from
  291. [`comet.com/api/my/settings/`](https://www.comet.com/api/my/settings/) instead,
  292. with [the local server](#self-hosted-and-open-source-opik-the-local-server)
  293. pointed at Opik Cloud:
  294. ```bash
  295. claude mcp add --scope user opik-mcp \
  296. --env OPIK_API_KEY="$OPIK_API_KEY" \
  297. --env OPIK_WORKSPACE=<workspace> \
  298. -- uvx opik-mcp
  299. ```
  300. The other clients take the same two variables in their `env` block. Set
  301. `OPIK_WORKSPACE` to the segment after `comet.com/opik/` in your Opik URL
  302. (`https://www.comet.com/opik/acme-ai/projects` → `acme-ai`). Left out, the
  303. server sends `default`, which Comet resolves to your account's default
  304. workspace, so reads can come from the wrong workspace without an error.
  305. ### Local server (self-hosted and open-source Opik)
  306. The examples use a local open-source Opik. For a self-hosted Comet, swap in the
  307. three variables from [the table](#self-hosted-and-open-source-opik-the-local-server).
  308. After adding the server, start a new session
  309. and ask: **"list my Opik projects"**.
  310. #### Claude Code, by hand
  311. ```bash
  312. claude mcp add --scope user opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp
  313. ```
  314. On a self-hosted Comet, with the key in your shell's `OPIK_API_KEY`:
  315. ```bash
  316. claude mcp add --scope user opik-mcp \
  317. --env COMET_URL_OVERRIDE=https://<host> \
  318. --env OPIK_WORKSPACE=<workspace> \
  319. --env OPIK_API_KEY="$OPIK_API_KEY" \
  320. -- uvx opik-mcp
  321. ```
  322. Or edit `~/.claude.json` directly:
  323. ```json
  324. {
  325. "mcpServers": {
  326. "opik-mcp": {
  327. "type": "stdio",
  328. "command": "uvx",
  329. "args": ["opik-mcp"],
  330. "env": {
  331. "OPIK_URL": "http://localhost:5173/api"
  332. }
  333. }
  334. }
  335. }
  336. ```
  337. `claude mcp get opik-mcp` shows `✔ Connected` once the server starts. That does
  338. not prove the URL or key are right, because only a tool call reaches Opik;
  339. `--check` ([the local server](#self-hosted-and-open-source-opik-the-local-server)) does. It also prints the `env` block, API key included.
  340. #### Codex, by hand
  341. ```bash
  342. codex mcp add opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp
  343. ```
  344. Or edit `~/.codex/config.toml`:
  345. ```toml
  346. [mcp_servers.opik-mcp]
  347. command = "uvx"
  348. args = ["opik-mcp"]
  349. env = { OPIK_URL = "http://localhost:5173/api" }
  350. # On a self-hosted Comet, forward the key from the environment Codex starts in,
  351. # so it stays out of this file:
  352. # env_vars = ["OPIK_API_KEY"]
  353. # Time allowed for the server to start (default 10 s); the first start
  354. # downloads the package.
  355. startup_timeout_sec = 30
  356. ```
  357. Codex gives a local server only the variables in `env` and the names in
  358. `env_vars`, so a key exported in your shell does not reach it otherwise.
  359. #### Cursor, by hand
  360. Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project), or use
  361. **Cmd+Shift+J → Features → Model Context Protocol**:
  362. ```json
  363. {
  364. "mcpServers": {
  365. "opik-mcp": {
  366. "type": "stdio",
  367. "command": "uvx",
  368. "args": ["opik-mcp"],
  369. "env": {
  370. "OPIK_URL": "http://localhost:5173/api"
  371. }
  372. }
  373. }
  374. }
  375. ```
  376. > **Cursor 60s timeout.** Cursor enforces a hard tool-call timeout that doesn't
  377. > reset on progress notifications. See [Known host limits](#known-host-limits).
  378. #### VS Code Copilot, by hand
  379. Add to `.vscode/mcp.json` in your workspace, or to your user `mcp.json`
  380. (**MCP: Open User Configuration**):
  381. ```json
  382. {
  383. "servers": {
  384. "opik-mcp": {
  385. "type": "stdio",
  386. "command": "uvx",
  387. "args": ["opik-mcp"],
  388. "env": {
  389. "OPIK_URL": "http://localhost:5173/api"
  390. }
  391. }
  392. }
  393. }
  394. ```
  395. ### MCP Inspector (manual testing)
  396. ```bash
  397. OPIK_URL=http://localhost:5173/api npx @modelcontextprotocol/inspector uvx opik-mcp
  398. ```
  399. ---
  400. ## Coming from `npx opik-mcp`?
  401. The TypeScript server (npm `opik-mcp@2`) is deprecated and stops serving
  402. requests on **2026-11-15**. For a new install, run the
  403. [Quick start](#quick-start) command; `uvx opik-mcp` is the command a client runs
  404. to start the server, not an installer. To move an existing config on Opik Cloud,
  405. switch to the hosted server and drop the API key. Otherwise, in your MCP client
  406. config, replace `npx -y opik-mcp` with `uvx opik-mcp`. Some env vars were renamed and command-line flags are no
  407. longer read: see the [migration
  408. guide](https://github.com/comet-ml/opik-mcp/blob/main/legacy/typescript/MIGRATION.md).
  409. Support policy: [`DEPRECATED.md`](https://github.com/comet-ml/opik-mcp/blob/main/legacy/typescript/DEPRECATED.md).
  410. The TypeScript source is at the git tag `legacy-typescript-final`.
  411. ---
  412. ## Tools
  413. `opik-mcp` exposes a small, outcome-oriented surface that covers the full
  414. lifecycle (read → annotate → curate → author → iterate).
  415. | Tool | Purpose |
  416. |---|---|
  417. | [`read`](#read) | Universal read by id / name / `opik://` URI |
  418. | [`list`](#list) | Universal list with optional name filter + pagination |
  419. | [`write`](#write) | Universal write — log traces/spans, score, comment, save prompts, manage datasets & experiments |
  420. | [`schema`](#schema) | Introspect write-operation schemas (used by the LLM to construct valid payloads) |
  421. | `read_skill` | Read one of the Opik agent skills bundled with this server |
  422. ### `read`
  423. One tool for any "show me X" question. Takes an `entity_type` plus an `id`
  424. (UUID or, for nameable types, a name) or a full `opik://` URI. Composite reads
  425. (`trace`, `prompt`, `thread`, `agent_insights_issue`) inline their children so
  426. a single call returns the full picture.
  427. The record you name comes back whole. Inlined children do not: their bodies
  428. are fetched with the backend's `truncate=true`, so a field over ~10 KB is cut
  429. in ClickHouse and base64 images are replaced with `"[image]"` — one attachment
  430. echoed across 200 spans would otherwise cost more than everything else in the
  431. read. The answer says so in `spanBodies` / `messageBodies`, and any child is
  432. whole again through its own `read("span", id)` or `read("trace", trace_id)`,
  433. which hit endpoints that have no `truncate` parameter at all.
  434. An inlined collection is also bounded in length: 200 spans, 200 turns, 100
  435. prompt versions. Past that, `spansTruncated` / `messagesTruncated` /
  436. `versionsTruncated` is `true` and a `moreSpans` / `moreMessages` /
  437. `moreVersions` line beside it carries the count and the exact `list(...)` call
  438. that continues from where the inlined part stopped.
  439. **Supported entities:** `project`, `trace`, `span`, `dataset`, `dataset_item`,
  440. `experiment`, `prompt`, `thread`, `agent_insights_issue`. Name-based lookup is
  441. available for `project`, `experiment`, `prompt`, `dataset` (slower — two API
  442. calls — and may return multiple matches). `thread` and `agent_insights_issue`
  443. are project-scoped: pass `project_id` or `project_name`, or a link/URI that
  444. carries the project. `dataset` and `dataset_item` were called `test_suite` and
  445. `test_suite_item` before; the old names still resolve, but they are not
  446. advertised and new code should use the new ones.
  447. ```python
  448. read(entity_type="trace", id="7f2e3c8a-…")
  449. read(entity_type="project", id="demo") # name lookup
  450. read(entity_type="trace", id="opik://traces/7f2e3c8a-…")
  451. read(entity_type="agent_insights_issue", id="<issue-uuid>", project_id="<project-uuid>")
  452. read(
  453. entity_type="agent_insights_issue",
  454. id="https://www.comet.com/opik/<ws>/projects/<pid>/diagnostics?issue=<id>",
  455. )
  456. ```
  457. A link copied from the Opik UI works as the `id`: a thread link or a
  458. Diagnostics page link carries the project, so no `project_id` is needed and
  459. the entity type is taken from the link.
  460. A `project` read answers "how is my project doing" in one call. It returns
  461. `{project, summary, vocabulary, contains, url}`: the record, then the four
  462. figures the Logs page shows as cards (trace count, error rate, average
  463. duration, total cost) for the last 7 days against the 7 before, SDK traffic
  464. only, as on screen. `since` / `until` move that window; `since="30d"` is what
  465. the UI opens on. A rate or an average over a period with no traces comes back
  466. as `null`, because 0% errors on a week with no traffic reads as a healthy week.
  467. `vocabulary` is the map you need before you can ask anything else: the
  468. project's feedback score names, its token usage keys, and the automation rules
  469. scoring its traces. These are the names that go into a filter or into
  470. `series=` below, and guessing them returns an empty page that reads like good
  471. news. Score names and rules are capped, always report the true total, and name
  472. the call that returns the rest; usage keys are listed in full, since nothing
  473. else enumerates them. `contains` names the freshest experiment, dataset, prompt
  474. version and optimization run, so "what has been happening here" does not need
  475. four more calls. A part that failed to load says so instead of looking empty,
  476. and an empty one is omitted.
  477. An `agent_insights_issue` read returns `{issue, example_trace_ids, details}`:
  478. the Diagnostics issue record (name, description, cause, suggested fix,
  479. severity, status), the deduplicated ids of the traces that exhibit it (the
  480. same sample the Diagnostics page shows — open one with `read("trace", id)`),
  481. and the per-day breakdown. Trace bodies are not inlined, so the read stays one
  482. backend call. `since` / `until` narrow the per-day rows; the default is
  483. all-time. When the server knows the Opik URL and the session's workspace, the
  484. read also carries `url` (the issue's Diagnostics page) and `trace_url_template`
  485. (a deep link for any of the example traces), so the assistant can hand you
  486. something clickable; under an OAuth session whose workspace could not be
  487. resolved the links are omitted rather than guessed.
  488. Traces themselves carry no URL — a link for one is not derivable from the
  489. fields a `read` or `list` returns, and a guessed shape 404s. The session
  490. instructions name a template for it instead,
  491. `.../v1/session/redirect/projects/?trace_id={trace_id}&path=...`, so the
  492. assistant fills in an id and hands you a link. It goes through opik-backend's
  493. redirect, which resolves the project and the workspace from the trace, so it
  494. works where a direct project URL cannot, an OAuth session with an unresolved
  495. workspace included. It is the same link the Python SDK prints for a trace.
  496. ### `list`
  497. Browse or search a collection with pagination. Project-scoped types (`trace`,
  498. `span`, `thread`, `agent_insights_issue`, `dataset_item`, `prompt_version`)
  499. need their parent: a project UUID or name, a dataset UUID, or a prompt UUID.
  500. ```python
  501. list(entity_type="experiment", page=1, size=25)
  502. list(entity_type="experiment", name="rerank") # name substring filter
  503. list(entity_type="agent_insights_issue", project_name="demo") # open Diagnostics issues
  504. list(entity_type="agent_insights_issue", project_id="<uuid>", status="resolved")
  505. list(entity_type="trace", project_name="demo") # latest traces of one project
  506. list(
  507. entity_type="trace", project_name="demo", filters="error_info is_not_empty AND duration > 5000"
  508. )
  509. list(
  510. entity_type="span",
  511. project_name="demo", # spans across the whole project
  512. filters='type = "llm" AND usage.total_tokens > 10000',
  513. )
  514. list(
  515. entity_type="thread",
  516. project_name="demo",
  517. filters="number_of_messages > 20 AND feedback_scores.helpfulness < 0.5",
  518. )
  519. list(entity_type="experiment", filters='dataset_id = "<dataset-uuid>" AND tags contains "baseline"')
  520. ```
  521. **Filters.** `trace`, `span`, `thread`, `experiment` and `dataset_item` take an
  522. OQL string, the same grammar as the SDK's `search_traces(filter_string=…)`:
  523. ```
  524. <field>[.<key>] <op> <value> [AND ...]
  525. ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in
  526. ```
  527. Strings go in double quotes, numbers are bare, `duration` is in milliseconds,
  528. dates are ISO-8601 instants with a timezone (`"2026-09-08T10:00:00Z"`).
  529. Scores and dictionaries take a key: `feedback_scores.accuracy < 0.5`,
  530. `metadata.environment = "prod"`. `AND` is the only connector.
  531. Like the UI's Logs page, trace, span and thread lists add `source = "sdk"` so
  532. evaluator, playground and experiment traces stay out of the way; name `source`
  533. yourself to see them. The first output line echoes the filter that was applied.
  534. A bad filter fails before reaching the backend with what is needed to fix it:
  535. the position of a syntax error, the closest field name, the valid operators for
  536. the field's type, or the expected value format. Fields with a closed set of
  537. values (`source`, span `type`, thread `status`, `visibility_mode`) are checked
  538. against it too, every element of an `in` list included. `source` is the one the
  539. backend validates itself, and it answers an unknown value with a 500 rather
  540. than a 400, so `source = "SDK"` would otherwise be an opaque server error for a
  541. capital letter. The rest are compared as strings and answer with an empty page,
  542. which reads as "no matches" when it means "no such value". Ask
  543. `schema("list.trace")` (or `list.span`, `list.thread`, `list.experiment`) for
  544. the full field reference, accepted values included.
  545. **Finding one case in a dataset.** `list(entity_type="dataset_item",
  546. dataset_id=…)` filters on the case itself: `data.<key>` for the keys the
  547. dataset was built with, `full_data` for a substring of the whole payload (a
  548. full scan — name a key when you can), plus `id`, `tags`, `source`, `trace_id`,
  549. `span_id` and the timestamps. `data.<key>` takes the six string operators only
  550. (`=`, `!=`, `contains`, `not_contains`, `starts_with`, `ends_with`); the
  551. backend answers a comparison with a 400, so this one is refused before the
  552. call. The endpoint has no sorting and no free-text search — `sort` is refused
  553. rather than dropped. `read(entity_type="dataset_item", id=…)` returns one case
  554. whole, which is how a value the table cut is read back.
  555. ```python
  556. list(entity_type="dataset_item", dataset_id="<uuid>", filters='data.question contains "install"')
  557. list(
  558. entity_type="dataset_item", dataset_id="<uuid>", filters='trace_id = "<trace-uuid>"'
  559. ) # the case made from that trace
  560. read(entity_type="dataset_item", id="<item-uuid>") # the case, uncut
  561. ```
  562. With `experiment_ids` the same list is the comparison instead — the cases with
  563. each run attached — and it filters on the runs (`feedback_scores.<name>`,
  564. `output`, `duration`). The two are different field sets on two backend
  565. endpoints: `schema("list.dataset_item_case")` is the dataset's own cases,
  566. `schema("list.dataset_item")` the comparison.
  567. **Sort.** `trace`, `span`, `thread` and `experiment` take
  568. `sort="<field> [asc|desc]"`, `desc` by default and one field only:
  569. `sort="duration desc"`, `sort="total_estimated_cost"`,
  570. `sort="feedback_scores.accuracy asc"`, `sort="usage.total_tokens"`. The field is
  571. checked against the entity's sortable list before the call, because the backend
  572. silently ignores fields it cannot sort by. On very large workspaces the backend
  573. drops sorting altogether; the header says so when that happens.
  574. `dataset_item` sorts only as a comparison (with `experiment_ids`): the items
  575. endpoint takes no sorting parameter, so a sort on a plain listing is refused
  576. rather than dropped.
  577. **Time window and search.** `trace`, `span` and `thread` take `since` and
  578. `until`, each a relative span (`"30m"`, `"1h"`, `"7d"`) or an ISO-8601 instant
  579. with a timezone, so "the last hour" needs no clock arithmetic. The window is by
  580. record creation time, which is cheap for the backend and agrees with
  581. `start_time` within seconds for live traffic. For an exact bound, put
  582. `start_time` in `filters`. The same three types take `search`, free text matched
  583. anywhere in id, name, input, output, metadata, tags and thread id. Search scans
  584. the whole project on the backend, so the first call on a large project can take
  585. tens of seconds. Those calls get a 60-second timeout. Adding `since` makes them
  586. fast again.
  587. **Reading the table.** Durations are labelled `duration_ms` / `ttft_ms` and
  588. shown as whole milliseconds; the field stays `duration` in `filters` and
  589. `sort`. Timestamps are shown to the second and costs as plain decimals.
  590. Project rows carry `last_updated_trace_at` so you can see which project has
  591. live traffic; thread rows carry the first message. An empty page under a time
  592. window says when the project's last trace landed, and an empty page under the
  593. default `source = "sdk"` says how to see the other sources. A misspelled
  594. `project_name` comes back with the closest existing name.
  595. ```python
  596. list(
  597. entity_type="trace",
  598. project_name="demo",
  599. since="1h",
  600. filters="error_info is_not_empty",
  601. sort="duration desc",
  602. )
  603. list(entity_type="trace", project_name="demo", search="order-42")
  604. ```
  605. **Diagnostics issues.** `agent_insights_issue` is the Diagnostics page over
  606. the MCP: the recurring failures Opik's Diagnostics job grouped for a project,
  607. ranked as the UI ranks them (most recently seen first). Columns are `severity`,
  608. `status`, `total_occurrences` (all-time sum), `latest_count` (the most recent
  609. report day, the number the issue's own description refers to) and `last_seen`.
  610. Open issues are listed by default; pass `status="resolved"` or `"closed"` for
  611. the rest. `read` and `list` also answer to `issue`, which is what the UI calls
  612. these; the long name is the one in the `entity_type` enum, so that one entity
  613. does not appear there twice. Counts are all-time so they match the UI; the same `since` / `until`
  614. as for traces narrow the window, truncated to UTC report days because
  615. Diagnostics aggregates per day.
  616. An empty list says why it is empty, because "nothing is broken" and "nobody
  617. turned Diagnostics on" read the same otherwise. There are five states:
  618. Diagnostics is unavailable on this deployment, not enabled for this project,
  619. turned off, enabled but not scanned recently, or enabled and clean with the
  620. time of the last scan. The ones you can act on name the call to make, and every
  621. state links the project's Diagnostics page.
  622. A non-empty list dates itself. The issues are whatever the last scan grouped,
  623. so the reply ends with `Report covers data through <time>`, and when the window
  624. you asked about runs past that, it names the uncovered tail and how to close
  625. it: a trigger when a rescan reaches back far enough, otherwise raw traces with
  626. the `since` it gives you. Ask for a week on a project scanned nightly and the
  627. last day is missing from the grouped answer; this is what says so.
  628. `write("agent_insights_job.enable", {"project_name": "demo"})` turns Diagnostics
  629. on. It scans daily from then on, and calling it again is safe.
  630. `write("agent_insights_job.trigger", …)` scans the last 24 hours now, without
  631. waiting for the nightly run. Both take the permission that reading issues takes,
  632. and both refuse where the deployment has no Diagnostics.
  633. An issue moves through its lifecycle with
  634. `write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"})`
  635. — dealt with — or `…close` for one not worth acting on, and `…reopen` to put
  636. either back on the open list. All three take the same permission and answer
  637. with a link to the view the issue moved to, since a resolved issue is no longer
  638. on the default page. Whether a failure is fixed is a judgment call, so these
  639. are for when you ask: the assistant has no business tidying the list while
  640. triaging it.
  641. **Metrics over time.** `project_metric` charts one metric for a project as a
  642. table of time buckets: trace, span and thread counts, durations, error rates,
  643. costs, token usage and feedback scores. It answers the question that follows
  644. the overview, which is when something changed.
  645. ```python
  646. list(entity_type="project_metric", project_name="demo", metric_type="trace_count")
  647. list(
  648. entity_type="project_metric",
  649. project_name="demo",
  650. metric_type="trace_error_rate",
  651. since="14d",
  652. interval="daily",
  653. )
  654. list(
  655. entity_type="project_metric", project_name="demo", metric_type="span_count", breakdown="model"
  656. ) # one column per model
  657. list(
  658. entity_type="project_metric",
  659. project_name="demo",
  660. metric_type="span_duration",
  661. breakdown="model",
  662. series="p99",
  663. ) # the p99 of each model
  664. ```
  665. Rows are time buckets, not records, so `page`, `size` and `sort` are refused
  666. rather than ignored. `interval` is `hourly`, `daily`, `weekly` or `total`;
  667. left out, it follows the window the way the Metrics tab does — hourly up to 3
  668. days, daily up to 30, weekly beyond — so a default chart is a few dozen rows
  669. whatever the range, and an hourly month (721 rows) is something you ask for.
  670. `since` / `until` take the same forms as everywhere else and default to the
  671. last 7 days. `filters` uses the fields of whichever entity the metric is
  672. about, so a span metric is filtered by span fields.
  673. `breakdown` splits each bucket by `tags`, `name`, `error_info`, `error_type`,
  674. `model`, `provider`, `span_type`, `guardrail_name` or `metadata.<key>`. Not
  675. every metric accepts every one of those, and seven accept none at all; the tool
  676. knows which and says so before calling the backend, naming a metric that does
  677. answer the same question where one exists. Three families come back as several
  678. series at once (a duration as p50/p90/p99, a feedback score per name, token
  679. usage per key), and the backend charts one of them at a time when grouping, so
  680. `series=` picks it: a percentile, a score name, or a usage key. Duration
  681. defaults to `p50` and token usage to `total_tokens`, and whichever was used is
  682. echoed on the first line.
  683. Empty buckets are left out and counted underneath, so a quiet month is a few
  684. rows instead of a column of zeros, and a rate over a bucket with no traces is
  685. absent rather than reported as zero.
  686. Ask `schema("list.project_metric")` for the metric table, the intervals and the
  687. per-metric grouping matrix.
  688. **A project's names.** `score_name` lists the feedback score names recorded in
  689. a project and `online_rule` the automation rule evaluators configured on it,
  690. which is where most of those names come from. Both are the same lists
  691. `read("project", …)` carries, in full and paginated, for when the capped
  692. version in the overview is not enough.
  693. ```python
  694. list(entity_type="score_name", project_name="demo")
  695. list(entity_type="online_rule", project_name="demo")
  696. ```
  697. ### `write`
  698. Universal write dispatcher. Pass `operation` + `data` and the dispatcher
  699. validates the payload, applies the right REST verb, and returns the
  700. backend response.
  701. **Operations:**
  702. | Operation | What it does |
  703. |---|---|
  704. | `trace.create` | Log a single trace (or a batch). Parent for spans / scores / comments. |
  705. | `trace.update` | Finalize or amend an existing trace. |
  706. | `span.create` | Log a span on an existing trace (or a batch). |
  707. | `score.create` | Attach a numeric feedback score to a trace, span, or thread. |
  708. | `comment.create` | Attach a free-text comment to a trace, span, or thread. |
  709. | `prompt_version.save` | Save a new prompt version (creates the prompt by name if missing). |
  710. | `dataset.create` | Create a dataset — `type: "test_suite"` makes it an evaluation test suite. |
  711. | `dataset_item.upsert` | Upsert items into a dataset (always the envelope shape). |
  712. | `experiment.create` | Create an experiment scoped to a dataset. |
  713. | `experiment_item.create` | Attach trace + dataset_item rows to an experiment. |
  714. | `thread.close` | Close a thread (mark it inactive). Pass `thread_id` and the project. |
  715. | `thread.open` | Reopen a closed thread. Pass `thread_id` and the project. |
  716. | `agent_insights_job.enable` | Turn Diagnostics on for a project (daily scans, safe to repeat). |
  717. | `agent_insights_job.trigger` | Run a Diagnostics scan now, over the last 24 hours. |
  718. | `agent_insights_issue.resolve` | Mark a Diagnostics issue dealt with (ask the user first). |
  719. | `agent_insights_issue.close` | Mark a Diagnostics issue not worth acting on (ask the user first). |
  720. | `agent_insights_issue.reopen` | Put a resolved or closed Diagnostics issue back on the open list. |
  721. | `annotation_queue.create` | Create a project's annotation queue, optionally with a custom annotator view. |
  722. | `annotation_queue.update` | Change an annotation queue; set, replace or clear its annotator view. |
  723. ```python
  724. write(
  725. operation="score.create",
  726. data={
  727. "target": "trace",
  728. "target_id": "7f2e3c8a-…",
  729. "name": "helpfulness",
  730. "value": 0.9,
  731. "reason": "great recovery",
  732. },
  733. )
  734. ```
  735. ### `schema`
  736. Inspect the exact JSON shape and required fields of any write operation before
  737. you call it — useful when you're not sure what `data` should look like. Returns
  738. the schema, OAuth scope, and one validated example. Pure lookup, no backend
  739. call.
  740. ```python
  741. schema(operation="score.create")
  742. schema(operation="prompt_version.save")
  743. ```
  744. The same tool answers `list.trace`, `list.span`, `list.thread` and
  745. `list.experiment` with the `list` tool's reference for that entity: every
  746. filterable field with its type and valid operators, the sortable fields, whether
  747. a time window and free-text search apply, and two example filters.
  748. ```python
  749. schema(operation="list.trace")
  750. ```
  751. ---
  752. ## Configuration
  753. These configure the local server; every setting is an environment variable.
  754. The hosted server on Opik Cloud takes none of them.
  755. ### Identity / endpoint
  756. | Variable | Default | Notes |
  757. |---|---|---|
  758. | `OPIK_API_KEY` | — | API key, for a self-hosted Comet, or for Opik Cloud without the hosted server. Open-source Opik needs none unless the deployment adds authentication. |
  759. | `OPIK_WORKSPACE` | _unset_ | Workspace name. On cloud with an API key, unset sends `default`, which resolves to your account's **default** workspace — set it explicitly if you work in a different one, or reads come from the wrong workspace silently. Leave unset over OAuth (the token carries it) and on local/OSS (`default` is the only workspace there). |
  760. | `COMET_WORKSPACE` | — | Deprecated alias for `OPIK_WORKSPACE` (backward compat). `OPIK_WORKSPACE` wins if both are set. |
  761. | `COMET_WORKSPACE_ID` | _unset_ | Optional workspace UUID. Stamped into analytics events when set, and takes precedence over the resolved one. Rarely needed — OAuth installs get the UUID from the token automatically. |
  762. | `COMET_URL_OVERRIDE` | `https://www.comet.com` | Set to your self-hosted Comet host, or `https://dev.comet.com` for staging. |
  763. | `OPIK_URL` | derived from `COMET_URL_OVERRIDE` + `/opik/api` | Set it for open-source Opik, which serves its API at `/api` (`http://localhost:5173/api` locally). On a Comet platform, override only if Opik lives on a different host/path than the Comet UI. |
  764. | `OPIK_DEFAULT_PROJECT_NAME` | _unset_ | When set, the per-session `instructions` blob tells the LLM to pass this as `project_name` on every tool call unless the user names a different project. |
  765. ### Server / transport
  766. | Variable | Default | Notes |
  767. |---|---|---|
  768. | `OPIK_MCP_TRANSPORT` | `stdio` | `stdio` for host-launched, `streamable-http` to listen on a port. |
  769. | `OPIK_MCP_HOST` | `127.0.0.1` | uvicorn bind host (`streamable-http` only). |
  770. | `OPIK_MCP_PORT` | `8080` | uvicorn bind port (`streamable-http` only). |
  771. | `OPIK_MCP_RELOAD` | `false` | `true` to enable uvicorn `--reload` (dev only). |
  772. | `OPIK_MCP_AS_URL` | _unset_ | OAuth Authorization Server URL, advertised in `/.well-known/oauth-protected-resource` (RFC 9728) and used as the proxy target for AS-discovery probes. Required for MCP hosts to bootstrap the OAuth dance over HTTP. |
  773. | `OPIK_MCP_RESOURCE_URI` | _unset_ | Canonical public URI of this server, advertised as `resource` in the protected-resource metadata and used to derive the `WWW-Authenticate` hint. |
  774. | `OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S` | `30` | How long a "valid" answer from opik-backend's token introspection is trusted before the next request on the same OAuth token asks again. Bounds the backend load added by per-request validation and the window in which an expired token is still forwarded (that window also ends on the first 401 the backend returns). Capped by the token's own `expires_at` when the backend reports one. |
  775. | `OPIK_MCP_LOG_LEVEL` | `INFO` | stderr logger threshold. |
  776. #### Choosing a transport
  777. Two bearer shapes, two contracts on HTTP transport. An `opik_mcp_at_…` OAuth
  778. access token is **validated on every request** against opik-backend's token
  779. introspection endpoint (cached, see `OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`);
  780. an expired or revoked token gets an HTTP 401 with
  781. `WWW-Authenticate: Bearer error="invalid_token"`, which is what MCP hosts key
  782. their silent `refresh_token` grant on. An Opik API key is **not validated
  783. locally**: it is forwarded verbatim to opik-backend, which is its single point
  784. of enforcement. Pick the transport by deployment shape:
  785. | Scenario | Transport |
  786. |---|---|
  787. | Opik Cloud | Nothing to run: [the hosted server](#opik-cloud-the-hosted-server) is this server over HTTP, run by Comet |
  788. | MCP client and Opik on the same machine (local OSS install) | **stdio** (recommended — simplest, no port, no OAuth setup) |
  789. | Local MCP client → self-hosted Opik | stdio with the env vars for the deployment, or HTTP with OAuth (`OPIK_MCP_AS_URL` pointing at the backend) |
  790. | opik-mcp served behind the same edge as opik-backend | **HTTP** — bearers are validated by the backend per request |
  791. Note for local OSS installs: the OSS backend does not authenticate requests,
  792. so an HTTP opik-mcp in front of it is as open as the OSS REST API itself.
  793. Keep the default `127.0.0.1` bind (and prefer stdio) on shared networks.
  794. ### Telemetry
  795. | Variable | Default | Notes |
  796. |---|---|---|
  797. | `OPIK_MCP_ANALYTICS_ENABLED` | `true` | Set to `false` to disable all non-Sentry telemetry. |
  798. | `OPIK_MCP_SENTRY_ENABLED | `true` | Set to `false` to disable all Sentry telemetry. |
  799. =======
  800. ---
  801. ## Known host limits
  802. Hosts differ in how long they let a single tool call run:
  803. - **Claude Code** — no documented tool-call timeout. Recommended.
  804. - **Cursor** — hard 60s timeout that does **not** reset on progress
  805. ([upstream bug](https://forum.cursor.com/t/mcp-tool-timeout/74465)).
  806. - **MCP Inspector** — `MAX_TOTAL_TIMEOUT` bounds total duration (default 60s).
  807. Raise it in the Inspector UI for long operations.
  808. If a call gets stuck, set `OPIK_MCP_LOG_LEVEL=DEBUG` for the full request log.
  809. ---
  810. ## Troubleshooting
  811. **Does the setup work?** Run the server with the env from its client config and
  812. `--check`: `OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check`. It
  813. names the workspace and the projects it sees, or says what to fix. The server's
  814. own errors also say what to change, and link the docs page for it.
  815. **`OPIK_API_KEY` isn't picked up** — the var isn't reaching the server
  816. process. In Claude Code / Cursor / VS Code, env vars only apply when inside
  817. the `env` block of the MCP server config, not your shell; Codex also forwards
  818. the names listed in `env_vars`. Start a new session after editing, since
  819. clients read the config when a session starts.
  820. **Requests go to `/opik/api` on an open-source Opik** — `COMET_URL_OVERRIDE` is
  821. for a self-hosted Comet platform. Open source serves its API at `/api`: set
  822. `OPIK_URL=http://localhost:5173/api` (or `https://<host>/api`) instead. The
  823. server warns about this at startup when the host is this machine, and `--check`
  824. answers "No Opik API at …".
  825. **Cursor call times out at 60s** — Cursor's known bug, not `opik-mcp`. Either
  826. narrow the call (smaller `size`, a tighter window), or run the same operation
  827. on Claude Code which has no hard cap.
  828. **Server not showing, sign-in not opening, wrong workspace, `uvx` not found.**
  829. These are covered in the [troubleshooting section of the docs](https://www.comet.com/docs/opik/mcp-server/faq#troubleshooting).
  830. `uvx opik@latest mcp status` lists every client that has the server configured
  831. and whether its config has drifted.
  832. ---
  833. ## Development
  834. ```bash
  835. git clone git@github.com:comet-ml/opik-mcp.git
  836. cd opik-mcp
  837. make install # uv sync --locked --extra dev
  838. make check # lint + typecheck + test
  839. make run-dev # uvicorn with --reload + DEBUG logs
  840. make inspect # MCP Inspector against the running server
  841. ```
  842. Common targets:
  843. | Target | What it does |
  844. |---|---|
  845. | `make install` | `uv sync --locked --extra dev` |
  846. | `make run` | Run the MCP server (stdio by default). |
  847. | `make run-dev` | Run with DEBUG logging + uvicorn `--reload`. |
  848. | `make dev` | Run via `mcp dev` (Inspector dev-mode wrapper). |
  849. | `make inspect` | Launch MCP Inspector against a running server. |
  850. | `make test` | `uv run pytest -q`. |
  851. | `make lint` | `ruff check` + format check. |
  852. | `make format` | `ruff format` + `ruff check --fix`. |
  853. | `make typecheck` | `mypy`. |
  854. | `make check` | `lint + typecheck + test`. |
  855. Repo layout:
  856. ```
  857. opik-mcp/
  858. ├── src/opik_mcp/ ← server, tools, analytics
  859. ├── tests/ ← pytest suites
  860. ├── scripts/ ← live-BE smoke + MCP-session smoke
  861. ├── legacy/typescript/ ← migration guide for the deprecated v2 TS server (source: tag `legacy-typescript-final`)
  862. ├── pyproject.toml
  863. └── Makefile
  864. ```
  865. ---
  866. ## Get help
  867. - [Open an issue](https://github.com/comet-ml/opik-mcp/issues) for bugs and feature requests
  868. - [Opik docs](https://www.comet.com/docs/opik/) for SDK / backend documentation
  869. - [Comet community Slack](https://chat.comet.com/) for questions
  870. ---
  871. ## License
  872. Apache-2.0.
  873. <!-- The MCP Registry accepts server.json only if the PyPI description has the next line. Keep it. -->
  874. <!-- mcp-name: io.github.comet-ml/opik-mcp -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.