首页
/ Opik MCP 项目配置指南:环境变量与命令行参数详解

Opik MCP 项目配置指南:环境变量与命令行参数详解

2025-06-29 07:01:23作者:齐冠琰

项目概述

Opik MCP 是一个功能强大的管理控制平台服务器,用于协调和管理与 Opik API 的交互。本文将全面介绍如何通过命令行参数和环境变量两种方式配置 Opik MCP 服务器,帮助开发者根据实际需求灵活调整系统行为。

配置方式对比

Opik MCP 提供了两种主要的配置方式,各有其适用场景:

  1. 命令行参数:适合临时性配置调整,优先级高于环境变量
  2. 环境变量:适合持久化配置,可通过 .env 文件管理

在实际生产环境中,推荐使用环境变量进行配置,便于版本控制和统一管理。

命令行参数配置详解

基本启动命令

node build/index.js --apiUrl "https://www.comet.com/opik/api" --apiKey "your-api-key" --workspace "default"

关键参数说明

参数 缩写 描述 默认值 注意事项
--apiUrl -url API基础地址 必须提供
--apiKey -key API认证密钥 敏感信息,需妥善保管
--workspace -ws 工作区名称 "default" 通常保持默认值
--selfHosted 是否自托管 false 自托管需设为true
--debug 调试模式 false 开发时建议开启

功能模块控制参数

Opik MCP 采用模块化设计,可通过以下参数按需启用/禁用特定功能模块:

  • --disablePromptTools:禁用提示词相关工具
  • --disableProjectTools:禁用项目管理工具
  • --disableTraceTools:禁用追踪功能
  • --disableMetricTools:禁用指标收集

环境变量配置详解

环境变量配置更适合长期稳定的部署场景,可通过 .env 文件统一管理。

核心配置项

# API基础配置
OPIK_API_BASE_URL=https://www.comet.com/opik/api
OPIK_API_KEY=your-secret-key
OPIK_SELF_HOSTED=false
DEBUG_MODE=true

服务器参数配置

# MCP服务器标识
MCP_NAME=custom-server
MCP_VERSION=2.0.0

# 通信设置
MCP_TRANSPORT=sse  # 可选stdio或sse
MCP_SSE_PORT=3005  # SSE模式专用端口

传输协议选择

Opik MCP 支持两种通信协议:

  1. stdio:标准输入输出,适合简单场景
  2. sse:服务器发送事件(Server-Sent Events),适合需要实时通信的场景

选择SSE协议时,需要额外配置 MCP_SSE_PORT 参数。

最佳实践建议

  1. 工作区配置:除非有特殊需求,否则工作区名称应保持为"default"
  2. 敏感信息保护:API密钥等敏感信息不应硬编码在代码中,建议通过环境变量注入
  3. 生产环境配置
    • 关闭调试模式(DEBUG_MODE=false)
    • 启用日志记录(MCP_LOGGING=true)
    • 使用SSE协议以获得更好的实时性
  4. 模块化管理:根据实际需求启用/禁用功能模块,减少资源占用

常见问题解答

Q:如何判断应该使用命令行参数还是环境变量?

A:临时性测试使用命令行参数,正式部署使用环境变量。两者同时存在时,命令行参数优先级更高。

Q:自托管模式和云模式有何区别?

A:自托管模式(OPIK_SELF_HOSTED=true)需要配置本地API地址,云模式则使用预设的云端地址。

Q:为什么我的工作区设置无效?

A:请确认使用的是工作区名称而非项目名称,常见错误是将项目名称如"Therapist Chat"误用作工作区名称。

通过本文的详细讲解,开发者应能全面掌握Opik MCP的配置方法,根据实际场景选择最适合的配置方式,充分发挥平台的管理和控制能力。

登录后查看全文
热门项目推荐