Comet Opik MCP Server for Prompts, Traces, Metrics

Overview

Comet Opik MCP Server is a TypeScript implementation of a Model Context Protocol (MCP) server intended to give MCP-aware clients unified access to prompts, traces, projects, metrics, and related resources. It can run locally over stdio (for IDE integrations that launch a local process) or as a streamable HTTP endpoint for self-hosted or remote deployments. The server maps Opik concepts (workspaces, projects, prompts, traces, datasets, metrics) into MCP resources so editors and tooling can inspect and act on model-context state with a consistent API.

This server is useful when you want IDE integrations and other MCP clients (VS Code, Windsurf, Copilot tooling, etc.) to surface prompt libraries, trace histories, and metrics without each tool needing bespoke APIs. It supports authentication and workspace resolution for remote deployments, plus configuration controls to enable only the toolsets you want in production or development environments.

Features

• MCP-compatible server exposing:
  • Prompts and prompt templates (list / get)
  • Resources and resource templates (static and templated URIs)
  • Traces, projects, workspaces, datasets, and metrics operations
• Two transport modes:
  • stdio for local client integration
  • streamable-http for remote/self-hosted MCP endpoints
• Built in TypeScript, Node >= 20.11.0
• Toolset gating to enable/disable capability groups (core, metrics, expert-*)
• Remote authentication controls and workspace token mapping
• Extensible resource URIs and templates for metadata-aware flows
• Local dev tooling: lint, test, build, and precommit scripts

Installation / Configuration

Install and run quickly with npx (recommended for local use):

# Run against Opik Cloud (provide actual API key)
npx -y opik-mcp --apiKey YOUR_API_KEY

Run against a self-hosted Opik instance:

npx -y opik-mcp --apiKey YOUR_API_KEY --apiUrl http://localhost:5173/api

Run from source:

git clone https://github.com/comet-ml/opik-mcp.git
cd opik-mcp
npm install
npm run build

# start local stdio transport
npm run start:stdio

# start streamable HTTP transport (exposes /mcp)
npm run start:http

Common CLI flags and environment variables:

• CLI: –toolsets (e.g. –toolsets core,metrics or –toolsets all)
• Env: OPIK_TOOLSETS (comma-separated)
• Auth & remote behavior:
  • STREAMABLE_HTTP_REQUIRE_AUTH (default: true)
  • STREAMABLE_HTTP_VALIDATE_REMOTE_AUTH (default: true)
  • REMOTE_TOKEN_WORKSPACE_MAP (JSON token->workspace map)
  • STREAMABLE_HTTP_TRUST_WORKSPACE_HEADERS (default: false)

Transport summary:

Repository: https://github.com/comet-ml/opik-mcp

Available Resources

The server exposes MCP resources and templates enabling clients to discover actionable URIs:

• resources/list — returns static resource URIs (e.g. opik://workspace-info)
• resources/templates/list — returns URI templates (e.g. opik://projects/{page}/{size})
• resources/read — reads both static and templated URIs resolved against Opik
• prompts/list and prompts/get — enumerates prompt workflows and retrieves prompt definitions
• traces, projects, datasets, and metrics endpoints for read/explore operations

Toolsets determine which of the above are visible to clients (see Installation / Configuration).

Integrating with MCP Clients

Example MCP cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
    }
  }
}

VS Code MCP server example (.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"]
    }
  }
}

Use Cases

• IDE Prompt Authoring: Enable prompt authors to browse project prompts, insert templates into editor buffers, and version prompt drafts using the MCP prompt endpoints.
• Trace Exploration: Inspect recent conversation traces and associated metadata in the editor to reproduce or refine model runs without switching to a separate dashboard.
• Metric and Dataset Observability: Query metrics and dataset references from within a notebook or IDE panel to correlate prompt changes with performance shifts.
• Self-hosted Teams: Run streamable-http behind your internal auth and network layer to let teams access Opik resources via corporate tooling while enforcing token->workspace mapping.
• Automation & Tooling: Use the resource templates to programmatically enumerate projects or datasets for CI pipelines, experiments, or reproducible prompt workflows.

Development & Contribution

Common developer tasks:

# lint
npm run lint

# test
npm test

# build
npm run build

# run precommit checks
make precommit

Read CONTRIBUTING.md and the repository documentation for API references, configuration details, and transport deep dives (IDE integration, streamable-http).