Opik MCP Server

Model Context Protocol (MCP) server for Opik, with both local stdio and remote streamable-http transports.

Website • Slack community • Twitter • Documentation

[!IMPORTANT]
This repository ships the MCP server implementation only. We do not currently provide a hosted remote MCP service for Opik.
If you run streamable-http remotely, authentication is fail-closed by default.

Why this server

Opik MCP Server gives MCP-compatible clients one interface for:

Prompt lifecycle management
Workspace, project, and trace exploration
Metrics and dataset operations
MCP resources and resource templates for metadata-aware flows

Quickstart

1. Run with npx

# Opik Cloud
npx -y opik-mcp --apiKey YOUR_API_KEY

For self-hosted Opik, pass --apiUrl (for example http://localhost:5173/api) and use your local auth strategy.

2. Add to your MCP client

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
    }
  }
}

VS Code / GitHub Copilot (.vscode/mcp.json):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opik-api-key",
      "description": "Opik API Key",
      "password": true
    }
  ],
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "opik-mcp", "--apiKey", "${input:opik-api-key}"]
    }
  }
}

Windsurf (raw config):

{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
    }
  }
}

More client-specific examples: docs/ide-integration.md

Run from source

git clone https://github.com/comet-ml/opik-mcp.git
cd opik-mcp
npm install
npm run build

Optional local config:

cp .env.example .env

Start the server:

npm run start:stdio
npm run start:http

Transport modes

Transport	Use case	Command
`stdio`	Local MCP integration (same machine as client)	`npm run start:stdio`
`streamable-http`	Remote/self-hosted MCP endpoint (`/mcp`)	`npm run start:http`

Remote auth defaults (`streamable-http`)

Authorization: Bearer <OPIK_API_KEY> or x-api-key is required by default.
Workspace is resolved server-side (token map recommended); workspace headers are not trusted by default.
In remote mode, request-context workspace takes precedence over tool workspaceName.
Missing or invalid auth returns HTTP 401.

Key environment flags:

STREAMABLE_HTTP_REQUIRE_AUTH (default true)
STREAMABLE_HTTP_VALIDATE_REMOTE_AUTH (default true, except test env)
REMOTE_TOKEN_WORKSPACE_MAP (JSON token-to-workspace map)
STREAMABLE_HTTP_TRUST_WORKSPACE_HEADERS (default false)

Deep dive: docs/streamable-http-transport.md

Toolsets

Toolsets let you narrow which capabilities are enabled:

core
integration
expert-prompts
expert-datasets
expert-trace-actions
expert-project-actions
metrics
all (enables all modern toolsets)

Configure via:

CLI: --toolsets all
Env: OPIK_TOOLSETS=core,expert-prompts,metrics

Details: docs/configuration.md

MCP resources and prompts

resources/list exposes static URIs (for example opik://workspace-info)
resources/templates/list exposes dynamic URI templates (for example opik://projects/{page}/{size})
resources/read supports static and templated URIs
prompts/list and prompts/get expose workflow prompts

Development

# Lint
npm run lint

# Test
npm test

# Build
npm run build

# Run precommit checks
make precommit

Documentation

Contributing

Please read CONTRIBUTING.md before opening a PR.

Citation

If you use this project in research, cite:

Comet ML, Inc, Koc, V., & Boiko, Y. (2025). Opik MCP Server. Github. https://doi.org/10.5281/zenodo.15411156

BibTeX:

@software{CometML_Opik_MCP_Server_2025,
  author = {{Comet ML, Inc} and Koc, V. and Boiko, Y.},
  title = {{Opik MCP Server}},
  year = {2025},
  publisher = {GitHub},
  url = {https://doi.org/10.5281/zenodo.15411156},
  doi = {10.5281/zenodo.15411156}
}

Citation metadata is also available in CITATION.cff.

License

Apache 2.0