opik-mcp

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

• 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