@qverisai/mcp 是面向 Cursor 及其他编程 Agent 等 MCP 兼容客户端的官方 QVeris MCP 服务器。
它通过少量 MCP 工具为 Agent 提供 QVeris 访问能力：
discover — 用自然语言发现能力inspect — 获取工具详情（参数、成功率、示例）call — 执行工具并传入参数usage_history — 上下文安全的调用审计摘要 / 精确查询 / 文件导出credits_ledger — 上下文安全的最终 credits 账本摘要 / 精确查询 / 文件导出换言之，MCP 服务器是本仓库其他文档所描述的 QVeris 核心协议的 Agent 侧传输层。
适合使用 MCP 服务器的场景：
适合使用 REST API 的场景：
两种方式均映射到同一套 QVeris 协议：
| 协议操作 | MCP 工具 | REST API |
|---|---|---|
| 发现 | discover | POST /search |
| 检查 | inspect | POST /tools/by-ids |
| 调用 | call | POST /tools/execute |
| 调用审计 | usage_history | GET /auth/usage/history/v2 |
| Credits 账本 | credits_ledger | GET /auth/credits/ledger |
**注意：**旧工具名称（
search_tools、get_tools_by_ids、execute_tool）仍作为弃用别名支持。
18+QVERIS_API_KEYnpx 安装npx -y @qverisai/mcp
MCP 服务器从以下环境变量读取配置：
QVERIS_API_KEY=your-api-key # 必填
QVERIS_BASE_URL=https://... # 可选：覆盖 API 地址
可以用 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 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、call 可见：
qveris mcp validate --target cursor --probe
{
"mcpServers": {
"qveris": {
"command": "npx",
"args": ["-y", "@qverisai/mcp"],
"env": {
"QVERIS_API_KEY": "your-api-key-here"
}
}
}
}
各环境的详细配置指南，请参考：
Hosted MCP 已列入规划，但当前接入路径不依赖托管端点。在正式发布托管端点前，请使用上文的 stdio server：npx -y @qverisai/mcp。
托管 MCP 端点可用后，接入流程会是：
qveris mcp validate --target <client> 或使用客户端内置工具列表，确认 discover、inspect、call 可见。discover使用自然语言发现能力。
这是**发现（Discover）**操作，免费使用。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | 是 | 用自然语言描述所需能力 |
limit | number | 否 | 最大返回数量（1-100，默认 20） |
session_id | string | 否 | 用于追踪的会话标识符 |
示例：
{
"query": "天气预报 API",
"limit": 10
}
典型响应字段：
search_idtotalresults[]results[].tool_idresults[].paramsresults[].examplesresults[].statsinspect在复用或调用之前，检查一个或多个已知 tool_id 的详情。
这是**检查（Inspect）**操作。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
tool_ids | array | 是 | 要查询的工具 ID 数组 |
search_id | string | 否 | 返回该工具的发现操作的搜索 ID |
session_id | string | 否 | 用于追踪的会话标识符 |
示例：
{
"tool_ids": ["openweathermap.weather.execute.v1"],
"search_id": "YOUR_SEARCH_ID"
}
以下情况建议使用 inspect：
响应结构与 /search 一致，包含所请求工具的参数、示例和统计数据。
call调用已发现的 QVeris 能力。
调用响应可能包含 compact 的 billing 预结算账单。最终是否扣费请通过 usage_history 或 credits_ledger 查询。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
tool_id | string | 是 | 来自发现结果的工具 ID |
search_id | string | 是 | 发现该工具的搜索 ID |
params_to_tool | object | 是 | 传递给工具的参数字典 |
session_id | string | 否 | 用于追踪的会话标识符 |
max_response_size | number | 否 | 最大响应字节数（默认 20480） |
示例：
{
"tool_id": "openweathermap.weather.execute.v1",
"search_id": "YOUR_SEARCH_ID",
"params_to_tool": {"city": "北京", "units": "metric"}
}
典型成功响应字段：
execution_idtool_idsuccessresult.dataelapsed_time_ms 或 execution_timebilling / pre_settlement_bill（如可用）usage_history当用户询问某次调用是否成功、失败或扣费时使用。默认 summary 模式，不会把全量历史塞进上下文。
常用参数：
mode: summary、search 或 export_fileexecution_id / search_idcharge_outcome: charged、included、failed_not_charged、failed_charged_reviewmin_credits / max_creditsstart_date / end_datesummary 模式会优先请求服务端 summary=true 聚合摘要；若旧部署暂不支持，则回退到有上限的客户端聚合。
示例：
{ "mode": "search", "execution_id": "EXECUTION_ID" }
credits_ledger当用户询问余额为何变化时使用。默认 summary 模式。
常用参数：
mode: summary、search 或 export_filedirection: consume、grant 或 anyentry_typemin_credits / max_creditsstart_date / end_datesummary 模式会优先请求服务端 summary=true 聚合摘要；若旧部署暂不支持，则回退到有上限的客户端聚合。
示例：
{ "mode": "search", "direction": "consume", "min_credits": 50 }
大量记录应使用 mode: "export_file"，MCP 服务器会写入 .qveris/exports/*.jsonl 并返回文件路径，而不是直接输出全量记录。
对于超大的工具调用输出，QVeris 可能返回：
truncated_contentfull_content_file_urlmessage对于大多数 Agent 任务，建议使用以下流程：
discover — 发现相关能力inspect — 在需要时检查最佳候选call — 调用所选能力实践中：
tool_id 时，建议先重新检查再复用在单次用户会话中提供一致的 session_id 有助于：
若省略 session_id，MCP 服务器可能会在进程存活期间自动生成一个。
node --versionQVERIS_API_KEY 设置正确tool_id 来自此前的发现结果inspect 检查工具后再调用params_to_tool 是否为有效对象如果在某些客户端中直接执行 npx 失败，用 cmd /c 包裹：
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@qverisai/mcp"]
}