Orq.ai MCP Server

什么是 Orq.ai MCP Server？

Orq.ai MCP Server 是 Orq.ai 官方的远程 MCP 服务器。它把 Claude Code、Claude Desktop、Cursor、VS Code、Codex 和 Warp 连接到你的 Orq.ai 工作区，让你不离开编辑器就能管理智能体、数据集、实验、评估器和链路追踪。

Orq.ai 是一个用于构建和运营 LLM 应用的平台：跨模型服务商的 AI 网关、托管智能体、评估与实验、可观测性、知识库和治理。MCP 服务器最早在 Orq.ai 4.4 中以测试版发布，现在提供 11 个类别共 38 个工具。它与 Orq.ai 的 MCP Portal 和 MCP Gateway 不同，后两者用于把第三方 MCP 服务器接入 Orq 智能体。

如何使用 Orq.ai MCP Server？

你需要一个 Orq.ai 账号。该端点支持两种认证方式：

• OAuth：添加端点时不带 Authorization 请求头。支持 OAuth 的客户端会在浏览器中打开 Orq.ai 登录流程，并请求访问工作区。
• API key：使用你 Orq.ai 工作区中的 key，设置请求头 Authorization: Bearer YOUR_ORQ_API_KEY。

https://my.orq.ai/v2/mcp

Claude Code

来自 Orq.ai 文档（OAuth）：

claude mcp add --transport http orq https://my.orq.ai/v2/mcp

如果改用 API key，添加 --header "Authorization: Bearer YOUR_ORQ_API_KEY"。

Claude Desktop 和 claude.ai

打开 Settings → Connectors → Add custom connector，命名为“Orq.ai”并粘贴 URL，然后完成 Orq.ai 登录。

Cursor

Orq.ai 文档建议把端点添加为远程 HTTP 服务器，并在使用 OAuth 时不填请求头。在 ~/.cursor/mcp.json 中：

{
  "mcpServers": {
    "orq": {
      "url": "https://my.orq.ai/v2/mcp"
    }
  }
}

VS Code

在 .vscode/mcp.json 中：

{
  "servers": {
    "orq": {
      "type": "http",
      "url": "https://my.orq.ai/v2/mcp"
    }
  }
}

客户端提示时，在浏览器中完成 OAuth。

Orq.ai MCP Server 的主要功能

• Orq.ai 官方服务器，支持 OAuth 登录或 API key 认证。
• 智能体管理：创建、更新（带语义化版本）、调用智能体并获取其响应。
• 数据集：创建数据集，添加、编辑或删除数据点（每次最多 100 个），包括合成测试数据。
• 实验：基于数据集创建运行、列出运行，并以 JSON、JSONL 或 CSV 导出结果。
• 评估器：创建和更新 LLM-as-a-Judge 和 Python 评估器。
• 可观测性：按条件列出 trace 和 span，并查询工作区在成本、延迟、token 和错误方面的分析数据。
• 跨项目、提示词、智能体等实体的搜索，以及文档搜索工具。
• 在同一会话中管理技能和部署。

Orq.ai MCP Server 的使用场景

• 在聊天中构建智能体：“创建一个名为 Support Bot 的客服智能体，回答关于我们 SaaS 产品的问题，语气简洁专业。”
• 回归测试：“用这 20 个失败的提示词创建数据集，并运行一个比较两个模型的实验。”
• 排查生产问题：“从昨天起哪些 trace 抛出了 500 错误？”
• 知识库缺口：“列出所有没有检索到知识库内容的查询。”
• 成本监控：“我们每次请求的平均成本在上升吗？哪些模型带来了主要开销？”
• 质量门槛：“添加一个 LLM-as-a-Judge 评估器，检查回答中是否编造了价格。”

Orq.ai MCP Server 常见问题排查

• 工具报错“API key lacks permission”。 使用 API key 时，每次调用都以该 key 的权限运行。请授予所需权限，或改用 OAuth，此时调用以登录用户身份运行。
• 只读 key 仍然写入了数据。 Orq.ai 说明其权限检查尚未覆盖所有写入工具，因此只读 key 并不是完整的保护措施。请检查智能体可以调用哪些工具。
• update_agent 被拒绝。 每次更新都需要 versionIncrement（major、minor 或 patch）和 versionDescription。
• 需要 MCP 工具没有覆盖的功能。 Orq.ai 的 CLI 覆盖范围更广（提示词、预算、webhook 等），也更适合脚本和 CI。