Opik MCP Server
Model Context Protocol (MCP) server for Opik, with both local stdio and remote streamable-http transports.
[](https://github.com/comet-ml/opik-mcp/blob/main/LICENSE)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
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
```bash
# 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`):
```json
{
"mcpServers": {
"opik": {
"command": "npx",
"args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
}
}
}
```
VS Code / GitHub Copilot (`.vscode/mcp.json`):
```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):
```json
{
"mcpServers": {
"opik": {
"command": "npx",
"args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
}
}
}
```
More client-specific examples: [docs/ide-integration.md](docs/ide-integration.md)
## Run from source
```bash
git clone https://github.com/comet-ml/opik-mcp.git
cd opik-mcp
npm install
npm run build
```
Optional local config:
```bash
cp .env.example .env
```
Start the server:
```bash
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 ` 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](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](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
```bash
# Lint
npm run lint
# Test
npm test
# Build
npm run build
# Run precommit checks
make precommit
```
## Documentation
- [API Reference](docs/api-reference.md)
- [Configuration](docs/configuration.md)
- [IDE Integration](docs/ide-integration.md)
- [Streamable HTTP Transport](docs/streamable-http-transport.md)
## Contributing
Please read [CONTRIBUTING.md](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:
```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](CITATION.cff).
## License
Apache 2.0