mcp-gateway

Vengtoo MCP 网关

面向 AI Agent 和 MCP 工具调用的授权网关。

开源。即插即用。适用于任何 MCP 客户端。

为什么要用

连接到 MCP 服务的 AI Agent 可以调用其有权访问的任何工具：读取数据库、删除文件、执行任意 SQL。Vengtoo MCP Gateway 在 Agent 与这些工具之间设立策略执行点，确保每次调用都经过授权后才执行。

功能

• 位于 MCP 客户端（Claude Code、Cursor、VS Code、GitHub Copilot）与任意 MCP 服务之间
• 拦截每次工具调用，并在转发前检查授权
• 两种模式：云端（Vengtoo Cloud API）和本地（Vengtoo Agent + .rego 策略文件）
• 完整记录每次工具调用的审计日志：主体、工具名称、参数和决策均以结构化 JSON 格式记录：

{"ts":"2026-05-25T10:03:11.482Z","level":"info","msg":"mcp_tool_call","subject":"agent:ai-assistant","tool":"database__query","allowed":true,"latency_ms":0.8}

快速开始

1. 安装并启动 Vengtoo Agent。该 Agent 在本地运行并评估授权策略；无需云账户。

go install github.com/vengtoo/agent/cmd/agent@latest
vengtoo-agent --policy ./policy.rego

创建 policy.rego，定义 Agent 可以执行的操作：

package vengtoo.mcp

default allow := false

# Allow read-only tools
allow if { input.resource.name == "database__query" }
allow if { input.resource.name == "database__list_tables" }

# Allow writes, but block destructive SQL
allow if {
    input.resource.name == "database__execute"
    not contains(lower(input.resource.attributes.sql), "drop")
    not contains(lower(input.resource.attributes.sql), "delete from")
}

更多示例（包括 Kubernetes 命名空间保护），请参见 demo/policies/。

2. 创建 gateway.config.json：

{
  "vengtoo": {
    "agentUrl": "http://127.0.0.1:8181"
  },
  "subject": "agent:ai-assistant",
  "servers": {
    "database": {
      "command": "node",
      "args": ["./my-database-mcp-server.js"]
    }
  }
}

3. 添加到 MCP 客户端（例如 Claude Code）：

claude mcp add --transport stdio vengtoo-gateway -- \
  npx vengtoo-mcp-gateway --config /path/to/gateway.config.json

配置

配置架构

字段	类型	必填	描述
vengtoo.agentUrl	string	*	本地 Vengtoo Agent 的 URL（本地模式）
vengtoo.cloudUrl	string	*	Vengtoo Cloud API 的 URL（云端模式）
vengtoo.apiKey	string		来自 Vengtoo Cloud 的 API 密钥（或设置 VENGTOO_API_KEY 环境变量）
vengtoo.timeoutMs	number		授权请求超时时间（默认值：5000）
subject	string	yes	发起工具调用的 Agent 身份
subjectType	string		主体类型（默认值："agent"）
resourceType	string		授权检查的资源类型（默认值："mcp_tool"）
servers	object	yes	要代理的下游 MCP 服务映射
transport	string		调用方传输方式："stdio"（默认）或 "http"，参见传输方式
http	object		HTTP 传输设置（当 transport 为 "http" 时使用）

* 提供 agentUrl（本地模式）或 cloudUrl（云端模式）之一。

servers 中的每个条目包含：

字段	类型	必填	描述
command	string	yes	用于启动 MCP 服务的命令
args	string[]		命令参数
env	object		附加环境变量

模式

云端模式

连接到 Vengtoo Cloud，使用托管策略：

{
  "vengtoo": {
    "cloudUrl": "https://api.vengtoo.com/access/v1/evaluation",
    "apiKey": "vgt_..."
  },
  "subject": "agent:prod-assistant",
  "servers": {
    "database": {
      "command": "node",
      "args": ["./db-server.js"]
    }
  }
}

本地模式

在本地运行 Vengtoo Agent，并使用 .rego 策略文件进行离线、自包含的授权：

# Start the agent with your policy
vengtoo-agent --policy ./policy.rego

{
  "vengtoo": {
    "agentUrl": "http://127.0.0.1:8181"
  },
  "subject": "agent:dev-assistant",
  "servers": {
    "database": {
      "command": "node",
      "args": ["./db-server.js"]
    }
  }
}

传输方式

网关通过以下两种传输方式之一，向调用方提供其（受策略保护的）工具。

stdio（默认）

作为本地子进程运行，通过 stdin/stdout 使用 MCP 通信：适用于单个桌面 Agent（Claude Desktop、Cursor、Claude Code）。不会暴露网络接口。

HTTP（远程）

在某个 URL 上运行 Streamable HTTP MCP 服务，这样远程 Agent（或多个并发 Agent）就可以共享一个受管控的网关。使用 --http（或在配置中设置 "transport": "http"）启用：

vengtoo-mcp-gateway --config gateway.config.json --http --port 8808

{
  "vengtoo": { "cloudUrl": "https://api.vengtoo.com/access/v1/evaluation", "apiKey": "vgt_..." },
  "subject": "agent:prod-assistant",
  "transport": "http",
  "http": {
    "port": 8808,
    "host": "0.0.0.0",
    "path": "/mcp",
    "authTokens": ["<caller-token>"],
    "allowedHosts": ["gateway.example.com"]
  },
  "servers": { "database": { "command": "node", "args": ["./db-server.js"] } }
}

HTTP 配置（http.*）：

字段	类型	默认值	描述
port	number	8808	要监听的 TCP 端口
host	string	127.0.0.1	要绑定的接口；0.0.0.0 接受远程连接
path	string	/mcp	MCP 端点的 URL 路径
callers	object[]	-	每个调用方的身份：{ "token": "...", "subject": "agent:claude" }；每个 bearer token 都授权为其自身的 subject
authTokens	string[]	-	匿名 bearer token；授予访问权限，并以全局 subject 身份运行
allowedHosts	string[]	-	启用 DNS 重绑定保护；拒绝 Host 不在列表中的请求
allowedOrigins	string[]	-	启用 DNS 重绑定保护；拒绝 Origin 不在列表中的请求

每个调用方的身份。 为每个 Agent 分配独立的 token 和 subject，这样你的策略（和审计记录）就能通过一个共享网关识别每个调用方的真实身份：

"http": {
  "port": 8808,
  "callers": [
    { "token": "<claude-token>", "subject": "agent:claude" },
    { "token": "<cursor-token>", "subject": "agent:cursor" }
  ]
}

也可以通过 VENGTOO_GATEWAY_HTTP_CALLERS="<token>=agent:claude,<token>=agent:cursor" 设置。 会话会绑定到创建会话的 token：其他调用方若提供了他人的会话 ID，会收到 401，因此不同身份无法跨会话访问。authTokens 中列出的 token（或完全未配置调用方时）会以配置中的全局 subject 身份运行。

安全性： 如果未配置调用方身份验证（callers 或 authTokens），网关拒绝绑定到非回环接口。请配置 token，或设置 VENGTOO_GATEWAY_ALLOW_UNAUTHENTICATED=true，以明确允许开放端点。始终会提供无需身份验证的 GET /healthz 存活探测。

⚠️ 安全：Vengtoo 信任此网关声明的 subject。 上述 callers token→subject 映射（由此网关自身的配置管理）是正确的做法；这与信任客户端提供的标头不同。切勿改为从调用客户端发送的标头或字段中推导 subject；否则任何调用方都能冒充任意 subject，并在你的租户内继承其权限。如果在此网关前部署了另一个反向代理，请确保无法诱使该代理转发调用方任意选择的 bearer token 或 subject。

CLI 标志

标志	描述
--config <path>	网关配置文件的路径（默认值：./gateway.config.json）
--http	使用 HTTP 而非 stdio 提供服务
--port <n>	HTTP 监听端口（默认值：8808；要求配置兼容 --http）
--host <h>	HTTP 绑定接口（默认值：127.0.0.1）
--path <p>	HTTP 端点路径（默认值：/mcp）
--list-tools	列出已配置的下游服务中的所有工具，然后退出
--generate-policy [path]	为已配置的工具生成初始 .rego 策略文件（默认值：policy.rego）

环境变量覆盖项：VENGTOO_API_KEY、VENGTOO_AGENT_URL、VENGTOO_SUBJECT、 VENGTOO_GATEWAY_TRANSPORT（http）、VENGTOO_GATEWAY_PORT / PORT、VENGTOO_GATEWAY_HOST、 VENGTOO_GATEWAY_PATH、VENGTOO_GATEWAY_HTTP_TOKENS（逗号分隔）、VENGTOO_GATEWAY_ALLOW_UNAUTHENTICATED。

MCP 客户端设置

网关以 stdio MCP 服务的形式运行。将 MCP 客户端指向该网关，而不是直接指向下游服务。

Claude Code

claude mcp add --transport stdio vengtoo-gateway -- \
  npx vengtoo-mcp-gateway --config /path/to/gateway.config.json

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "vengtoo-gateway": {
      "command": "npx",
      "args": ["vengtoo-mcp-gateway", "--config", "/path/to/gateway.config.json"]
    }
  }
}

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "vengtoo-gateway": {
      "command": "npx",
      "args": ["vengtoo-mcp-gateway", "--config", "/path/to/gateway.config.json"]
    }
  }
}

VS Code / GitHub Copilot

添加到 .vscode/mcp.json：

{
  "servers": {
    "vengtoo-gateway": {
      "type": "stdio",
      "command": "npx",
      "args": ["vengtoo-mcp-gateway", "--config", "/path/to/gateway.config.json"]
    }
  }
}

请参阅 demo/，了解包含示例策略的完整端到端示例。

路线图

请参阅 ROADMAP.md，了解计划中的功能：针对每位调用者的 OAuth、下游服务弹性、动态工具列表、指标、远程下游服务等。

反馈

• GitHub Issues：错误报告和功能请求
• 文档：指南和 API 参考

许可证

Apache-2.0，详见 LICENSE。