VerifyAX

VerifyAX MCP 服务

VerifyAX 官方 Model Context Protocol（MCP）服务：由云托管的桥接服务，让你的 AI 工具能够安全、实时地访问 VerifyAX 平台，以注册 Agent、生成场景、运行模拟并读取评估结果。

快速开始 · 支持的工具 · 安全性 · 部署自己的服务 · 报告问题

---

VerifyAX 官方 MCP 服务是你的 MCP 兼容 AI 客户端与 VerifyAX Agent 评估平台之间的桥接服务。完成配置后，你可以用自然语言注册 Agent、生成场景、运行模拟并读取评估结果，无需编写 API 脚本。

使用 VerifyAX MCP 服务，你可以：

• 注册并测试 Agent（A2A 或 API），在评估前确认连接正常。
• 根据技能标签生成场景，并通过一次工具调用等待生成完成。
• 运行评估，读取分数、对话记录和额度使用情况，无需手动轮询。

它与 verifyax-api skill 相辅相成（并不取代它）：skill 适用于编写代码的开发者；MCP 服务适用于对话式工作流。

目录

• 支持的客户端
• 支持的工具
• 开始之前
• 安装 MCP 服务
• 工作原理
• 工作流示例
• 提示与技巧
• 数据与安全
• 故障排查
• 支持与反馈
• 免责声明
• 开发者指南
• 许可证

---

支持的客户端

VerifyAX MCP Server 可与支持 Streamable HTTP 或 stdio 的 MCP 兼容客户端配合使用：

客户端	设置参考
OpenAI ChatGPT	连接器 / MCP 指南
Claude（Claude.ai、Code、Desktop）	Claude MCP 文档
Cursor	Cursor MCP 文档
Visual Studio Code（GitHub Copilot）	VS Code MCP 文档
GitHub Copilot CLI	关于 Copilot CLI
Google Gemini CLI	Gemini CLI MCP 文档
Amazon Quick Suite	MCP 集成指南

任何可通过 mcp-remote 连接的客户端，也可以 使用托管端点 https://mcp.verifyax.com/mcp。

重要

Claude.ai 自定义连接器：选择 无需登录，并使用 Authorization 标头。 此服务 使用 VerifyAX API 密钥进行身份验证，而非 OAuth，因此请在 设置 → 连接器 → 添加自定义 连接器 中：

1. URL：https://mcp.verifyax.com/mcp
2. 身份验证：无需登录 — 对话框中将其描述为“适用于使用 API 密钥而非 OAuth 的服务”。不要选中 立即登录；此服务不提供 OAuth 元数据，因此 OAuth 尝试会失败。
3. 在 请求标头 下，添加值为 Bearer sk-ver-api-... 的 Authorization。

随后会显示全部 17 个工具，Claude.ai 允许你为每个工具设置审批方式（它将工具分为 12 个只读工具和 5 个写入/删除工具 — 建议将写入/删除工具组设为需要审批，因为 generate_scenario 和 evaluate_agent 会消耗额度）。

要求服务版本为 0.3.5 或更高版本：更早的版本会区分大小写地匹配 Bearer 方案，并拒绝将其规范化的客户端，但最终只会显示“无法连接到服务。” X-VerifyAX-API-Key 标头可用于此服务，但 Claude.ai 的标头字段不接受该名称，因此请使用 Authorization。

提示

有关 Claude 的分步设置说明，以及它与 VerifyAX skill 和 SDK 的比较，请参阅 docs/using-verifyax-with-claude.md。

---

支持的工具

17 个工具对应不同的用户意图。阻塞式工具会在内部轮询，并仅在任务完成后返回（通常需要 30 秒至 5 分钟）。

区域	工具	阻塞
Agents	register_agent · list_agents · delete_agent	—
场景	list_compatible_tags · recommend_scenario_tags · search_scenario_tags · generate_scenario · list_scenarios · get_scenario · delete_scenario	是（generate_scenario）
评估	evaluate_agent · list_recent_runs · get_run_details · get_evaluation_report · get_run_output	是（evaluate_agent）
用量	get_usage_summary · preview_run_cost	—

说明

如需了解工具说明（Claude 据此选择工具）及其设计理由，请参阅 docs/tool-descriptions.md。软件包级参考文档： packages/mcp-server/README.md。

---

开始之前

具体要求取决于连接方式。

远程 HTTP（托管于 mcp.verifyax.com）

• 一个 VerifyAX API 密钥（在控制台的 Settings → API Keys 中获取）
• 支持 Streamable HTTP 的 MCP 客户端，或用于运行 mcp-remote 代理的 Node.js 18+

本地 stdio（通过 npx 运行 verifyax-mcp-server）

• Node.js ≥ 20
• 客户端配置中提供一个 VerifyAX API 密钥（VERIFYAX_API_KEY）

npm 软件包提供两个可执行文件（verifyax-mcp-server 和 verifyax-mcp-server-http）；使用 npx 时，请明确指定 stdio 可执行文件的名称。

---

安装 MCP 服务

远程 HTTP（推荐）

托管端点：

https://mcp.verifyax.com/mcp

在初始化请求中发送 VerifyAX API 密钥。托管服务不会存储密钥；每个客户端会话都需自带密钥。

Cursor（原生 URL — v0.48+）：

{
  "mcpServers": {
    "verifyax": {
      "url": "https://mcp.verifyax.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-ver-api-..."
      }
    }
  }
}

不要添加 transport 字段；Cursor 会根据 URL 自动识别 Streamable HTTP。你也可以使用 "X-VerifyAX-API-Key": "sk-ver-api-..." 替代 Authorization。

Claude Desktop / 不支持原生 HTTP 的客户端（mcp-remote）：

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "verifyax": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.verifyax.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${VERIFYAX_AUTH}"
      ],
      "env": {
        "VERIFYAX_AUTH": "Bearer sk-ver-api-..."
      }
    }
  }
}

由于此服务仅支持 Streamable HTTP（不支持旧版 SSE），请使用 --transport http-only。你也可以通过 --header 传入 X-VerifyAX-API-Key: sk-ver-api-...，替代 Authorization。

更改配置后，请重启 MCP 客户端。

本地 stdio

Claude Code：

claude mcp add verifyax --env VERIFYAX_API_KEY=sk-ver-api-... -- npx -y -p @verifyax/mcp-server verifyax-mcp-server

说明

这里有意不固定版本，因此此命令始终会获取当前服务。 只有 verifyax-mcp 插件固定了确切 版本（@verifyax/mcp-server@<plugin version>），因为市场插件承诺：只有在插件版本升级时，用户才会 获得新的服务构建版本。手动设置没有这样的 承诺，因此默认跟踪最新版本是正确的做法。如果需要可复现性，可以自行固定版本：-p @verifyax/[email protected]。

-p … verifyax-mcp-server 会明确指定二进制文件名称，因为该软件包提供两个 二进制文件（verifyax-mcp-server、verifyax-mcp-server-http），且都与软件包名称不匹配，因此 直接运行 npx -y @verifyax/mcp-server 会失败并显示“could not determine executable to run”。

Claude Desktop：

{
  "mcpServers": {
    "verifyax": {
      "command": "npx",
      "args": ["-y", "-p", "@verifyax/mcp-server", "verifyax-mcp-server"],
      "env": { "VERIFYAX_API_KEY": "sk-ver-api-..." }
    }
  }
}

更改配置后，重启客户端，然后用自然语言描述你的需求。

---

工作原理

架构与通信

1. MCP 客户端连接到 https://mcp.verifyax.com/mcp（远程 HTTP），或启动 npx -p @verifyax/mcp-server verifyax-mcp-server（本地 stdio）。
2. 客户端在初始化时发送你的 VerifyAX API 密钥（HTTP 使用 Authorization: Bearer … 或 X-VerifyAX-API-Key；stdio 使用 VERIFYAX_API_KEY 环境变量）。
3. 服务代表你调用 VerifyAX API。阻塞式工具（generate_scenario、 evaluate_agent）会在内部轮询任务状态，并且只在任务完成后返回。

权限与计费

• 操作范围限定为与你的 API 密钥关联的工作区。
• 使用量和额度计入你的 VerifyAX 工作区，而非 MCP 服务运营方。
• 托管服务不会发送遥测数据，也不会在会话之间保存 API 密钥。

自托管

在你自己的基础设施上运行相同的 HTTP 服务（例如 Google Cloud Run）。请参阅 deploy/gcp/README.md。

---

示例工作流

连接后，用自然语言描述任务，客户端会选择相应的工具。

Agent 设置

• 注册："在 https://my-agent.example.com 注册我的 A2A Agent，并确认它可以访问。"
• 列出："我的工作区中注册了哪些 Agent？"

场景编写

• 发现标签："列出我可用于面试场景的技能标签。"
• 生成："生成一个带有 empathy 和 coordination 标签的 info_exchange 场景。"

评估

• 运行评估："根据场景 Y 评估 Agent X，并总结评分。"
• 查看历史记录："显示我最近一次模拟运行的详细信息。"

使用量与费用

• 预览："针对我的 Agent 运行此场景需要多少额度？"
• 汇总："我最近 5 次模拟运行的费用是多少？"

说明

阻塞式工具可能需要 30s–5min。请勿重复调用，应等待结果。

---

提示与技巧

将默认设置添加到 AGENTS.md

将以下内容添加到项目根目录中的 AGENTS.md 文件，以减少发现调用和不合适的标签组合 （格式请参阅 AGENTS.md 约定）：

## VerifyAX MCP

When connected to verifyax:

- **MUST** call `recommend_scenario_tags`, `search_scenario_tags`, or `list_compatible_tags` before `generate_scenario`
- **MUST NOT** combine QnA tags with other tags (QnA must be the sole tag)
- **MUST** use `preview_run_cost` when the user asks about credits before `evaluate_agent`
- Blocking tools (`generate_scenario`, `evaluate_agent`) take 30s–5min — do not retry manually

在代码工作流中使用 skill

对于脚本、CI 或自定义多步骤逻辑，请使用 verifyax-api skill 或 @verifyax/sdk，而不是 MCP 工具。

---

数据与安全

• 所有发往托管端点的流量均使用 HTTPS (TLS)。
• 使用 API 密钥进行身份验证；每项操作都会遵循你的 VerifyAX 工作区权限。
• 托管服务不会存储 API 密钥，每个会话都会提供自己的密钥。
• MCP 服务不会发送遥测数据；它只与 VerifyAX API 通信。
• 具有破坏性的工具（delete_agent、delete_scenario）会永久删除资源，调用前请与用户确认。

API 密钥可在 VerifyAX 控制台中管理（Settings → API Keys）。 可在那里撤销密钥，立即切断访问权限。

---

故障排除

• “VERIFYAX_API_KEY 未设置” — 密钥未传到服务端。请检查 env 配置块 （stdio），或 Authorization / X-VerifyAX-API-Key 请求头（HTTP）。
• 身份验证失败 — 密钥无效、已撤销或来自错误的环境。请在控制台中生成新的密钥。
• 工具调用未显示 — MCP 客户端会在启动时加载工具；添加服务后，请重启客户端（或启动新会话）。
• Cursor 中的 HTTP 连接失败 — 尝试在 mcp-remote 中使用 --transport http-only，或确认 URL 以 /mcp 结尾。
• 需要日志？ 将 VERIFYAX_MCP_LOG_LEVEL=debug 设为 debug。日志为 stderr 上的结构化 JSON；stdout 专用于 MCP 协议。

---

支持与反馈

本项目由 Conscium 的 VerifyAX 团队维护。

• 错误报告和功能请求：提交 issue
• 开发参考：CONTRIBUTING.md（维护者和分支）
• 不接受外部拉取请求 — issue 是联系我们的最佳方式

---

免责声明

MCP 客户端可以使用你的 VerifyAX API 密钥和工作区额度注册 Agent、生成场景、运行评估和删除资源。请遵循最小权限原则（使用限定范围的密钥、仅授予最少的工作区访问权限），在确认高影响操作前先进行检查，并撤销不再需要的密钥。

Model Context Protocol 将 AI Agent 连接到外部工具，从而创建强大的工作流，但也带来结构性风险。大模型可能容易受到提示词注入及相关攻击的影响。请仅使用可信的 MCP 客户端和服务，并检查每个 Agent 可以访问哪些工具。

---

面向开发者

此仓库是一个包含两个软件包的 pnpm monorepo：

软件包	说明
@verifyax/sdk	用于 VerifyAX REST API 的类型化 TypeScript 客户端
@verifyax/mcp-server	基于 SDK 构建的 MCP 服务（17 个工具）

需要 Node ≥ 20 和 pnpm 10。

pnpm install      # install workspace dependencies
pnpm build        # build all packages (topological order)
pnpm test         # run unit tests
pnpm lint         # lint
pnpm format       # format with prettier

依赖网络的测试套件：pnpm test:integration（实时 API，需要 VERIFYAX_TEST_KEY）和 pnpm test:conformance（通过 stdio 启动已构建的 MCP 服务）。

• MCP Inspector：docs/debugging-mcp-inspector.md
• 执行计划：docs/PLAN.md
• 架构决策：CLAUDE.md
• Cloud Run 部署：deploy/gcp/README.md

---

许可证

Apache-2.0。请参阅 LICENSE。