QVeris MCP 服务器文档

简介

@qverisai/mcp 是面向 ChatGPT（Codex）、Cursor、Claude Desktop、Cherry Studio、GitHub Copilot、Cline、Roo Code、Kiro、Qoder、CodeBuddy、WorkBuddy 及其他编程智能体等 MCP 兼容客户端的官方 QVeris MCP 服务器。

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

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

进行 Provider 比较时，如果需要确认当前范围或完整契约，必须逐一 Inspect；Discover 摘要不等于确认。比较需要当前报价时，必须逐一 Probe。复用只能保留精确路由，不能保留业务参数或结果：参数必须来自当前请求；当前、最新、今天或其他时效性数据必须执行新的 Call。

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

MCP 与 REST API 对比

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

• 将 QVeris 集成到 ChatGPT（Codex）、Cursor、Claude Desktop、Cherry Studio、GitHub Copilot、Cline、Roo Code、Continue、Kiro、Junie、Augment、Zed、Google Antigravity、Qoder、CodeBuddy、WorkBuddy、OpenCode 或其他 MCP 客户端
• 希望智能体在对话中直接调用 QVeris 工具
• 希望客户端自动管理工具调用

适合使用 REST API 的场景：

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

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

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

环境要求

• MCP 兼容客户端
• 使用支持 OAuth 自动发现的托管 MCP 时，需要 QVeris 账户以完成浏览器登录
• 仅本地 stdio 配置或托管 MCP 的 API 密钥备用方案需要有效的 QVERIS_API_KEY
• 仅在使用本地 stdio 备用方案时需要 Node.js 18+

快速开始

托管 MCP（推荐）

只要客户端支持远程 Streamable HTTP，就应优先使用托管 MCP。它使用一个受管端点，无需维护本地软件包、Node.js 进程或服务器生命周期。

支持 MCP OAuth 自动发现的客户端可添加以下端点，按提示在浏览器中完成登录，无需创建或粘贴 API 密钥。示例使用 mcpServers 外层键；VS Code 应改用 servers。

{
  "mcpServers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp"
    }
  }
}

如果远程客户端不支持 OAuth 自动发现，请使用托管 MCP 详细说明中的 API 密钥备用方案。可前往托管 MCP 页面复制端点并查看各客户端的配置说明。只有当客户端不支持远程 Streamable HTTP 时，才使用下方本地 stdio 备用方案。

本地 stdio 备用方案

通过 npx 安装

npx -y @qverisai/mcp

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

QVERIS_API_KEY=your-api-key          # 必填
QVERIS_BASE_URL=https://qveris.ai/api/v1  # 可选：覆盖 API 地址

使用 QVeris CLI 配置

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

# 打印安全的 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 claude-desktop --write --include-key
qveris mcp configure --target opencode --write --include-key
qveris mcp configure --target openclaw --write --include-key

# Claude Code 使用 shell 命令，而不是 JSON 配置文件
qveris mcp configure --target claude-code

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

qveris mcp validate --target cursor

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

qveris mcp validate --target cursor --probe

Claude Desktop 配置示例

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

Cursor 配置示例

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

Cherry Studio 配置示例

在 Cherry Studio 中打开设置 → MCP 服务器，新增服务器后将以下内容填入对应配置字段：

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

保存服务器，在对话中启用它，并确认可见 discover、inspect、probe 和 call。

桌面端智能体客户端

除上文客户端外，以下桌面端智能体在支持远程 Streamable HTTP 时应优先使用托管 MCP，本地 stdio 仅作为备用方案：ChatGPT（Codex）、GitHub Copilot、Cline、Roo Code、Continue、Kiro、Junie、Augment、Zed、Google Antigravity、Qoder、CodeBuddy 和 WorkBuddy。

ChatGPT（Codex）可运行：

codex mcp add qveris --env QVERIS_API_KEY=your-api-key-here --env QVERIS_BASE_URL=https://qveris.ai/api/v1 -- npx -y @qverisai/mcp

对于 GitHub Copilot 以外的仅支持本地 stdio 的客户端，请在 MCP 设置中导入以下备用配置。Zed 在 Agent 面板中填写相同的名称、命令、参数和环境变量。

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

VS Code 中的 GitHub Copilot

GitHub Copilot 的 mcp.json 使用顶层 servers 对象，而不是 mcpServers。

托管 MCP 配置

QVeris MCP Registry 清单发布并被 VS Code MCP Gallery 收录后，从 Gallery 安装即可使用托管端点并自动发现 OAuth。按提示在浏览器中完成登录即可。Gallery 收录由 GitHub 决定；也可以直接在 .vscode/mcp.json 中配置该端点：

{
  "servers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp"
    }
  }
}

如需在 VS Code 中使用 API 密钥备用方案，请保留 servers 外层键，并通过密码输入保存密钥，避免将密钥提交到工作区：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qveris-api-key",
      "description": "QVeris API 密钥",
      "password": true
    }
  ],
  "servers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:qveris-api-key}"
      }
    }
  }
}

本地 stdio 备用方案

如果客户端环境不能使用远程 HTTP，请保留同一 servers 外层键，改用以下本地 stdio 条目：

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

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

• 智能体安装指南
• Codex 与 ChatGPT 桌面端配置
• Claude Code 配置
• OpenCode 配置
• IDE / CLI 配置

托管 MCP 详细说明

QVeris 提供远程 Streamable HTTP MCP 托管服务。对于支持它的客户端，这是首选 MCP 连接方式：无需安装本地软件包或运行后台进程。

https://mcp.qveris.ai/mcp

支持 MCP OAuth 自动发现的客户端可按快速开始中的说明添加服务地址，并在浏览器中完成登录，无需创建 API 密钥。

API 密钥备用方案

对于不支持 OAuth 自动发现的远程 MCP 客户端，可使用以下配置，在每次请求中发送 QVeris API 密钥：

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

如需在 Claude Code 中使用此 API 密钥备用方案，可通过命令行添加：

claude mcp add --transport http qveris https://mcp.qveris.ai/mcp --scope user --header "Authorization: Bearer YOUR_QVERIS_API_KEY"

API 密钥接入步骤：

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 不执行能力，也不消耗积分。

4. call

调用已发现的 QVeris 能力。

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

示例：

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

投影参数仅在显式指定时发送。付费 call / execute_tool 请求严格 single-submit：MCP server 不会重试 429/503，不会跟随 HTTP 重定向，也不会删除被拒绝的投影字段后再次提交。投影错误仍按错误返回；QVERIS_MAX_RETRIES 仅用于读和审计工具。

典型成功响应字段：

• 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

推荐使用模式

应根据任务适配度、数据质量/时效、费用、用户约束和调用开销，在已连接工具与 QVeris 之间选择。能力缺失、Provider 未知、需要跨 Provider 比较或 fallback，或用户明确指定 QVeris 时，QVeris 尤其适合；它不是所有任务的必经入口。

对于大多数 QVeris 任务，默认使用：

1. discover — 发现相关能力
2. Discover 已提供当前且完整的参数契约，并满足费用和用户约束时，直接 call

实践中：

• 仅在选择或构造合法请求依赖缺失/过期的契约详情，或需要比较候选时使用 inspect
• 仅在参数需要校验、预算决策需要当前报价、或明确要求预检时使用 probe；报价不等于锁价或授权
• Call 使用当前 Discover 结果的 search_id，并根据用户本次请求重新构造业务参数

会话管理

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

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

若省略 session_id，MCP 服务器会在进程存活期间自动生成一个。该行为不等于语义路由记忆或持久化 schema 缓存。如果 Host 自行实现复用，必须按账户、API 地址、授权上下文和会话隔离；保留原始 search_id；分别管理 schema、费用和可用性的失效；不得缓存凭据、敏感业务值或业务结果。Host 未实现这些能力时，应重新 Discover，不能假设存在记忆。

故障排查

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 文档
• 智能体安装指南
• IDE / CLI 配置指南