FAQ & troubleshooting

Clients read MCP servers and skills when a session starts.

• Start a new session.
• Run uvx opik mcp status. It lists the clients the CLI knows about that have the server, and the config file it lives in. If yours is missing, run uvx opik mcp configure again. Clients you configured by hand are not listed — check their config file.
• If setup printed exists but is not a valid JSON object, that client’s config has comments in it. Paste the block the CLI printed in by hand.

The hosted server signs you in through the browser on the first connection, and the client only tries once per session.

• Start a new session, then trigger sign-in from the client: /mcp in Claude Code, the MCP settings panel in Cursor, codex mcp login opik-mcp in Codex.
• On a corporate network, allow www.comet.com. On self-hosted Opik, allow your deployment’s domain and its identity provider.
• Sessions expire; when that happens the client asks you to sign in again.

You are connected but not signed in — those two tools are how you sign in.

• Ask your assistant to authenticate, or run the authenticate tool, and finish in the browser tab it opens.
• In Claude Code, run /mcp and choose Authenticate.
• The other tools appear once the sign-in completes.

The server points at a different workspace than you expect.

• Hosted server: the workspace was chosen at sign-in. Sign out and in again from the client’s MCP panel and pick the right one.
• Local server: run uvx opik configure, choose the workspace, then uvx opik mcp configure again, then start a new session.
• ✗ OUT OF SYNC in uvx opik mcp status means the client config is older than your Opik configuration. The same re-run fixes it.

To choose a server, the CLI checks a discovery endpoint on your deployment. If a proxy, VPN or TLS error blocks that check, it falls back to the local server and stores your API key in the client config.

• Re-run uvx opik mcp configure from a network that can reach the deployment.
• On self-hosted Opik without a hosted server, pass --local-server — that is the intended path.

uv is not installed, or the terminal was opened before the install finished. Install it with the one-liner on the overview, open a new terminal, and run uvx --version.

With the local server the client runs uvx opik-mcp, which downloads the package and a Python runtime on first use. Let the first call finish once; later calls start in about a second. If it fails outright, run uvx opik-mcp --help in a terminal to see the real error.

Cursor enforces a hard 60-second timeout per tool call that does not reset on progress, and reads of very large traces hit it.

• Ask for fewer traces, or for one span at a time.
• For long investigations use Claude Code or VS Code, which have no such cap.

No. uvx opik mcp configure needs only uv. The Cursor and VS Code buttons need nothing. npx add-mcp and npx skills add need Node. The language of your project does not matter.

On Opik Cloud, and any deployment that advertises it, you get the hosted server: your client signs in through the browser and nothing is stored in its config. Everywhere else, or with --local-server, you get the local server: uvx opik-mcp runs on your machine with OPIK_API_KEY and OPIK_WORKSPACE in the client’s env block. uvx opik mcp status shows which one each client uses. Advanced setup has the full comparison.

The agent acts with your permissions and cannot exceed them. One tool, write, can score, comment, save prompt versions and create traces, test suites and experiments; everything else is read-only, and nothing can be deleted — there is no delete operation at all. Keep your client’s tool approval on for writes. Trace content is text your users wrote, so treat anything the agent reads from a trace as data, not as instructions.

Not yet. Until then, use your client’s tool approval to gate the write tool.

Yes. The CLI covers Claude Code, Cursor, VS Code Copilot, Codex and opencode. For any other client on Opik Cloud, run npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp, or point the client at that URL yourself with the Streamable HTTP transport. Skills for other clients: npx skills add comet-ml/opik-skills. See Advanced setup.

Yes, as a custom connector pointed at https://www.comet.com/opik/api/v1/mcp. This gives you the MCP server; the skill pack is for coding agents only. Advanced setup has the steps and the self-hosted caveat.

One workspace per client config. On the hosted server you pick it at sign-in. On the local server, uvx opik configure switches it, then run uvx opik mcp configure again.

uvx opik@latest mcp configure. It re-runs setup for each client, reports the result per client, and refreshes the skill pack; a client whose config it could not write is reported, not silently skipped. Plain uvx opik reuses the version it already has cached. Start a new session afterwards.

There is no remove command. Use claude mcp remove opik-mcp or codex mcp remove opik-mcp, or delete the opik-mcp entry from your client’s MCP config file. Local server telemetry switches off with OPIK_MCP_ANALYTICS_ENABLED=false in the same config.