Okareo

Okareo MCP Server

Okareo MCP 服务将 Okareo 的评估能力作为 MCP 工具提供，使 AI 编码助手能够直接在编辑器中创建和管理场景、注册模型、运行评估并执行多轮模拟。

如需详细文档，请参阅 Okareo MCP 文档。

先决条件

• 一个 Okareo 账户，访问地址：app.okareo.com
• 支持 MCP 服务的 copilot（Claude Code、Cursor、VS Code 或 GitHub Copilot），或 Slack 中的 Slackbot
• Python 3.10–3.12（仅本地安装模式需要；远程模式不需要）

---

远程 MCP（托管）— 推荐

最快的入门方式。无需本地安装，无需 Python，也无需在 .mcp.json 中填写 API 密钥。首次连接时，通过浏览器登录即可完成身份验证。

推荐方式（OAuth — Claude Code、Claude Desktop、Cursor、VS Code 1.101+）

将以下内容添加到 copilot 的 MCP 配置中（通常为 .mcp.json）：

{
  "mcpServers": {
    "okareo": {
      "type": "http",
      "url": "https://tools.okareo.com/mcp"
    }
  }
}

重新加载 copilot。它会打开浏览器，让你登录 Okareo；之后，copilot 会自行保存令牌。你的 .mcp.json 中不会包含任何机密信息。

备用方式（Bearer 标头 — 较旧的客户端或无头 / CI 环境）

对于尚未支持 MCP OAuth 流程的客户端，请将 API 密钥粘贴为 bearer 标头。建议使用环境变量形式，而非直接写入字面值：

{
  "mcpServers": {
    "okareo": {
      "type": "http",
      "url": "https://tools.okareo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:OKAREO_API_KEY}"
      }
    }
  }
}

GitHub Copilot（VS Code 和 Copilot CLI 中）、Slackbot 以及其他所有客户端的设置说明，请参阅 docs.okareo.com/mcp/configuration。

在多个 Okareo 组织间切换

如果你有权访问多个 Okareo 账户，只需执行 Clear Authentication，然后使用要操作的账户重新进行身份验证。你可以随时询问当前登录的账户，以及你有权访问的账户。

---

本地安装（替代方案）

在自己的计算机上运行 MCP 服务。适用于离线 / 隔离网络环境以及开发场景。

除非你有特定的本地安装需求（隔离网络、自定义构建或在此代码库中开发），否则建议使用上面的 远程 MCP 部分。远程端点无需安装，并会自动保持最新。

对于拥有多个组织的用户，远程端点还提供租户管理工具（list_tenants、switch_tenant）。

第 1 步：设置 API 密钥

export OKAREO_API_KEY="your-api-key"

将此内容添加到 ~/.zshrc 或 ~/.bash_profile，以便持久保存。

第 2 步：配置 Copilot

Claude Code

添加到 .mcp.json：

{
  "mcpServers": {
    "okareo": {
      "command": "uvx",
      "args": ["okareo-mcp"],
      "env": {
        "OKAREO_API_KEY": "${OKAREO_API_KEY}"
      }
    }
  }
}

无需预先安装 — uvx 会自动处理。

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "okareo": {
      "command": "uvx",
      "args": ["okareo-mcp"]
    }
  }
}

Cursor 会从 shell 环境继承 OKAREO_API_KEY。

替代方案：pip install

如果你尚未安装 uv：

pip install okareo-mcp

然后使用 "command": "okareo-mcp"，替代 "command": "uvx" 和 "args": ["okareo-mcp"]。

---

配置参考

变量	默认值	说明
OKAREO_API_KEY	（必需）	你的 Okareo API 密钥
OKAREO_BASE_URL	https://api.okareo.com	覆盖本地部署的 Okareo 后端地址
TRANSPORT	stdio	传输方式：stdio（本地）或 sse（Docker）
PORT	8000	SSE 传输端口

---

可用工具

场景

工具	说明
save_scenario	根据输入 / 结果数据行保存命名场景（幂等）
list_scenarios	列出项目中的所有场景，包括名称、ID 和行数
get_scenario	按名称或 ID 获取场景的元数据和所有数据行
create_scenario_version	使用更新后的数据为现有场景创建新版本
preview_delete_scenario	删除场景前预览将被删除的内容
delete_scenario	永久删除场景及所有相关测试数据

生成模型

工具	描述
list_available_llms	浏览 Okareo 注册表中的可用大模型
register_generation_model	从注册表中选择一个大模型，注册生成模型以供测试
list_generation_models	列出项目中所有已注册的生成模型
get_generation_model	读取已注册生成模型的详细信息
update_generation_model	更改已注册生成模型所指向的大模型
delete_generation_model	移除已注册的生成模型及其所有相关测试数据

测试与检查项

工具	描述
list_checks	列出用于评估模型输出质量的可用检查项（内置和自定义）
run_test	运行质量测试，使用指定的检查项，根据场景评估模型
list_test_runs	查找以最近优先排序的过往测试运行。detail_level="summary"（默认）或 "detailed"（聚合指标）
get_test_run_results	根据 ID 或名称加载某次运行的一页结果。detail_level="summary"（默认）/ "detailed"（逐项检查结果和说明）/ "full"（对话记录）。默认包含 20 段对话。附带 rerun 区块，其中包含重新运行此模拟的调用和配置
get_conversation_transcript	获取单个数据点的完整对话记录
reevaluate_test_run	使用一组（可能不同的）检查项重新评估已完成的测试运行
create_or_update_check	按名称创建或更新质量检查项——基于模型、基于代码或音频（upsert）
generate_check	根据自然语言描述生成检查项，然后保存
get_check	获取检查项的完整配置，包括其提示词模板或代码
delete_check	按名称永久删除检查项
calibrate_check	对已完成的测试运行试运行草稿检查项——提供逐行判定结果和检查项收到的参数，不保存任何内容

模拟（多轮）

工具	描述
create_or_update_target	创建或更新 Target——生成模型、自定义端点或语音（OpenAI、Deepgram、Twilio）
get_target	按名称获取 Target 的配置（所有类型）
list_targets	查找模拟目标（语音和 custom_endpoint）。默认上限为 20；可通过 name_contains 筛选
delete_target	移除模拟目标及其所有相关测试数据
create_or_update_driver	定义一个将与目标交互的模拟用户角色
get_driver	获取 Driver 的完整配置，包括角色提示词
list_drivers	查找 Driver 角色。默认上限为 20；可通过 name_contains 筛选
list_driver_voices	查找语音 Driver 可用的声音、声音配置和语言
run_simulation	运行多轮对话评估。使用 based_on_run_id 时，会继承原始运行的完整配置；传入的任何参数都会覆盖对应字段
list_simulations	列出过往模拟运行，可选按目标、场景和数量限制筛选

语音监控

工具	描述
ingest_conversations	将已完成的语音对话提交给 Okareo 进行监控
connect_voice_integration	连接语音提供商，使其流量进入 Okareo 监控
list_voice_integrations	列出项目中的语音提供商集成
get_voice_integration	按 ID 获取语音提供商集成，包括其状态
update_voice_integration	更新语音提供商集成的元数据
rotate_voice_integration_secret	轮换语音提供商集成的密钥
delete_voice_integration	按 ID 删除语音提供商集成
get_voice_webhook_url	获取语音提供商的入站 webhook 端点

项目

工具	描述
list_projects	列出你可以使用的所有项目，包括 ID、名称、标签和归档状态，并标记当前项目
select_project	选择本次对话要使用的项目
create_project	创建新项目
update_project	重命名项目或替换其标签
archive_project	将项目从项目选择器中隐藏。此操作可撤销；不会删除任何内容
unarchive_project	将已归档的项目恢复到项目选择器中
clone_project	将现有项目的场景复制到新项目中（先试运行）

Okareo 不支持删除项目——无论是在应用、API 还是此处都不支持。归档即为移除，它只会将项目从项目选择器中隐藏：项目中的场景、运行记录和仪表板都会保持不变，且所有工具仍可对其进行操作。

分析与仪表板

工具	描述
query_analytics	查询 Okareo 的产品分析数据，了解评估趋势
list_dashboards	列出项目中的分析仪表板
get_dashboard	按名称获取仪表板的完整配置
save_dashboard	按名称创建或更新分析仪表板（upsert）
reorder_dashboards	设置仪表板的显示顺序
delete_dashboard	按名称删除仪表板

租户管理（仅限远程 MCP）

工具	描述
list_tenants	列出你在此 MCP 会话中有权访问的所有 Okareo 组织
switch_tenant	不会更改当前组织；返回重新连接并在登录时选择其他组织的方式

文档与模板

工具	描述
get_docs	查询 Okareo 文档系统，获取概念性说明或便于用户理解的解释
get_templates	获取适用于常见 Okareo 模式的提示词模板（可离线使用）
get_reps_baseline	提供最新标记的 okareo-tools 版本中的 REPS Agent 评估基线材料（场景库、驱动程序、检查项、评估配置）

---

故障排除

症状	原因	解决方法
okareo-mcp: command not found	未安装或不在 PATH 中	运行 pip install -e .（开发环境）或使用 uvx okareo-mcp（用户环境）
服务因 API 密钥错误而退出	未设置 OKAREO_API_KEY	导出该变量：export OKAREO_API_KEY="..."
在 Python 3.13+ 上运行 pip install 失败	Okareo SDK 要求 Python <3.13	使用 Python 3.10–3.12
Copilot 无法连接（Docker）	URL 错误	确保 URL 以 /sse 结尾，且端口匹配
Cursor 未读取 API 密钥	Cursor 是从 Dock 而非终端启动的	从终端启动 Cursor：cursor .

---

贡献

此仓库是经过整理的公开镜像；规范源代码由 Okareo 维护。我们欢迎提交问题，也会考虑社区拉取请求——有关提议变更的审核和移植方式，请参阅 CONTRIBUTING.md。

许可证与商标

Okareo MCP 服务源代码遵循 Apache License 2.0 许可（另请参阅 NOTICE）。

“Okareo”、Okareo 徽标以及 Okareo 产品名称均为 Okareo, Inc. 的商标，不受 Apache 2.0 许可证涵盖。有关允许的使用方式，请参阅 TRADEMARK.md。