Archytan Lite MCP gate

archytan-mcp-gate

archytan-mcp-gate 位于 MCP 宿主（Claude Code、Claude Desktop、IDE Agent 或你自己的 Agent）与 MCP 工具服务之间。在任何工具调用到达服务之前，都必须先由 Archytan Lite gate 服务授权。MCP gate 会检查该决策的签名回执，并消耗一次性能力，然后才转发调用。策略不允许的调用会以可供 Agent 读取的工具错误形式返回，绝不会到达服务。

本仓库包含 MCP gate 的源代码，采用 Apache License 2.0 许可。它所连接的 Archytan Lite gate 服务是单独的产品，以签名容器镜像的形式分发；快速入门指南见 archytan-lite-community。

工作原理

宿主启动 MCP gate 来替代工具服务，而 MCP gate 会自行启动该服务，因此它成为 Agent 与工具之间唯一的通路。对于每个 tools/call，它会：

1. 请求 Archytan Lite gate 服务授权该调用所对应的操作，以及调用所指定的资源；
2. 验证服务返回的回执：其字段必须哈希为签名的意图哈希，签名必须来自服务的密钥，并且回执必须准确描述此次调用；
3. 兑换随 ALLOW 一同提供的一次性能力；
4. 将调用转发给工具服务。

如果任何步骤失败，该调用都会被拒绝，服务也不会收到该调用。Agent 始终不会持有任何可以绕过这些步骤的内容：MCP gate 持有 Agent 的凭据，而 Agent 只通过 MCP 通信。

要求

• 已启用能力的 Archytan Lite gate 服务（ARCHYTAN_LITE_CAPABILITIES=on）。测试使用 2.6.0 版本运行。
• 使用服务的 callergen 为 Agent 创建的、与凭据绑定的调用方。MCP gate 从不发送角色；Agent 的角色由其凭据决定。

安装

从本仓库的发布页下载适用于你平台的二进制文件。SHA256SUMS 包含每个二进制文件的校验和，并由构建它们的工作流使用 cosign 进行无密钥签名：

cosign verify-blob SHA256SUMS --bundle SHA256SUMS.cosign.bundle \
  --certificate-identity-regexp '^https://github.com/High-ArchyTech-Solutions/archytan-mcp-gate/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum -c SHA256SUMS --ignore-missing

也可以使用 Go 自行构建：

go install github.com/high-archytech-solutions/archytan-mcp-gate/v2/cmd/archytan-mcp-gate@latest

每个版本还会附带 archytan-mcp-gate.mcpb，这是一个供支持安装的宿主使用的 MCP bundle，并在 MCP Registry 中以 io.github.High-ArchyTech-Solutions/archytan-mcp-gate 列出。宿主需要四项内容：一个在 server 字段中指定工具服务的 mcp-gate.json（参见配置）、gate 服务的 URL、Agent 的令牌文件，以及服务的公钥。该 bundle 包含适用于 macOS 和 Linux（amd64 和 arm64）的构建版本，以及适用于 Windows（amd64）的构建版本；Windows on Arm 通过仿真运行该版本。它也包含在 SHA256SUMS 中。macOS 构建版本未经 Apple 公证，因此 macOS 可能会拒绝运行通过浏览器下载的版本，除非你先清除其隔离属性（xattr -d com.apple.quarantine <file>）。

配置

在 mcp-gate.json 中，为你希望 Agent 使用的每个工具映射一个策略操作。resource_id_arg 指定用于标识调用所作用资源的参数：

{
  "version": 1,
  "agent_uid": "agent-invoices",
  "tools": {
    "delete_invoice": { "action": "invoice.delete", "resource_type": "invoice", "resource_id_arg": "invoice_id" },
    "read_invoice":   { "action": "invoice.read",   "resource_type": "invoice", "resource_id_arg": "invoice_id" }
  }
}

然后让宿主连接 MCP gate，而不是工具服务。相同的 mcpServers 条目既适用于 Claude Desktop 的 claude_desktop_config.json，也适用于项目的 .mcp.json：

{
  "mcpServers": {
    "invoices": {
      "command": "archytan-mcp-gate",
      "args": ["--config", "/etc/archytan/mcp-gate.json", "--", "node", "/opt/invoice-server/index.js"],
      "env": {
        "ARCHYTAN_MCP_GATE_URL": "https://gate.internal:8421",
        "ARCHYTAN_MCP_GATE_CALLER_TOKEN_PATH": "/etc/archytan/agent-invoices.token",
        "ARCHYTAN_MCP_GATE_PUBLIC_KEY_HEX": "<the gate service's receipt-signing public key>"
      }
    }
  }
}

变量	含义
ARCHYTAN_MCP_GATE_URL	Archytan Lite gate 服务的基址。仅允许通过普通 http 连接回环地址，因为每个请求都携带 Agent 的凭据。
ARCHYTAN_MCP_GATE_CALLER_TOKEN_PATH	存放 Agent 调用方令牌的文件。
ARCHYTAN_MCP_GATE_PUBLIC_KEY_HEX	服务的 Ed25519 回执签名公钥，以十六进制表示。拒绝由任何其他密钥签名的回执。

也可以在 mcp-gate.json 中指定工具服务，而不必将其放在 -- 后面；这适用于只允许传入配置文件的宿主或捆绑包：

{
  "version": 1,
  "agent_uid": "agent-invoices",
  "server": { "command": "node", "args": ["/opt/invoice-server/index.js"] },
  "tools": {
    "read_invoice": { "action": "invoice.read", "resource_type": "invoice", "resource_id_arg": "invoice_id" }
  }
}

此时宿主的条目为 "args": ["--config", "/etc/archytan/mcp-gate.json"]。 命令会完全按照原样运行，并继承 MCP gate 的环境，与将命令放在 -- 后面的情况相同。只在一处指定服务：如果配置中有 server，且 -- 后也有命令，MCP gate 会拒绝启动，而不会自行选择其中一个。

mcp-gate.json 的读取校验与宿主消息一样严格。遇到未知字段、重复键或在任意嵌套层级仅大小写不同的键，以及无效的 UTF-8 文本或转义未配对代理项的文本时，MCP gate 都会在启动时停止，因此第二个 server 无法悄然决定运行哪个程序。

在线路上的行为

• 策略未涵盖的工具会被隐藏并拒绝。 tools/list 只向 Agent 显示已映射的工具，对任何其他名称的调用都会被拒绝， 不会到达服务或服务端。resources/*、prompts/*、 completion/*、tasks/* 和未知方法都会被拒绝，这些能力也会从 服务端公布的信息中移除。
• 宿主无法扩大服务端的范围。 MCP roots 允许宿主告知服务端应在哪些文件夹中 工作，而遵循这些信息的服务端（例如参考文件系统服务端）会用宿主提供的列表 替换其已配置的文件夹。在 MCP 闸门之后，服务端命令中指定的文件夹才是 它保留的文件夹：闸门会从宿主声明的信息中移除 roots，响应或拒绝服务端 对 roots 的请求，并丢弃 roots 变更通知。
• 两代协议均可通过。 MCP 闸门会转发 initialize 握手和 MCP 2026-07-28：server/discover、携带自身能力的请求、 用于 elicitation 和 sampling 的 input_required 往返，以及 subscriptions/listen，范围缩小为工具列表变更。每一轮因暂停并询问用户而 中止的调用都会单独授权和计费，因为服务端可能会对每次调用采取行动。
• 含义不明确的消息会被拒绝。 JSON 解析器对键重复或仅大小写不同的对象， 以及包含无效 UTF-8 或未配对代理项转义的文本，处理方式并不一致。此类 宿主消息会在授权或转发前被拒绝，因此 MCP 闸门和服务端始终对已判定的调用 达成一致。
• 拒绝会以工具结果的形式返回。 被拒绝的调用会返回一个设置了 isError 的 工具结果，并附上模型可以据此采取行动的直白说明。
• Agent 的追踪信息会传递到决策环节。 工具调用 params._meta 中的 W3C traceparent 会传递给服务，因此服务日志和第 2 版回执都包含 Agent 的 追踪 ID。追踪上下文绝不会改变决策。
• 调用按 Agent 发出的顺序执行，而 ping、通知和取消操作不会被它们阻塞。
• 每个步骤都会处理取消操作。 如果在能力兑换前取消，不会产生消耗或执行。 如果在转发后取消，取消操作会转发给服务端，因为只有服务端还能将其停止。
• 工具服务端不会比 MCP 闸门存活更久。 闸门退出时会关闭服务端的输入， 然后请求服务端停止，最后强制终止。在 Windows 上，服务端还会在作业对象中 运行，因此即使闸门本身被终止，服务端也会停止。在其他平台上，闸门被终止后， 服务端会在输入结束时退出，正如 MCP stdio 服务端的行为。

测试对象

宿主或服务端	通过 MCP 闸门
MCP TypeScript 客户端 SDK 2.3.1，initialize 握手	可用
同一 SDK，auto 协商	可用。可使用服务端对 MCP 2026-07-28 的支持；若服务端版本更早，则回退到 initialize
同一 SDK，固定为 2026-07-28	与 2026-07-28 服务端配合可用。与较旧服务端配合时会在连接阶段失败，符合 SDK 的预期
同一 SDK，重复使用缓存的发现结果	可用，且宿主的 roots 仍不会传递给服务端
MCP TypeScript 服务端 SDK 2.3.1（两代协议）	与上述所有客户端模式均可用
@modelcontextprotocol/server-filesystem 1.0.0（仅支持 initialize）	可用，且保留其已配置的文件夹

未涵盖的内容

• 它保护 Agent 通过它访问的内容。应将它设为唯一途径： 仅通过 MCP gate 的入口列出工具服务，并且只将服务自身的凭据提供给 该入口。拥有通用 shell 的 Agent 仍可手动启动服务，而 Claude Code 和 Claude Desktop 会为 Claude 提供自己的 shell 和文件 工具。对于它们，locked-workspace 会创建一个工作区， 让 MCP gate 的工具成为访问受保护路径的唯一方式。
• 策略决定 Agent 可对哪些资源执行哪些操作。 在获准的操作范围内，服务自身的参数和配置决定了它的访问范围。
• 它管理工具。资源、提示词和 completions 不经过这里。

安全

请按 SECURITY.md 中的说明私下报告漏洞。该文件还列出了 过去的安全公告，包括 GHSA-9ff5-c4g4-rx92， 该漏洞已在 2.5.1 和 2.6.0 中修复。

构建和测试

go test ./...

testing/mcpgate 中的测试会在脚本化主机、fixture 工具服务和真实的 Archytan Lite gate 服务之间运行真实二进制文件。默认情况下，它们使用 Docker 运行已发布并签名的服务镜像。若要改用本地二进制文件，请设置 ARCHYTAN_LITE_BIN 和 ARCHYTAN_LITE_KEYGEN_BIN。如果两者都未设置，测试会跳过并说明原因；CI 会设置 ARCHYTAN_MCP_GATE_E2E_REQUIRED=1，确保测试不能通过跳过来通过。

欢迎贡献；请参阅 CONTRIBUTING.md。

许可证

Apache License 2.0；请参阅 LICENSE 和 NOTICE。Archytan Lite gate 服务采用单独的许可证。