Cordon for MCP

Cordon for MCP

MCP 工具调用的安全网关

网站 • 文章

快速入门 • 为什么选择 Cordon • 工作原理 • 配置 • 路线图 • 参与贡献

---

每家公司都想部署 AI Agent，却没有公司愿意把数据库的钥匙交给 Agent。

Cordon 消除了信任鸿沟。

来自 Agent Toolbelt 的维护者——25+ 个 MCP 工具，每周 npm 下载量约 1,600 次。

---

演示

https://github.com/user-attachments/assets/153d978f-6303-443a-b49b-b4ec7ebf0452

---

问题

Model Context Protocol (MCP) 让 AI Agent 能够轻松使用强大的工具，例如数据库、文件系统、API 和云基础设施。

但 MCP 没有内置的安全模型。没有审计日志，没有审批工作流，也没有速率限制。如今，AI Agent 要么完全关闭，要么拥有完整管理员权限，两者之间别无选择。

这是阻碍 AI Agent 进入生产环境的最大障碍。

解决方案

Cordon 是一个安全网关，位于大模型与 MCP 服务之间。

它兼具防火墙、审计器和远程控制的作用，让你完全掌握 AI Agent 可以和不可以执行的操作。

┌─────────┐      ┌──────────┐      ┌──────────────┐
│  LLM /  │ ──▶  │  Cordon  │ ──▶  │  MCP Server  │
│  Agent  │ ◀──  │ Gateway  │ ◀──  │  (database,  │
└─────────┘      └──────────┘      │   fs, APIs)  │
                   │               └──────────────┘
                   ├── Policy Engine
                   ├── Audit Logger
                   └── Approval Workflows

无需更改基础设施，无需重写。只需一个配置文件。

---

快速入门

步骤 1 — 初始化

在项目目录中运行（该目录下应存在 claude_desktop_config.json）：

npx @getcordon/cli init

这会读取你现有的 Claude Desktop MCP 配置，生成 cordon.config.ts，并修改 Claude Desktop，使所有工具调用都经由 Cordon 转发。

步骤 2 — 启动

npx @getcordon/cli start

Cordon 启动后会连接到你的 MCP 服务，并开始拦截工具调用。重启 Claude Desktop 后，每次工具调用都会经由网关转发。

手动设置

如果你希望手动配置，可以全局安装并创建配置文件：

npm install -g @getcordon/cli
cordon init

cordon init 会生成一个 cordon.config.ts：

import { defineConfig } from '@getcordon/policy';

export default defineConfig({
  servers: [
    {
      name: 'database',
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@my-org/db-mcp-server'],
      policy: 'read-only',        // Block all write operations
    },
    {
      name: 'github',
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-github'],
      policy: 'approve-writes',   // Reads pass; writes require approval
      tools: {
        delete_branch: 'block',   // Never, regardless of approval
      },
    },
  ],

  audit: {
    enabled: true,
    output: 'stdout',             // or 'file'
  },

  approvals: {
    channel: 'terminal',
    timeoutMs: 60_000,            // auto-deny after 60s; the request is retained
                                  // and replayable if approved late
  },
});

---

为什么选择 Cordon

不使用 Cordon	使用 Cordon
Agent 可不受限制地访问工具	按工具设置细粒度策略
无法了解 Agent 执行过什么操作	为每次调用生成结构化审计记录
“Agent 刚才是不是删了张表？”	在终端实时审批
读操作和写操作一视同仁	approve-writes 自动放行读操作
合规团队拒绝使用 AI	审计日志可随时导出

---

功能

策略引擎

可以按工具、按服务或全局定义规则。工具级策略会覆盖服务级策略。

// Server-level default
policy: 'approve-writes',

// Per-tool overrides
tools: {
  query:        'allow',    // reads: pass through
  execute:      'approve',  // writes: pause for human approval
  drop_table:   'block',    // catastrophic: always reject
  list_tables:  'log-only', // audit but don't interrupt
},

人工审核

当工具调用需要审核时，Cordon 会暂停 Agent，并直接在终端中提示你：

╔══════════════════════════════════════╗
║  ⚠  APPROVAL REQUIRED               ║
╚══════════════════════════════════════╝
  Server : database
  Tool   : execute_sql
  Args   :
  {
    "query": "DELETE FROM sessions WHERE expires_at < NOW()"
  }

  [A]pprove  [D]eny
  >

Agent 会等待，由你决定。

更喜欢使用 Slack？在控制面板中点击 Add to Slack，只需连接一次工作区，无需创建或粘贴机器人令牌，然后设置 approvals: { channel: 'slack' }。遇到标记的调用时，系统会向你的频道发送一张“批准 / 拒绝”卡片，并暂停等待人工点击；审核者的姓名也会写入审计记录。请参阅 Slack 审核设置。

如果迟迟无人回复。 调用会被拒绝，Agent 会继续运行，但请求不会丢失。Cordon 会保留待审核请求及其完整上下文，控制面板也会将其列在 发生的更改 → 超时的审核 下。如果有人在请求过期后批准了卡片，这一迟到的决定仍会被记录，调用也可以重新运行：

cordon replay <callId>

重放会执行该工具，并将结果连同原因 replay of late-approved call 记录到同一审计流中。它恢复的是工具调用，而非 Agent 的会话——发起请求的 Agent 早已结束运行。只有在超时后获批的调用才能重放，因为重放已经运行过的调用会导致重复执行。

审计日志

每次工具调用都会记录为结构化 JSON——包括请求、策略决策、响应和耗时。你可以将其通过管道发送到标准输出，也可以写入文件，供合规团队使用。

{"event":"tool_call_received","callId":"...","serverName":"database","toolName":"execute_sql","timestamp":1773434469641}
{"event":"approval_requested","callId":"...","serverName":"database","toolName":"execute_sql","timestamp":1773434469641}
{"event":"tool_call_approved","callId":"...","serverName":"database","toolName":"execute_sql","timestamp":1773434471203}
{"event":"tool_call_completed","callId":"...","durationMs":34,"isError":false,"timestamp":1773434471237}

只读模式

只需一个策略设置，即可阻止服务器上的所有写操作。无需猜测哪些操作属于写入——Cordon 会根据工具名称进行检测。

policy: 'read-only'  // any tool starting with write/create/update/delete/drop/execute/... is blocked

隐藏工具

对于模型绝不应看到的工具，不只是拒绝调用，而是会将其完全从 tools/list 响应中过滤掉。这能封堵一种提示注入攻击面：如果模型根本不知道某个工具存在，就无法被诱骗去调用它。

{
  name: 'database',
  policy: 'approve-writes',
  tools: {
    drop_table:      'block',   // call attempts are rejected
    internal_admin:  'hidden',  // not advertised to the client at all
  },
}

SQL 感知策略

对于数据库 MCP 服务，如果一个工具可以接受任意 SQL（Postgres、SQLite、BigQuery 等），仅凭工具名称进行启发式判断并不够精确——名称 query 并不能告诉你 Agent 即将执行的是 SELECT 还是 DROP TABLE。Cordon 内置了两种策略，会解析 SQL 本身，并根据语句类型作出判断。

tools: {
  // Allow SELECTs (including CTEs that wrap a SELECT). Block everything else.
  query: 'sql-read-only',

  // Reads pass; writes (INSERT/UPDATE/DELETE/DROP/ALTER/...) pause for human approval.
  execute: 'sql-approve-writes',

  // When the tool takes SQL in a different arg name:
  run: { action: 'sql-read-only', sqlArg: 'statement' },
}

默认情况下，两种策略都使用 PostgreSQL 方言（其他方言将在后续支持），并采用失败即关闭的方式：无法解析的 SQL 会被拦截，而非放行。AST 解析器可以正确将提示注入模式（如 SELECT 1; DROP TABLE users;）和包裹在块注释中的关键字识别为写操作。

封闭世界工具目录

声明上游服务应公开的确切工具范围。当上游在未来版本中添加新工具时，Cordon 会自动拦截该工具，直到你明确将其加入允许范围。

{
  name: 'postgres',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-postgres', process.env.POSTGRES_URL!],
  policy: 'read-only',
  knownTools: ['query', 'list_tables', 'describe_table'],  // your approved surface
  onUnknownTool: 'block',                                  // default when knownTools is set
}

如果下一个 Postgres MCP 版本新增了 truncate_table，Cordon 会拦截它并向标准错误输出警告，无需更新策略。将 knownTools 保持为未定义，即可维持向后兼容的开放世界行为。

每个 Agent 的策略 + 调用图约束

每个工具的策略可以拦截危险的单次调用。调用图规则可以拦截危险的调用序列——也就是以非预期顺序使用允许的工具。典型示例：Agent 使用 read_data（允许）读取敏感数据，然后用 write_file（也允许）将其写入磁盘。单独来看，每次调用都没问题。问题在于调用序列。

Cordon 的调用图规则会在每个工具的策略之上应用，且是累加的——它们只能提高严重级别，绝不会降低。

export default defineConfig({
  // Optional identity for this Cordon process. Surfaced in audit logs.
  agentId: 'et-acquisition-agent',

  servers: [{
    name: 'demo-db',
    transport: 'stdio',
    command: 'npx',
    args: ['-y', '@my-org/db-mcp'],
    policy: 'approve-writes',
  }],

  callGraph: [
    // Reading data and then writing to disk is the exfil shape — block it,
    // even though write_file would only require approval on its own.
    { from: 'read_data', to: 'write_file', action: 'block',
      reason: 'No file writes after database reads.' },

    // Glob matching: any send_* tool right after a database read needs human approval.
    { from: 'read_data', to: 'send_*', action: 'approve' },

    // `*` matches anything: after a privileged read, every next call must be approved.
    { from: 'sensitive_read', to: '*', action: 'approve' },
  ],
});

规则如何与每个工具的策略结合（严重级别累加）：

严重级别顺序：allow < approve < block。

只有当调用图规则的动作严重级别高于每个工具的决策时，该规则才会生效。这意味着：

• action: 'block' 规则会覆盖 allow 的每个工具策略 ✓
• action: 'approve' 规则会覆盖 allow，但不会降低 block ✓
• action: 'allow' 规则绝不会削弱更严格的基准策略——它不会产生任何效果
• 多条规则同时匹配时，严重级别最高的规则生效（配置顺序无关紧要）

单向棘轮——只能收紧，绝不放宽。

审计日志增加链上下文。 每个 tool_call_received 事件现在都会携带 previousTool（上次成功执行的工具）。规则触发时，被阻止或需要审批的事件还会包含 callGraphRule: { from, to }：

{"event":"tool_call_received","toolName":"write_file","previousTool":"read_data","..."}
{"event":"tool_call_blocked","toolName":"write_file","reason":"No file writes after database reads.","previousTool":"read_data","callGraphRule":{"from":"read_data","to":"write_file"},"..."}

v1 的适用范围（如果你要在生产环境中发布每个 Agent 的策略，请阅读此部分）：

在 stdio 模式（以及当前的单租户 HTTP 模式）下，一个 Cordon 进程服务于一个 Agent 身份——因此，配置中的 agentId 标识的是此部署，而不是每次调用的运行时身份。多租户 HTTP 网关（一个 Cordon 实例托管多个具有不同策略的 Agent）仍在排期中——届时 agentId 将支持从 HTTP 标头获取，无需重写配置。

lastTool 仅在上游正常返回时才会更新。被阻止、拒绝以及传输失败的调用不会推进调用链。v1 无法防范探测行为——攻击者尝试 fs:delete（被阻止）后再调用 http:post 时，http:post 会根据探测之前的工具进行评估，而不是根据探测本身。我们有意采用这种设计：记录每次被阻止的尝试，会过于频繁地将那些被阻止一次后继续执行的合法流程误判为异常。等有了真实的对抗性滥用数据后再重新评估。

---

工作原理

Cordon 以单一的聚合型 MCP 代理运行。Claude Desktop 不再直接连接到你的 MCP 服务，而是连接到 Cordon。随后由 Cordon 在内部管理你的服务。

Before:  Claude ──▶ MCP Server A (full access)
         Claude ──▶ MCP Server B (full access)

After:   Claude ──▶ Cordon ──▶ MCP Server A (governed)
                          ──▶ MCP Server B (governed)

你的大模型客户端和 MCP 服务完全不需要更改。cordon init 会处理配置修改。

HTTP 传输（n8n 和其他通过 HTTP 通信的 MCP 客户端）

对于通过 HTTP 使用 MCP 通信的客户端——n8n 的 MCP Client Tool 节点、无法生成子进程的托管 Agent，以及其他需要网络端点的客户端——Cordon 可以作为 HTTP 监听器运行，而不是使用 stdio。

export CORDON_GATEWAY_TOKEN=your-secret-token
npx @getcordon/cli start --http --port 7777
# [cordon] HTTP gateway listening on http://127.0.0.1:7777/mcp

也可以在配置中设置：

import { defineConfig } from '@getcordon/policy';

export default defineConfig({
  servers: [ /* your upstream MCP servers */ ],
  gateway: {
    transport: 'http',
    authToken: process.env.CORDON_GATEWAY_TOKEN!,
    port: 7777,
    host: '127.0.0.1',  // localhost-only by default; set to '0.0.0.0' to expose externally
  },
});

客户端通过 Authorization: Bearer <your-token> 请求头连接到 http://your-host:7777/mcp。此传输实现了 MCP Streamable HTTP 规范——一个端点同时提供 SSE 响应流和直接 JSON 响应，并通过请求头中的会话 ID 处理会话复用。

所有策略执行、审计日志记录和审批工作流在不同传输方式下的工作方式都相同——变化的只有线路协议。

从 n8n 连接。 将 MCP Client Tool 节点指向你的 Cordon URL，并将 Bearer 令牌设为凭据。已弃用的仅支持 SSE 的端点形式（旧版 n8n 使用旧版 MCP SSE 规范）不受支持——Cordon 仅提供当前的 Streamable HTTP 传输，n8n 正在迁移到该传输。

单租户。 当前的 HTTP 传输是单租户的：所有会话共用相同的上游 MCP 服务、策略配置和身份验证令牌。多租户托管网关（从请求头读取每次调用的 agentId，并使用每租户策略）已列入路线图。

---

配置

策略操作

策略	行为
allow	立即放行
block	拒绝——Agent 会收到错误
approve	暂停，等待在终端中进行人工审批
approve-writes	读取操作直接放行；写入操作需要审批
read-only	阻止所有写入操作
log-only	放行，但在审计日志中标记
hidden	从 tools/list 中过滤掉——模型不会看到它
sql-read-only	解析 SQL 参数，允许 SELECT/WITH-SELECT，阻止其他所有内容（无法解析时默认拒绝）
sql-approve-writes	解析 SQL 参数，允许读取操作，暂停写入操作以等待人工审批，阻止无法解析的内容

策略可在服务级别设置（适用于所有工具的默认策略），也可针对单个工具设置（覆盖服务默认策略）：

{
  name: 'my-server',
  policy: 'approve-writes',   // server default
  tools: {
    safe_read:   'allow',     // override: always allow
    nuke_db:     'block',     // override: always block
  },
}

审批渠道

渠道	状态
terminal	可用——在终端中进行交互式提示
slack	可用——一键添加到 Slack（OAuth）、由服务器发布的 Block Kit 卡片、经 HMAC 验证的交互，以及记录中捕获的审批人信息
web	将在 v0.3 推出
webhook	将在 v0.3 推出

审计输出

输出	状态
stdout	可用
file	可用——将 JSON 行写入本地文件
hosted	可用——将事件发送到 Cordon 仪表板
otlp	将在 v0.3 推出

---

软件包

软件包	描述
@getcordon/cli	CLI——npx @getcordon/cli start
@getcordon/policy	TypeScript 配置 SDK——defineConfig() 和所有类型
@getcordon/core	核心代理引擎——策略评估器、审计日志记录器、审批管理器

---

路线图

• 带聚合器模型的 MCP 代理（多个服务，一个网关）
• 策略引擎 — 允许、阻止、审批、审批写入、只读、仅记录、隐藏
• 封闭世界工具目录 — 使用 knownTools + onUnknownTool 控制上游接口，面向未来
• SQL 感知策略 — sql-read-only / sql-approve-writes 在调用时解析 SQL 参数（PostgreSQL 方言）
• 终端审批通道，提供兼容 TTY 的提示
• Slack 审批通道 — Block Kit 消息，并轮询响应
• 将结构化 JSON 审计日志输出到 stdout、文件或托管式仪表板
• cordon init — 自动读取 Claude Desktop 配置并进行修改
• 速率限制 — 滑动窗口，全局 / 按服务 / 按工具
• 托管式仪表板 — 审计日志历史记录、CSV/JSON 导出、GitHub OAuth，个人用户免费
• 按 Agent 设置策略 + 调用图约束 — 根据调用序列阻止操作，并采用累加式严重级别
• HTTP/Streamable HTTP 传输 — 面向 n8n 和支持 HTTP 的 MCP 客户端的单租户网关
• 漂移检测 — 在仪表板中查看“本周 Agent 的行为发生了哪些变化”
• 策略建议 — 分析审计历史记录，并提出调用图规则和关卡建议
• 持久化审批 — 超时的审批会被保留、显示，并可通过 cordon replay 重新执行
• 多租户 HTTP 网关 — 多个 Agent 共用一个 Cordon 实例，并通过请求头中的 agentId 区分每次调用
• OpenTelemetry 导出
• 团队账户和集中式治理

---

示例

请参阅 examples/security-showcase，了解 Cordon 拦截试图删除生产数据库表的 Agent 的实际演示。

cd examples/security-showcase
npm install
npm run demo

---

使用场景

企业 — 对所有 AI Agent 部署进行集中式治理。策略即代码、结构化日志，并为符合 SOC2 要求的审计跟踪提供清晰路径。

创业团队 — 放心部署 Agent。每次工具调用都会记录，写入操作需要审批，合规团队也能查看审计记录。

独立开发者 — 保护本地 Claude/Cursor 环境。准确了解 Agent 调用了什么工具，并在危险操作进入生产环境之前将其阻止。

---

协作工具

• Agent Toolbelt — 一套类型化的现成 MCP 工具（网页搜索、获取内容、文件系统等）。将它接入 Claude Desktop，再通过 Cordon 路由这些工具调用，以强制执行策略并记录审计日志。Agent Toolbelt 为 Agent 提供能力；Cordon 则确保它们在使用之前先征求许可。

• Build & Ship MCP Tools — 配套课程，循序渐进地讲解如何从头到尾构建自己的 MCP 服务。共 7 个模块、33 节课；模块 0 免费，模块 6 讲解如何使用 Cordon 保护 MCP 服务。

---

参与贡献

Cordon 是开源项目，欢迎贡献。

git clone https://github.com/marras0914/cordon.git
cd cordon
npm install
npm run build
npm run dev

---

许可证

MIT — 详情请参阅 LICENSE。

---

别再盲目信任，开始实施治理。
⭐ 在 GitHub 上点亮 Star

隐私 · 条款 · 支持 · 合作伙伴
© 2026 Elephant Tortoise LLC