\n\n> [!IMPORTANT]\n> This repository ships the MCP server implementation only. We do not currently provide a hosted remote MCP service for Opik.\n> If you run `streamable-http` remotely, authentication is fail-closed by default.\n\n## Why this server\n\nOpik MCP Server gives MCP-compatible clients one interface for:\n\n- Prompt lifecycle management\n- Workspace, project, and trace exploration\n- Metrics and dataset operations\n- MCP resources and resource templates for metadata-aware flows\n\n## Quickstart\n\n### 1. Run with npx\n\n```bash\n# Opik Cloud\nnpx -y opik-mcp --apiKey YOUR_API_KEY\n```\n\nFor self-hosted Opik, pass `--apiUrl` (for example `http://localhost:5173/api`) and use your local auth strategy.\n\n### 2. Add to your MCP client\n\nCursor (`.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"opik\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"opik-mcp\", \"--apiKey\", \"YOUR_API_KEY\"]\n }\n }\n}\n```\n\nVS Code / GitHub Copilot (`.vscode/mcp.json`):\n\n```json\n{\n \"inputs\": [\n {\n \"type\": \"promptString\",\n \"id\": \"opik-api-key\",\n \"description\": \"Opik API Key\",\n \"password\": true\n }\n ],\n \"servers\": {\n \"opik-mcp\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"opik-mcp\", \"--apiKey\", \"${input:opik-api-key}\"]\n }\n }\n}\n```\n\nWindsurf (raw config):\n\n```json\n{\n \"mcpServers\": {\n \"opik\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"opik-mcp\", \"--apiKey\", \"YOUR_API_KEY\"]\n }\n }\n}\n```\n\nMore client-specific examples: [docs/ide-integration.md](docs/ide-integration.md)\n\n## Run from source\n\n```bash\ngit clone https://github.com/comet-ml/opik-mcp.git\ncd opik-mcp\nnpm install\nnpm run build\n```\n\nOptional local config:\n\n```bash\ncp .env.example .env\n```\n\nStart the server:\n\n```bash\nnpm run start:stdio\nnpm run start:http\n```\n\n## Transport modes\n\n| Transport | Use case | Command |\n| --- | --- | --- |\n| `stdio` | Local MCP integration (same machine as client) | `npm run start:stdio` |\n| `streamable-http` | Remote/self-hosted MCP endpoint (`/mcp`) | `npm run start:http` |\n\n### Remote auth defaults (`streamable-http`)\n\n- `Authorization: Bearer ` or `x-api-key` is required by default.\n- Workspace is resolved server-side (token map recommended); workspace headers are not trusted by default.\n- In remote mode, request-context workspace takes precedence over tool `workspaceName`.\n- Missing or invalid auth returns HTTP `401`.\n\nKey environment flags:\n\n- `STREAMABLE_HTTP_REQUIRE_AUTH` (default `true`)\n- `STREAMABLE_HTTP_VALIDATE_REMOTE_AUTH` (default `true`, except test env)\n- `REMOTE_TOKEN_WORKSPACE_MAP` (JSON token-to-workspace map)\n- `STREAMABLE_HTTP_TRUST_WORKSPACE_HEADERS` (default `false`)\n\nDeep dive: [docs/streamable-http-transport.md](docs/streamable-http-transport.md)\n\n## Toolsets\n\nToolsets let you narrow which capabilities are enabled:\n\n- `core`\n- `integration`\n- `expert-prompts`\n- `expert-datasets`\n- `expert-trace-actions`\n- `expert-project-actions`\n- `metrics`\n- `all` (enables all modern toolsets)\n\nConfigure via:\n\n- CLI: `--toolsets all`\n- Env: `OPIK_TOOLSETS=core,expert-prompts,metrics`\n\nDetails: [docs/configuration.md](docs/configuration.md)\n\n## MCP resources and prompts\n\n- `resources/list` exposes static URIs (for example `opik://workspace-info`)\n- `resources/templates/list` exposes dynamic URI templates (for example `opik://projects/{page}/{size}`)\n- `resources/read` supports static and templated URIs\n- `prompts/list` and `prompts/get` expose workflow prompts\n\n## Development\n\n```bash\n# Lint\nnpm run lint\n\n# Test\nnpm test\n\n# Build\nnpm run build\n\n# Run precommit checks\nmake precommit\n```\n\n## Documentation\n\n- [API Reference](docs/api-reference.md)\n- [Configuration](docs/configuration.md)\n- [IDE Integration](docs/ide-integration.md)\n- [Streamable HTTP Transport](docs/streamable-http-transport.md)\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.\n\n## Citation\n\nIf you use this project in research, cite:\n\n```\nComet ML, Inc, Koc, V., & Boiko, Y. (2025). Opik MCP Server. Github. https://doi.org/10.5281/zenodo.15411156\n```\n\nBibTeX:\n\n```bibtex\n@software{CometML_Opik_MCP_Server_2025,\n author = {{Comet ML, Inc} and Koc, V. and Boiko, Y.},\n title = {{Opik MCP Server}},\n year = {2025},\n publisher = {GitHub},\n url = {https://doi.org/10.5281/zenodo.15411156},\n doi = {10.5281/zenodo.15411156}\n}\n```\n\nCitation metadata is also available in [CITATION.cff](CITATION.cff).\n\n## License\n\nApache 2.0\n","readmeFilename":"README.md"}
![\"Comet](\"docs/assets/logo-light-mode.svg\")
\n ![\"DOI\"](\"https://zenodo.org/badge/DOI/10.5281/zenodo.15411156.svg\"){kind=icon}
\n\n