Comet-ML/Opik-MCP

[!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

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

• API Reference
• Configuration
• IDE Integration
• Streamable HTTP Transport

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