Vantagate Mcp Server

VantaGate MCP 服务与 OpenAPI 集成

为 AI Agent 提供人在环路中的授权。 VantaGate 会拦截高风险操作，通过 Slack 或 Email 将其转交给人工审批者，并返回经过加密签名的决策——让你的 Agent 在具备完整审计记录的情况下继续运行或停止。

---

什么是 VantaGate？

AI Agent 越来越有能力执行会对现实世界产生重大影响的操作：向数千名用户发送电子邮件、删除数据库记录、转移资金、部署到生产环境。VantaGate 是信任层，确保人类始终掌控全局。

Agent hits risky action
        ↓
POST /v1/checkpoint  ──→  Human receives Slack/Email notification
        ↓                          ↓
   id and status              Human reviews payload & decides
        ↓                          ↓
Poll GET /v1/checkpoint/{id}  ←──  Decision recorded + payload purged
        ↓
   APPROVED → Resume workflow
   REJECTED → Halt + report reason

核心保障

• API 响应时间 < 100ms——你的 Agent 无需等待 I/O，不会被阻塞
• 静态数据采用 AES-256 载荷加密——决策作出后，载荷将被永久销毁
• 零保留轮询——GET /checkpoint/{id} 永远不会返回原始载荷
• 加密审计记录——每项决策都经过 HMAC-SHA256 签名
• 无状态协议——无需 SDK；任何语言都可以使用纯 HTTP

---

此软件包

此软件包提供了两种集成方式，可将任意 AI Agent 连接到 VantaGate：

方式	文件	适用场景
OpenAPI 3.0 规范	vanta-gate-openapi.json	无代码工具、OpenAI GPTs、Alice、n8n、Zapier
MCP 服务	src/index.ts / dist/index.js	Claude Desktop、Cursor、Cline，以及任何兼容 MCP 的 Agent

---

前置条件

• Node.js >= 20
• VantaGate 账户：https://vanta-gate.com
• VantaGate API 密钥（Dashboard → Projects → New Project）

---

快速开始

选项 A：在 Claude Desktop 中使用 MCP 服务

最快的方式。无需手动设置。

第 1 步： 从 https://vanta-gate.com/dashboard/projects 获取你的 API 密钥

第 2 步： 将 VantaGate 添加到 Claude Desktop 配置中。

打开你的 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vantagate": {
      "command": "npx",
      "args": ["-y", "@vantagate/mcp-server"],
      "env": {
        "VANTA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

第 3 步： 重启 Claude Desktop。工具 create_vantagate_checkpoint 和 check_vantagate_status 将出现在 Claude 的工具列表中。

第 4 步： 让 Claude 执行需要审批的操作：

“删除暂存数据库中 created_at < 2024-01-01 的所有记录”

Claude 会自动暂停、创建检查点，并提示你查看电子邮件或 Slack 中的审批通知。

---

选项 B：使用 OpenAPI 规范（无代码 / 低代码）

将 vanta-gate-openapi.json 直接导入你选择的工具。

OpenAI GPTs / 自定义操作

1. 在 https://platform.openai.com/gpts 打开 GPT 编辑器
2. 点击 “Add actions” → “Import from URL”，或粘贴 JSON
3. 设置 Authentication → API Key → Header：X-API-KEY
4. 输入你的 VantaGate API 密钥

现在，GPT 在调用高风险工具之前会暂停并请求人工审批。

Alice（AI Agent 平台）

1. 前往 Integrations → Import OpenAPI
2. 上传或粘贴 vanta-gate-openapi.json
3. 在凭据存储中将标头 X-API-KEY 设置为你的 VantaGate API 密钥
4. 将 create_vantagate_checkpoint 映射到 Agent 的“高风险操作前”触发器

n8n / Zapier

1. 添加 HTTP Request 节点
2. 导入 OpenAPI 规范以自动填充端点
3. 在凭据配置中设置 X-API-KEY 标头

LangChain / LlamaIndex

from langchain.tools import OpenAPITool

vanta_tool = OpenAPITool.from_openapi_spec(
    spec_path="./vanta-gate-openapi.json",
    headers={"X-API-KEY": os.environ["VANTA_API_KEY"]}
)
agent = initialize_agent([vanta_tool], llm, agent=AgentType.OPENAI_FUNCTIONS)

---

可用的 MCP 工具

create_vantagate_checkpoint

暂停 Agent 工作流，并提交人工审批请求。

Claude 使用时机： 执行任何高风险操作之前，例如财务操作、删除数据、生产环境部署和批量通信。

参数	类型	必填	描述
title	string	✅	显示给审批人的简短标题。最多 200 个字符。
payload	object	✅	用于决策的完整 JSON 上下文。决策后加密并清除。
description	string	❌	标题下方的补充上下文。最多 1000 个字符。
options	string[]	❌	决策选项。第一个选项表示批准操作。默认值：["Approve", "Reject"]。最少 2 个，最多 5 个。
timeout	string	❌	自动过期时长：30m、4h、2d。默认值：24h。
notify_email	string	❌	用于接收魔法链接通知的电子邮件地址。
slack_webhook_url	string	❌	Slack webhook URL（Pro/Scale 方案）。前往 Dashboard → Add to Slack 获取。
callback_url	string	❌	用于接收签名决策 webhook 的 HTTPS 端点。

返回： checkpoint_id 和提供给 Agent 的分步说明。

check_vantagate_status

轮询待处理检查点的决策状态。

参数	类型	必填	描述
checkpoint_id	string	✅	来自 create_vantagate_checkpoint 的 ID。

返回： status（PENDING / APPROVED / REJECTED / RESOLVED / EXPIRED）、selected_option、reject_reason 和完整审计记录。

---

API 参考摘要

基础 URL： https://api.vanta-gate.com/v1
身份验证： X-API-KEY 标头

方法	端点	描述
POST	/checkpoint	创建检查点并暂停 Agent
GET	/checkpoint/{id}	轮询人工决策
GET	/checkpoint/secure/{token}	决策界面（内部使用 — 魔法链接）
POST	/checkpoint/secure/{token}/decide	提交决策（内部使用 — 决策界面）

检查点状态生命周期

PENDING → APPROVED   (human chose first/positive option)
        → REJECTED   (human rejected with optional reason)
        → RESOLVED   (human chose non-primary option)
        → EXPIRED    (timeout elapsed, no decision)

错误代码

HTTP	代码	描述
400	Invalid_Webhook_URL	slack_webhook_url 必须以 https://hooks.slack.com/ 开头
400	Invalid_Callback_URL	callback_url 格式不正确或指向私有 IP
400	Invalid_Decision	决策值不在检查点的选项数组中
400	Validation_Error	请求正文中的字段验证失败
401	Unauthorized	API 密钥缺失、无效或已轮换
402	Upgrade_Required	此功能需要 Pro 或 Scale 方案
403	Forbidden	API 密钥与检查点所属项目不匹配
404	Not_Found	检查点 ID 或令牌不存在
409	Already_Decided	此检查点的决策已记录
410	Checkpoint_Expired	已超过超时时间
429	Rate_Limited	请求过多 — 请稍后重试

所有错误都采用以下封装格式：

{
  "statusCode": 400,
  "error": "Machine_Readable_Code",
  "message": "Human-readable description."
}

---

订阅级别

功能	Free	Pro（$49/月）	Scale（$199/月）
每月检查点数	50	2,500	25,000
电子邮件通知	✅	✅	✅
Slack 通知	❌	✅	✅
Webhook 回调	✅	✅	✅
最长超时时间	24h	7 天	30 天
日志保留时间	7 天	90 天	365 天

超时值会自动限制为你所用方案允许的最大值。Free 方案的 timeout: "7d" 请求会被限制为 24h。

---

Webhook

人工做出决策后，VantaGate 会向你的 callback_url 发送经过签名的 HTTPS POST 请求（最多重试 5 次，并采用指数退避）。

请求标头：

Content-Type: application/json
X-Vanta-Signature: sha256=<HMAC-SHA256 of body>
User-Agent: VantaGate-Webhook/1.0

签名验证（Node.js）：

const crypto = require('crypto')

function verifyVantaSignature(rawBody, signature, projectSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', projectSecret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

app.post('/webhook/vanta', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-vanta-signature']
  if (!verifyVantaSignature(req.body, sig, process.env.VANTA_PROJECT_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' })
  }
  const event = JSON.parse(req.body)
  if (event.status === 'APPROVED') {
    // ✅ Resume agent workflow
  } else if (event.status === 'REJECTED') {
    // ❌ Halt - check event.reject_reason
  }
  res.json({ received: true })
})

你的 Webhook 签名密钥（VANTA_PROJECT_SECRET）与 API 密钥不同。可在 Dashboard → Project Settings 中找到。

---

从源代码构建

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run the server directly
VANTA_API_KEY=YOUR_API_KEY_HERE npm start

---

高级：其他客户端的 MCP 配置

Cursor / Cline / Windsurf

{
  "mcpServers": {
    "vantagate": {
      "command": "npx",
      "args": ["-y", "@vantagate/mcp-server"],
      "env": {
        "VANTA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

使用本地构建（开发）

{
  "mcpServers": {
    "vantagate": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "VANTA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

---

安全

• 你的 X-API-KEY 会在服务端进行哈希处理——VantaGate 从不存储明文密钥。
• 你的 slack_webhook_url 会随每个请求发送，并在决策后原子性清除。零保留。
• 所有载荷数据都以 AES-256 加密后静态存储，并在人工决策后销毁。无法还原。
• callback_url 会针对私有 IP 范围进行验证（防止 SSRF）。
• 所有 Webhook 投递都使用 HMAC-SHA256 签名。请务必验证签名。

---

许可证

MIT——参见 LICENSE

---

链接

• 控制面板： https://vanta-gate.com/dashboard
• 完整 API 文档： https://vanta-gate.com/dashboard/docs
• 隐私政策： https://vanta-gate.com/legal/privacy-policy
• 服务条款： https://vanta-gate.com/legal/terms-of-service