comet-ml/opik-mcp
If you are the rightful owner of opik-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
Opik MCP Server is an open-source implementation of the Model Context Protocol for the Opik platform, providing a unified interface for interacting with Opik's capabilities.
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-httpremotely, 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:
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>orx-api-keyis 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(defaulttrue)STREAMABLE_HTTP_VALIDATE_REMOTE_AUTH(defaulttrue, except test env)REMOTE_TOKEN_WORKSPACE_MAP(JSON token-to-workspace map)STREAMABLE_HTTP_TRUST_WORKSPACE_HEADERS(defaultfalse)
Deep dive:
Toolsets
Toolsets let you narrow which capabilities are enabled:
coreintegrationexpert-promptsexpert-datasetsexpert-trace-actionsexpert-project-actionsmetricsall(enables all modern toolsets)
Configure via:
- CLI:
--toolsets all - Env:
OPIK_TOOLSETS=core,expert-prompts,metrics
Details:
MCP resources and prompts
resources/listexposes static URIs (for exampleopik://workspace-info)resources/templates/listexposes dynamic URI templates (for exampleopik://projects/{page}/{size})resources/readsupports static and templated URIsprompts/listandprompts/getexpose workflow prompts
Development
# Lint
npm run lint
# Test
npm test
# Build
npm run build
# Run precommit checks
make precommit
Documentation
Contributing
Please read 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 .
License
Apache 2.0
