Vulnify

Vulnify MCP

在 AI Agent 读取、写入、删除、导出或发送数据之前，先向 Vulnify 发起询问。
finalDecision 是权威结果：ALLOW、REVIEW 或 BLOCK。

连接到 Claude  ·  文档  ·  MCP  ·  更新日志  ·  Node SDK

@vulnify/mcp 是 Vulnify 的 MCP 服务。Vulnify 是面向 AI Agent 的运行时授权层。Agent 会先发起询问。此进程会代理 https://api.vulnify.io。它不会存储事件或 API 密钥。

在 https://mcp.vulnify.io/mcp 使用 Vulnify 登录（OAuth 2.1）。该托管服务使用无状态 Streamable HTTP。本地使用方式是通过 VULNIFY_API_KEY 运行 npx -y @vulnify/mcp。

check_action 是一次试运行。它会跳过 PII 扫描，且不记录任何内容。decide_action 会记录真实决策。REVIEW 会等待人工处理。此服务无法批准或拒绝该请求。

应在你自己的进程内进行决策的应用代码，可使用 Node SDK（@vulnify/sdk）。此包不依赖该 SDK。SDK 会将某些传输故障转换为默认拒绝的决策。此服务会将这些故障作为 MCP 工具错误返回，因此模型不会将其误读为 ALLOW。

快速开始

权威信息请参阅 docs.vulnify.io/mcp。docs/clients.md 中也提供了相同的步骤。

使用 Vulnify 登录

连接到 https://mcp.vulnify.io/mcp。API 密钥和 OAuth 客户端字段留空。客户端会收到 HTTP 401，以及：

WWW-Authenticate: Bearer realm="https://mcp.vulnify.io/mcp", resource_metadata="https://mcp.vulnify.io/.well-known/oauth-protected-resource/mcp", scope="decisions:read decisions:write policies:read policies:test"

响应正文为 {"error":"unauthorized","message":"Sign in with Vulnify, or send an API key as Authorization: Bearer or X-Vulnify-Key:."}。受保护资源元数据会列出授权服务器 https://api.vulnify.io。

选择一个组织，并允许客户端请求的权限范围：

权限范围	工具
decisions:read	get_decision
decisions:write	decide_action
policies:read	list_policies
policies:test	check_action、test_policies

允许访问后，托管服务会提供这五个工具。plan_policy_changes 和 check_mcp_tool_call 不在该列表中。它们需要 API 密钥。缺少权限范围时会返回一条指出缺少哪个权限范围的工具错误。该错误不是 ALLOW。可在“设置”>“已连接的应用”中撤销连接：app.vulnify.io/settings/connected-apps。

Claude

Vulnify 已收录在 Claude 的连接器目录中：连接到 Claude。在列表中选择 Connect，然后使用 Vulnify 登录。操作指南：Claude 操作的人工审批。

若要改用 URL 添加，请打开 Settings > Connectors > Add custom connector。将 URL 设置为 https://mcp.vulnify.io/mcp。不要粘贴 API 密钥。Add Vulnify in Claude 会打开该对话框，并自动填入名称和 URL。随后 Claude 会启动 Sign in with Vulnify。

Cursor

在 Cursor 中安装会添加托管服务并启动登录。

在 .cursor/mcp.json 或 ~/.cursor/mcp.json 中使用同一服务时，只需填写 URL，无需添加请求头：

{
  "mcpServers": {
    "vulnify": {
      "url": "https://mcp.vulnify.io/mcp"
    }
  }
}

Grok

打开 grok.com/connectors，然后选择 New Connector > Custom。将名称设为 Vulnify。将 URL 设置为 https://mcp.vulnify.io/mcp。OAuth 字段留空。Grok 会启动 Sign in with Vulnify。

Claude Code

claude mcp add --transport http vulnify https://mcp.vulnify.io/mcp

随后 Claude Code 会登录。此命令中不要传入 API 密钥。

API 密钥或本地 npx

当你需要使用 plan_policy_changes 或 check_mcp_tool_call、客户端无法打开浏览器，或密钥设有 IP 白名单时，请使用 API 密钥。本地进程需要 Node.js 20 或更高版本，并会读取 VULNIFY_API_KEY。它不会打开 OAuth 授权页面。

npx -y @vulnify/mcp

VULNIFY_API_KEY=vln_live_... npx -y @vulnify/mcp

密钥格式为 vln_live_... 或 vln_test_...。TEST 密钥会存储沙盒事件。这些事件不会显示在主控制面板中。

在托管服务上，两种请求头仍然都可用。每个请求都要发送密钥：

Authorization: Bearer <key>
X-Vulnify-Key: <key>

API 密钥会话会列出全部七个工具。

Cursor，托管服务：

{
  "mcpServers": {
    "vulnify": {
      "url": "https://mcp.vulnify.io/mcp",
      "headers": {
        "Authorization": "Bearer vln_live_..."
      }
    }
  }
}

Cursor，本地：

{
  "mcpServers": {
    "vulnify": {
      "command": "npx",
      "args": ["-y", "@vulnify/mcp"],
      "env": {
        "VULNIFY_API_KEY": "vln_live_..."
      }
    }
  }
}

在托管服务上，可以用 X-Vulnify-Key 替代 Authorization。

Claude Code 使用 API 密钥：

claude mcp add --transport http vulnify https://mcp.vulnify.io/mcp --header "Authorization: Bearer vln_test_your_key"

优先使用环境变量，而不是将密钥写入 shell 历史记录。要登录，请使用不带请求头的 Claude Code 命令。

Claude Desktop 可以运行本地进程。在 macOS 上，文件为 ~/Library/Application Support/Claude/claude_desktop_config.json。在 Windows 上，文件为 %APPDATA%\Claude\claude_desktop_config.json。保存后重启应用。

{
  "mcpServers": {
    "vulnify": {
      "command": "npx",
      "args": ["-y", "@vulnify/mcp"],
      "env": {
        "VULNIFY_API_KEY": "vln_live_..."
      }
    }
  }
}

VS Code，.vscode/mcp.json，托管服务：

{
  "servers": {
    "vulnify": {
      "type": "http",
      "url": "https://mcp.vulnify.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:vulnify-api-key}"
      }
    }
  }
}

VS Code，本地：

{
  "servers": {
    "vulnify": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vulnify/mcp"],
      "env": {
        "VULNIFY_API_KEY": "${input:vulnify-api-key}"
      }
    }
  }
}

工作原理

finalDecision 字段是权威结果。工具错误不代表 ALLOW。

工具

每个工具都有标题，以及 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint。这些提示用于告知客户端如何呈现工具，不会改变工具的行为。

工具	API	是否记录？	readOnlyHint	备注
check_action	POST /v1/policies/test（一个案例）	否	true	跳过 PII 扫描，不记录任何内容。没有事件 ID。
decide_action	POST /v1/events	是	false	写入安全事件和审计条目。finalDecision 是权威结果。
get_decision	GET /v1/events/{id}	否	true	读取决策。可选的等待操作会轮询 REVIEW，直到结果变为 ALLOW 或 BLOCK（最长 30 秒）。
list_policies	GET /v1/policies	否	true	按名称排序的策略即代码列表。
test_policies	POST /v1/policies/test	否	true	最多 200 个案例。跳过 PII 扫描。不会保存所提交的 policies。
plan_policy_changes	POST /v1/policies/apply	否	true	dryRun 会被强制设为 true。需要组织范围的 LIVE 密钥。
check_mcp_tool_call	POST /v1/gateway/mcp	是	false	将工具名称映射为操作并记录决策。不会运行该工具。

所有工具的 destructiveHint 均为 false。所有工具的 openWorldHint 均为 false，因为每次调用都仅限于调用者自己的 Vulnify 组织。只读工具的 idempotentHint 为 true，decide_action 和 check_mcp_tool_call 的 idempotentHint 为 false。idempotencyKey 可确保重试已记录的决策时返回同一事件。

策略列表、测试和计划调用的限额为每个密钥每分钟 60 次请求。批量试运行请使用 test_policies。POST /v1/events 有独立的限额。OpenAPI 文本只会说明已超出限额。

安全性

此服务无法更改审核结果，也无法保存策略。

• 没有批准工具，也没有拒绝工具。由人工在 Vulnify 中处理 REVIEW。
• 没有应用工具。每次请求中，plan_policy_changes 都会以 dryRun: true 调用 POST /v1/policies/apply。工具输入没有 dryRun 字段。服务端最后设置 dryRun，因此调用者无法关闭试运行。工具会返回差异。
• POST /v1/gateway/http 不是工具。如果结果为 ALLOW，该 API 端点会转发 HTTP 调用。此服务不会转发。

plan_policy_changes 需要组织范围的 LIVE 密钥。TEST 密钥或绑定到 Agent 的密钥会收到 403。OAuth 会话不会列出 plan_policy_changes 或 check_mcp_tool_call。

OAuth 作用域

用户登录使用托管 HTTP 服务。本地 stdio 进程仍使用 API 密钥。托管服务会将工具映射到作用域：

工具	作用域	OAuth 路由
check_action	policies:test	POST /v1/mcp/policies/test
test_policies	policies:test	POST /v1/mcp/policies/test
decide_action	decisions:write	POST /v1/mcp/events
get_decision	decisions:read	GET /v1/mcp/events/{id}
list_policies	policies:read	GET /v1/mcp/policies
plan_policy_changes	仅限 API 密钥和 stdio	从 OAuth tools/list 中省略
check_mcp_tool_call	仅限 API 密钥和 stdio	从 OAuth tools/list 中省略

缺少所需作用域的令牌会收到指出该作用域的工具错误。该错误不代表 ALLOW。活动 introspection 结果最多会复用 60 秒，且绝不会超过 exp。

与 MCP 网关的区别

https://mcp.vulnify.io/mcp（以及本地 stdio 进程）是 MCP 客户端连接的服务。随后，客户端会调用上述工具。

check_mcp_tool_call 则不同。它会向 api.vulnify.io 上的 POST /v1/gateway/mcp 发送一次工具调用，记录决策，然后停止。它不会执行该工具，而且客户端连接到此服务也不会调用该网关。

IP 允许列表

API 密钥可以列出允许的源 IP。使用该密钥通过 https://mcp.vulnify.io/mcp 发起的调用，其来源是托管服务的出口地址，而不是运行 Cursor 或 VS Code 的机器。只包含办公室或笔记本电脑地址的允许列表会拒绝托管服务。请在地址位于列表中的主机上使用 npx -y @vulnify/mcp。使用 Vulnify 登录不会发送该 API 密钥。

产品

此截图来自演示工作区。Agent 为 SupportBot。

Vulnify 应用中的审计导出为 JSON 或 CSV 下载文件，其中包含 SHA-256 校验和。SIEM 导出为 JSON 或 CEF 行。

配置

变量	位置	必需	用途
VULNIFY_API_KEY	stdio 进程	是	API 密钥（vln_live_... 或 vln_test_...）。HTTP 不会回退到此变量。
VULNIFY_BASE_URL	两者	否	API 基础 URL。默认值为 https://api.vulnify.io。
OAUTH_INTROSPECTION_SECRET	HTTP	用户登录时需要	用于 POST /oauth/introspect 的 Bearer 密钥。该密钥保留在服务端。API 密钥无需此密钥即可使用。
OPENAI_APPS_CHALLENGE	HTTP	否	设置后，GET /.well-known/openai-apps-challenge 会以 text/plain 返回此值。未设置时，该路径返回 404。
PORT	HTTP	否	监听端口。默认值为 8080。
HOST	HTTP	否	绑定地址。默认值为 0.0.0.0。

当记录的决策应计入某个 Agent 时，请使用绑定到 Agent 的 LIVE 密钥。plan_policy_changes 需要组织级 LIVE 密钥。

VULNIFY_TEST_API_KEY 仅用于 npm run test:live。服务不会读取该变量。

HTTP 服务

npx -y @vulnify/mcp --http

容器以非 root 用户运行 HTTP 服务：

docker build -t vulnify-mcp .
docker run --rm -p 8080:8080 -e PORT=8080 vulnify-mcp

启动容器无需 API 密钥。请在每个请求中发送密钥。

curl -sS localhost:8080/health
curl -sS -o /dev/null -w '%{http_code}\n' -X POST localhost:8080/mcp \
  -H 'content-type: application/json' -d '{}'

健康检查会输出 JSON。未携带密钥的 POST 请求会返回 401。

GET /.well-known/mcp/server-card.json 无需密钥。它会列出服务注册的工具（名称、描述和输入架构），说明你可以通过 OAuth 登录或在标头中发送 Vulnify API 密钥，并提供文档和此代码库的链接。

curl -sS https://mcp.vulnify.io/.well-known/mcp/server-card.json

错误

工具调用失败会作为 MCP 工具错误（isError）返回。不会包含 API 密钥。

状态码	含义
401	API 密钥或访问令牌缺失、无效、已撤销或已过期。
403	密钥绑定到其他 Agent、调用方 IP 不在允许列表中、访问令牌缺少所需作用域，或调用 plan_policy_changes 时未使用组织级 LIVE 密钥。
413	JSON 请求体超过 API 的 200 KB 限制。
429	密钥受到速率限制。策略调用每分钟限 60 次。使用相同的 idempotencyKey 重试已记录的决策。

安全

请通过 [email protected] 报告漏洞。披露政策见 vulnify.io/disclosure。请参阅 SECURITY.md。

不会记录密钥。请求日志包含方法、路径和状态。用于敏感数据扫描的 content 会转发到 API，不会写入此服务的日志。API 会在内存中扫描该文本，不会存储。

此软件包不会运行 shell，也不会注册钩子。请勿将密钥放在工具参数或已提交的配置文件中。

此进程使用的网络端点：

• 每次调用工具时，以及检查 API 密钥时调用 GET /v1/policies，都会使用 https://api.vulnify.io（或 VULNIFY_BASE_URL）。API 密钥会作为 Authorization: Bearer 发送到 /v1/*。用户访问令牌会作为 Authorization: Bearer 发送到 /v1/mcp/*。
• 在同一源上调用 POST /oauth/introspect，并将 OAUTH_INTROSPECTION_SECRET 设为 Authorization: Bearer，以验证 vln_oat_... 令牌。该密钥不会发送给客户端，也不会被记录。
• https://mcp.vulnify.io/mcp 是托管的 HTTP 传输端点。服务进程不会调用该 URL。

开发

npm install
npm test
npm run lint
npm run build

设置 VULNIFY_TEST_API_KEY 时，npm run test:live 会在 https://api.vulnify.io 上调用 list_policies；未设置时则会跳过。它不会记录事件。

发布流程见 RELEASING.md。

许可证

MIT。版权所有 2026 Vulnify。