Opik MCP Server

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

Related MCP server: OpenAI MCP Server

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