15 · MCP、工具访问与密钥投影

MCP EndpointTool GatewayProfile / PolicyApprovalSecret Projection

一句话结论： Paperclip 在 MCP 图中扮演两个角色：它自身可作为控制面 MCP Server，也可作为 Agent 访问上游 MCP 的治理 Gateway；后者通过 Connection→Catalog→Profile→Policy→Approval→Audit 管线，把工具可见性、调用风险和密钥投影连成一条执行前防线。

1. 两种 MCP 角色

flowchart TB
  subgraph Endpoint["Paperclip as MCP Endpoint"]
    CLIENT["Claude / IDE / external client"] --> PCMCP["Paperclip MCP Server"]
    PCMCP --> CONTROL["Issue / Agent / control-plane APIs"]
  end

  subgraph Gateway["Paperclip as MCP Gateway"]
    AGENT["Paperclip-managed Agent"] --> GW["Tool Gateway\nprofile + policy + approval + audit"]
    GW --> UP["GitHub / Linear / SaaS / local MCP"]
  end

Endpoint 管“外部客户端调用 Paperclip”；Gateway 管“Paperclip Agent 调用外部工具”。它们的工具目录、token 和风险模型不同。

2. Gateway 的五个核心对象

Application

逻辑应用，如 GitHub、Linear、Notion。一个 Application 可有多个 Connection。

Connection

一个具体 endpoint/transport/auth 实例：

• remote MCP/HTTP；
• REST API；
• local stdio；
• OAuth/API key/none；
• workspace/user grant；
• health/lifecycle/catalog refresh。

Catalog Entry

从 Connection 发现的一个 tool，保存 name、description、input schema、hash、risk、status。

Profile

决定 Agent 能看到哪些 tool。通过 binding 绑定 Company、Project、Agent、Routine 或 Issue。

Policy

决定 这一次具体调用能否执行：allow/block/require approval/rate limit/trust rule。

一句话记忆：Profile 管可见集合，Policy 管调用时决策。

3. Connection 生命周期

stateDiagram-v2
  [*] --> Draft
  Draft --> Active: health ok + catalog reviewed + enable
  Active --> Disabled: operator / health / security
  Disabled --> Active: revalidate + enable
  Active --> Archived
  Disabled --> Archived

新 Connection 默认不应立即开放。典型流程：

1. 保存 transport 和 secret refs；
2. health check；
3. catalog refresh；
4. review quarantined/new tools；
5. 建 profile/policy/binding；
6. enable。

4. Remote 与 Local Stdio

Remote

适合 SaaS MCP/HTTP。Server 解析 credential refs、验证 URL，再发起请求。

Local Stdio

只在受信任部署/运行主机开放。操作者不能随意粘贴任意 command + args；核心用批准的 command template catalog，降低“配置一个 MCP”变成远程命令执行。

Public/cloud 环境若没有可信 runtime host，应 fail closed。

5. Catalog 与变更隔离

发现 tool 后按 annotations/schema/模板推断风险：

风险	典型语义	默认处理
read	list/get/search	可进入只读 profile
write	create/update/send	默认需更严格 profile/policy
destructive	delete/transfer/revoke	首次/变更时 quarantine，人工明确启用

Catalog 保存 tool/schema hash。上游悄悄增加 write/destructive tool 或改变 schema 时，新条目会 quarantine，旧 trust rule 也因 hash 漂移失效。

这是供应链防线：不要假设同一个 MCP endpoint 永远暴露同一能力。

6. Profile 选择

Profile 有 default allow/deny 和 entries，selector 可按：

• application；
• connection；
• catalog entry；
• tool name pattern；
• risk level。

Binding 优先级从窄到宽可理解为：

issue > routine > agent > project > company

运行建立 gateway session 时解析 effective profile。Profile 不匹配的 tool 根本不应出现在 Agent tool list 中，降低模型误调用面。

7. Policy 决策顺序

flowchart TD
  CALL["Tool call"] --> CAT{"catalog active?"}
  CAT -->|quarantined/disabled| DENY["deny"]
  CAT -->|yes| PROF{"effective profile includes?"}
  PROF -->|no| DENY
  PROF -->|yes| BLOCK{"matching block?"}
  BLOCK -->|yes| DENY
  BLOCK -->|no| APPROVE{"require approval?"}
  APPROVE -->|yes| AR["create action request"]
  APPROVE -->|no| RATE{"rate limit exceeded?"}
  RATE -->|yes| RL["rate_limited"]
  RATE -->|no| ALLOW["allow / runtime decision"]

Block 优先于 allow。决策可能是 allow、deny、require_approval、rate_limited 或 defer_runtime。

8. Action Request 与签名参数

需要审批时 Gateway：

1. canonicalize arguments；
2. 计算 arguments hash；
3. 保存 tool/schema/actor/run/issue/expiry；
4. 创建 action request 和任务线程 confirmation；
5. 返回 409 approval_required。

Agent 获批后用相同参数 + approvedActionRequestId 重试。Gateway 重新校验：

tool identity + schema hash + canonical arguments hash + actor scope + expiry

任一变化都不能消费旧批准。

9. Trust Rule

一次批准可被提升为受限 trust rule，条件可包括：

• actor/Company/Agent/Project/Issue scope；
• tool/catalog/schema hash；
• arguments shape/hash；
• approval threshold/count；
• expiry；
• revoke metadata。

Trust rule 是 policy，不是修改 profile。Tool 仍需可见且 active，schema 漂移后规则自然不匹配。

10. Runtime Slot

Local stdio 或需受管理进程的 connection 使用 runtime slot，记录：

• kind/status；
• connection/runtime identity；
• PID/process group；
• endpoint/health；
• last used/restart；
• stop/failure。

Slot 让多个 tool call 复用受控 MCP process，并在 Server restart 后识别/停止孤儿。它不是 Agent runtime service，但生命周期模式相似。

11. Gateway Token

Heartbeat 为受管理 Adapter materialize MCP config，指向 Paperclip named gateway endpoint，并注入短期、scope 化 bearer token。Token 绑定：

• Company/Agent/Run；
• issue/project/responsible user；
• gateway/profile/session；
• expiry/action。

这样 Agent 不直接得到上游长期 credential；每次 call 先回到 Gateway。

12. Gateway 调用时序

sequenceDiagram
  participant A as Agent
  participant G as Paperclip Gateway
  participant P as Profile/Policy
  participant S as Secret Service
  participant U as Upstream MCP
  participant D as Audit DB

  A->>G: tools/call + scoped token
  G->>G: verify run/company/actor context
  G->>P: catalog + effective profile + policies
  alt approval required
    P-->>G: action request
    G->>D: persist signed intent
    G-->>A: 409 approval_required
  else allow
    G->>S: resolve approved secret projections
    S-->>G: ephemeral headers/env
    G->>U: invoke tool
    U-->>G: result
    G->>G: content guard + redaction
    G->>D: invocation + call event + metrics
    G-->>A: guarded result
  end

13. Secret 的数据模型

Paperclip 的 secret 系统包含：

• company secret declaration/metadata；
• version；
• binding；
• provider config/vault；
• user secret definition/value；
• proposal/import；
• access event。

核心目标不是“把 env 存到数据库”，而是保存引用、版本、来源和谁在何上下文访问。

14. Secret Provider

部署级 fallback 可是：

• local encrypted（master key file）；
• AWS Secrets Manager 等外部 provider；
• Company 级命名 provider vault。

Company secret row 可以链接外部 reference，不一定把 value 存进主 PostgreSQL。Provider config 的非秘密连接信息与 credential secret ref 分开。

15. Secret Projection

运行时只把需要的 secret 投影到指定位置：

• environment variable；
• HTTP header；
• adapter config path；
• plugin config path；
• MCP credential ref。

投影要校验：

secret.company == run.company
binding grants Agent/use case
version valid and not revoked
projection class/path allowed
responsible user/grant satisfied
trust preset permits secret access

值只在执行边界短暂存在；DB/activity/API 返回 redacted metadata。

16. Strict Mode 与 Inline Secret 迁移

Authenticated 部署默认更倾向 strict mode，拒绝配置中残留明文敏感值。CLI 提供 migrate-inline-env/doctor，把 adapter/plugin config 中的 inline value 转为 secret ref。

这降低 export、log、UI response 或 config backup 意外泄露的概率。

17. 内容与网络防线

Gateway 不只做权限，还需要：

• remote URL allow/SSRF guard；
• redirect/hostname/IP 重新验证；
• response size/time limit；
• tool result content guard；
• secret/token redaction；
• local stdio allowlist template；
• catalog schema validation；
• audit result summary，而非无限保存敏感 payload。

尤其对 MCP，工具返回内容也可能是 Prompt injection 来源，不能只保护请求方向。

18. 审计与指标

每次调用至少可记录：

• actor/run/issue/responsible user；
• application/connection/catalog/tool；
• risk、profile、matched policies；
• decision/reason；
• action request/trust rule；
• latency/outcome；
• redacted arguments/result summary；
• runtime slot/connection health。

这让 Board 能回答“哪个 Agent 为什么被允许调用哪个工具”。

19. 明确的治理边界

不是主机级 MCP 防火墙

Paperclip 只能治理经过其 Gateway 的调用。如果 Agent 进程读取了操作者手写的 MCP 配置，或有网络/凭据直接访问上游，Paperclip 无法阻止和审计。Managed adapter config 是控制面 containment，不是整个主机的 endpoint firewall。

要强化边界，需要结合 sandbox 网络策略、filesystem 隔离、secret 最小投影和禁止 unmanaged config。

20. 可复用经验

1. 把“工具可见性”和“单次调用授权”拆成 Profile 与 Policy。
2. Catalog 保存 schema hash，新/变更高风险 tool 默认 quarantine。
3. 高风险审批要签 tool + schema + canonical arguments + actor scope。
4. Agent 使用短期 gateway token，不直接拿上游长期 credential。
5. Secret 以版本化引用和受控 projection 交付，访问要留事件。
6. Local stdio 只允许审核过的 command template。
7. 清楚声明治理只覆盖 managed path，并用 sandbox 补主机级边界。

源码入口

• doc/MCP-ACCESS-GOVERNANCE.md
• doc/MCP-RUNTIME-OPERATIONS.md
• server/src/services/tool-access.ts
• server/src/services/tool-access-policy.ts
• server/src/services/tool-gateway.ts
• server/src/services/mcp-http.ts
• packages/db/src/schema/tool_access.ts
• server/src/services/secrets.ts
• packages/db/src/schema/company_secrets.ts、company_secret_versions.ts
• packages/db/src/schema/secret_access_events.ts
• packages/mcp-server/

---

工具决定 Agent 能做什么，Skill 决定它知道怎样做。下一章：16 · Skills 与 Teams Catalog。