QVeris MCP 服务器文档

简介#

@qverisai/mcp 是面向 Cursor 及其他编程 Agent 等 MCP 兼容客户端的官方 QVeris MCP 服务器。

@qverisai/mcp v0.12.0 是最新测试版本，通过六个规范 MCP 工具为 Agent 提供 QVeris 访问能力：

• discover — 用自然语言发现能力
• inspect — 获取工具详情（参数、成功率、示例）
• probe — 不执行能力的参数校验与报价
• call — 执行工具并传入参数
• usage_history — 上下文安全的调用审计摘要 / 精确查询 / 文件导出
• credits_ledger — 上下文安全的最终积分账本摘要 / 精确查询 / 文件导出

换言之，MCP 服务器是本仓库其他文档所描述的 QVeris 核心协议的 Agent 侧传输层。

MCP 与 REST API 对比#

适合使用 MCP 服务器的场景：

• 将 QVeris 集成到 Cursor、OpenCode 或其他 MCP 客户端
• 希望 Agent 在对话中直接调用 QVeris 工具
• 希望客户端自动管理工具调用

适合使用 REST API 的场景：

• 编写应用代码或后端服务
• 需要对请求和响应进行直接的 HTTP 控制
• 构建 SDK 封装或生产环境集成

两种方式均映射到同一套 QVeris 协议：

**注意：**旧工具名称（search_tools、get_tools_by_ids、execute_tool）仍作为弃用别名支持。

环境要求#

• Node.js 18+
• 有效的 QVERIS_API_KEY
• MCP 兼容客户端

快速开始#

通过 npx 安装#

npx -y @qverisai/mcp

MCP 服务器从以下环境变量读取配置：

QVERIS_API_KEY=your-api-key          # 必填
QVERIS_BASE_URL=https://qveris.cn/api/v1  # 必填：设置 API 地址

使用 QVeris CLI 配置#

可以用 CLI 生成客户端配置，无需手写 JSON。默认会打印带有 YOUR_QVERIS_API_KEY 占位符的安全配置；占位符输出会故意无法通过 API key 校验，直到你替换占位符或使用 --include-key。

export QVERIS_BASE_URL="https://qveris.cn/api/v1"
 
# 打印安全的 Cursor 配置
qveris mcp configure --target cursor
 
# 使用 qveris login 或 QVERIS_API_KEY 中的 API key 写入可直接使用的配置
qveris mcp configure --target cursor --write --include-key
qveris mcp configure --target opencode --write --include-key
qveris mcp configure --target openclaw --write --include-key

重启客户端前可以先校验配置：

qveris mcp validate --target cursor

对 stdio 客户端，可添加 --probe 启动配置中的 MCP server，并通过 tools/list 确认 discover、inspect、probe、call 可见：

qveris mcp validate --target cursor --probe

Cursor 配置示例#

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key-here",
        "QVERIS_BASE_URL": "https://qveris.cn/api/v1"
      }
    }
  }
}

各环境的详细配置指南，请参考：

• Agent 安装指南
• OpenCode 配置
• IDE / CLI 配置

Hosted MCP#

QVeris 提供远程 Streamable HTTP MCP 托管服务，无需安装本地软件包或运行后台进程。如果端点暂时不可用，请在托管服务发布完成前继续使用上文的本地 stdio 软件包。

https://mcp.qveris.cn/mcp

在支持远程 MCP 的客户端中添加服务地址，并在每次请求中发送 QVeris API 密钥：

{
  "mcpServers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.cn/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_QVERIS_API_KEY"
      }
    }
  }
}

接入步骤：

1. 在控制台/API 密钥创建密钥。
2. 将服务地址和 Bearer 请求头添加到客户端。客户端支持时，请用密钥管理或环境变量保存 API 密钥，切勿提交到源代码仓库。
3. 重新连接客户端，确认 discover、inspect、probe、call 可见。

服务会在会话启动时验证并绑定密钥。401 表示密钥缺失或无效；503 表示验证服务暂时不可用。更换密钥后请新建 MCP 会话。可前往托管 MCP 页面复制配置。

不支持远程 Streamable HTTP MCP 的客户端仍可使用本地 stdio 软件包。

可用 MCP 工具#

1. discover#

使用自然语言发现能力。

这是**发现（Discover）**操作，免费使用。

示例：

{
  "query": "天气预报 API",
  "limit": 10,
  "view": "routing",
  "lang": "zh"
}

典型响应字段：

• search_id
• total
• results[]
• results[].tool_id
• results[].params
• results[].examples
• results[].stats

2. inspect#

在复用或调用之前，检查一个或多个已知 tool_id 的详情。

这是**检查（Inspect）**操作。

示例：

{
  "tool_ids": ["openweathermap.weather.execute.v1"],
  "search_id": "YOUR_SEARCH_ID"
}

以下情况建议使用 inspect：

• 多个候选能力看起来类似
• 调用前想重新确认参数
• 想检查成功率或延迟数据
• 复用上一轮对话中发现的工具

响应结构与 /search 一致，包含所请求工具的参数、示例和统计数据。

3. probe#

用于在不执行能力的情况下校验候选参数并获取零成本报价。输入包括 tool_id、可选 parameters、可选 checks（schema、quote、coverage、sample）以及可选 live_budget（none、metadata、sampled）。当前已实现 schema 与 quote；coverage 和 sample 可能返回 unknown。Probe 不执行能力，也不消耗 credits。

4. call#

调用已发现的 QVeris 能力。

调用响应可能包含 compact 的 billing 预结算账单。最终是否扣费请通过 usage_history 或 credits_ledger 查询。

示例：

{
  "tool_id": "openweathermap.weather.execute.v1",
  "search_id": "YOUR_SEARCH_ID",
  "params_to_tool": {"city": "北京", "units": "metric"},
  "respond_with": "summary"
}

投影参数仅在显式指定时发送。旧服务返回 422 extra_forbidden 时仅移除对应可选字段并重试一次；无效投影仍按错误返回。

典型成功响应字段：

• execution_id
• tool_id（所选投影返回时）
• success
• result.data，或显式请求的精简摘要字段
• elapsed_time_ms 或 execution_time
• billing / pre_settlement_bill（如可用）

5. usage_history#

当用户询问某次调用是否成功、失败或扣费时使用。默认 summary 模式，不会把全量历史塞进上下文。

常用参数：

• mode: summary、search 或 export_file
• execution_id / search_id
• charge_outcome: charged、included、failed_not_charged、failed_charged_review
• min_credits / max_credits
• start_date / end_date

summary 模式会优先请求服务端 summary=true 聚合摘要；若旧部署暂不支持，则回退到有上限的客户端聚合。

示例：

{ "mode": "search", "execution_id": "EXECUTION_ID" }

6. credits_ledger#

当用户询问余额为何变化时使用。默认 summary 模式。

常用参数：

• mode: summary、search 或 export_file
• direction: consume、grant 或 any
• entry_type
• min_credits / max_credits
• start_date / end_date

summary 模式会优先请求服务端 summary=true 聚合摘要；若旧部署暂不支持，则回退到有上限的客户端聚合。

示例：

{ "mode": "search", "direction": "consume", "min_credits": 50 }

大量记录应使用 mode: "export_file"，MCP 服务器会写入 .qveris/exports/*.jsonl 并返回文件路径，而不是直接输出全量记录。

对于超大的工具调用输出，QVeris 可能返回：

• truncated_content
• full_content_file_url
• message

推荐使用模式#

对于大多数 Agent 任务，建议使用以下流程：

1. discover — 发现相关能力
2. inspect — 在需要时检查最佳候选
3. call — 调用所选能力

实践中：

• 任务简单且最佳候选明确时，可直接从发现跳到调用
• 任务风险较高或参数不清晰时，在调用前插入检查步骤
• 复用上一轮找到的 tool_id 时，建议先重新检查再复用

会话管理#

在单次用户会话中提供一致的 session_id 有助于：

• 保持用户会话连续性
• 随时间推移优化工具选择
• 更连贯的分析和追踪

若省略 session_id，MCP 服务器可能会在进程存活期间自动生成一个。

故障排查#

MCP 服务器未出现在客户端#

• 确认已安装 Node.js：node --version
• 确认客户端 MCP 配置为有效 JSON
• 确认 QVERIS_API_KEY 设置正确
• 修改配置后重启 MCP 客户端

工具可见但调用失败#

• 验证 API 密钥是否有效
• 验证所选 tool_id 来自此前的发现结果
• 重新运行 inspect 检查工具后再调用
• 检查 params_to_tool 是否为有效对象

Windows 特定问题#

如果在某些客户端中直接执行 npx 失败，用 cmd /c 包裹：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@qverisai/mcp"]
}

相关文档#

• 快速开始
• REST API 文档
• Agent 安装指南
• IDE / CLI 配置指南