MCP 模块代码标准

更新 — 2026-08-18：CoSAI令牌交换、MCP项目沙箱基线、OWASP GenAI基线、Ruby SDK漏洞——授权模式和部署基线

四个发展提供了此代码标准所需的授权模式和部署基线。

1. CoSAI令牌交换（8月18日）——授权模式。 每个MCP模块应在信任边界交换令牌，不持有持久凭证。令牌在几分钟内过期，可即时撤销。

2. MCP项目沙箱基线（8月16日）——部署基线。 每个MCP模块部署必须包含操作系统级沙箱（Landlock/Seatbelt/Windows ACL）。

3. OWASP GenAI MCP服务器安全基线（8月18日）——开发参考。 本标准的目录结构、工具注册和错误处理映射到OWASP GenAI的开发控制。

4. MCP Ruby SDK漏洞（8月16日）——新的CVE类别确认防御姿态。 Ruby SDK DoS扩展了速率限制要求；目录遍历扩展了输入验证要求。参见MCP安全加固检查清单。

更新 — 2026-08-15：DeepSeek Harness — "一切皆插件"验证了模块模式

DeepSeek 于2026年8月13-14日开源了 DeepSeek Harness — 基于 Cordis 元框架的 MIT 运行时。原则：**"一切皆插件。"**数小时内获得33,000+ GitHub 星标。对此标准描述的插件/模块模式的最强行业验证。

为什么代码标准很重要

我们交付的每个连接器都长得一样。这不是巧合——这是纪律。当第二个集成到来时，智能体的能力更容易测试、审计和替换，因为每个 MCP 模块都遵循相同的结构、命名和错误契约。

本文档定义了 IdeaBosque 编排主干中所有 MCP 模块的标准。涵盖目录布局、工具注册、输入输出 schema、错误处理、速率限制、审计日志和 PII 边界处理。

目录结构

每个 MCP 模块都位于 app/mcp_modules/ 下自己的目录中，布局一致：

app/mcp_modules//
  __init__.py
  module.py          # 工具注册 + handler
  schemas.py         # 输入输出 Pydantic 模型
  tests/
    test_module.py
  README.md

工具注册

每个模块通过标准接口注册其工具。编排主干通过扫描 register_tools() 入口点来发现工具——无需手动接线。

def register_tools(registrar):
    """注册本模块提供的所有工具。"""
    registrar.tool(
        name="search_catalog",
        description="按 SKU 或名称搜索供应商目录",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # 每分钟调用数
    )

错误处理

模块必须抛出类型化异常，而不是裸字符串。主干捕获 MCPToolError 子类并将其转换为智能体可推理的结构化响应：

• MCPAuthError — 凭据缺失或过期
• MCPRateLimitError — 触及上游速率限制
• MCPTimeoutError — 上游调用超过配置的超时
• MCPValidationError — 输入未通过 schema 校验
• MCPUpstreamError — 上游返回错误状态

速率限制

每个工具在注册调用中声明自己的速率限制。主干按智能体、按工具、按窗口执行这些限制。当达到限制时，智能体收到一个带 Retry-After 头的 429 响应——它不会崩溃或盲目重试。

审计日志

每次工具调用都记录：时间戳、智能体 ID、工具名、输入哈希（不是原始输入——PII 边界）、输出状态、时长和上游系统。日志以结构化 JSON 写入并推送到可观测性管道。

"每次工具调用都被记录且可审计"不是我们后来才加的功能。它是标准要求的第一件事。

PII 边界处理

模块必须声明哪些输入字段包含 PII。主干在记录前对这些字段做哈希，绝不把原始 PII 发到审计管道。PII 字段在 schema 中标记：

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

当设置 pii=True 时，审计日志器把值替换为 SHA-256 哈希。工具 handler 仍然接收原始值——PII 处理在日志边界强制执行，不在业务逻辑内部。

Update — 2026-08-06: Transport-mode security — the stateful streamable-HTTP attack surface

CVE-2026-16496 (CVSS 10.0, patched in Terraform MCP Server on August 5, 2026) is the first maximum-severity CVE in the MCP ecosystem and the first production evidence that the transport mode is a security dimension, not just an operational one. The vulnerability is a session-hijacking authorization bypass in the streamable-HTTP stateful transport mode: a user who obtains another user's MCP session ID can have their tool calls executed using that user's Terraform credentials. HashiCorp also patched CVE-2026-16498 (tenant isolation break) and CVE-2026-14869 (SSRF) in the same release. (The Hacker News, SentinelOne vulnerability database)

This adds a transport-mode-security rule to the deployment-hardening standard:

5. Prefer stateless transport; treat stateful streamable-HTTP as a security risk. The MCP 2026-07-28 specification moved to a stateless protocol core — the initialize/initialized handshake and Mcp-Session-Id header are removed, and stateful workflows use explicit handles instead of server-side sessions. The stateless design eliminates the session-hijacking attack class at the architecture level: a stateless server has no session to steal. The stateful streamable-HTTP transport mode that CVE-2026-16496 exploits is the mode the stateless core is designed to replace. If a module must run stateful streamable-HTTP (for compatibility with a client that has not migrated), treat it as a known-vulnerable configuration: bind it to a private network, require authentication on every session, and plan the migration to stateless transport on the same 12-month clock as the SSE deprecation. A module that exposes stateful streamable-HTTP on a public interface without authentication is in the same risk class as the 1,467 servers Trend Micro found with zero auth — plus the session-hijacking vector.

The OX Security advisory also expanded with additional CVEs beyond the original four exploit families: CVE-2026-30618, CVE-2026-33224, CVE-2026-30617 (Family 1 — STDIO command injection), CVE-2026-30625 (Family 2 — Upsonic allowlist bypass), CVE-2026-30615 (Family 3 — Windsurf prompt injection), CVE-2026-26015 (Family 4 — SSRF), plus CVE-2025-65720 (GPT Researcher RCE), CVE-2026-30623 (LiteLLM RCE), CVE-2026-30624 (Agent Zero RCE), and CVE-2026-54449 (LangBot RCE). The expanded inventory extends the supply-chain risk beyond MCP servers to the agent frameworks and orchestration layers that wrap them — signed provenance, pinned versions, and AIBOM manifests (the dependency control for MCP) are what make the expanded inventory detectable before it fires.

部署加固：切勿在未认证的情况下暴露 MCP 服务器

STDIO 加固规则解决的是代码层面的漏洞。2026 年 7 月浮现了一个独立的暴露维度，而且它落在了参考实现本身。2026 年 7 月 11 日至 21 日期间，三个 CVE 被提交给官方 MCP Python SDK——每个 Python MCP 服务器都继承自这一参考实现：

• CVE-2026-59950 — 缺少 Host/Origin 验证。受害者访问的网页可以通过 DNS 重绑定和 CSRF 驱动其本地 MCP 服务器。浏览器成为攻击者进入运营商认为私有的 loopback 服务器的代理。
• CVE-2026-52869 — 未验证的会话请求。HTTP 传输在未验证会话的情况下提供会话请求，允许未认证访问。
• CVE-2026-52870 — 开放的任务处理器。实验性任务处理器允许任何客户端访问另一个客户端的任务。

同一两周内，其他 CVE 影响了热门服务器：meta-ads-mcp（CVE-2026-54547 / -54549，auth-token 重用 + SSRF）、LangBot（CVE-2026-54449，已认证 RCE）、ToolHive（CVE-2026-58196，SSRF）和 mcp-atlassian（GHSA-g5r6-gv6m-f5jv，任意文件读取）。该模式是类别层面的，而非孤立的：MCP 为 localhost loopback 设计，团队将其部署到互联网上，而安全基础——认证、来源验证、输入检查——被跳过了。参考实现发布与社区服务器同类缺陷，正是本标准所解决的部署加固证据：下方的认证和来源验证规则不是理想化的——它们关闭了 CVE-2026-59950 和 CVE-2026-52869 背后的根因。

Trend Micro 更正后的后续扫描发现 1,467 个公开可访问的 MCP 服务器没有认证或加密——几乎是从初始 492 个翻了三倍，而非此前引用的"约 2,000"。升级不仅在于数量：1,467 个中有 1,227 个在运行已弃用的 SSE 传输（受 7 月 28 日规范迁移和安全暴露影响最大的群体），execute_sql 工具出现在 70 台主机上，"Graphiti Agent Memory"（一个 agentic MCP 服务器）在 39 台主机上——是窃取内存驻留数据的主要目标——至少三台服务器通过"progress_note"工具暴露患者病历。威胁从本地 STDIO 配置扩展到了可从互联网访问的云部署 MCP 服务器。其中许多服务器向任何能够访问该端口的人暴露了硬编码凭据、工具端点和系统访问权限。

BlueRock Security：7,000+ MCP 服务器中 36.7% 存在 SSRF 漏洞。 BlueRock Security 分析了超过 7,000 个 MCP 服务器，发现 36.7% 可能存在 Server-Side Request Forgery 漏洞——这是比 Trend Micro 的 1,467 台暴露服务器扫描更大的语料库，且属于不同的漏洞类型。SSRF 允许攻击b者强制 MCP 服务器向服务器可达但攻击者不可达的内部网络资源发起请求——云元数据端点、内部 API、数据库。36.7% 是新的总合漏洞统计数据：超过三分之一的 MCP 服务器可以被欺骗探测内部网络。对于 B2B 部署，SSRF 风险尤为严峽，因为 MCP 服务器通常可以访问内部系统（ERP、CRM、库存数据库）——一个获取供应商目录的服务器可以被重定向去获取云元数据端点并泄露凭据。

2026 年 7 月波次中出现了三个额外的 CVE，将 CVE 时间线扩展到了官方 SDK 漏洞之外：

• CVE-2025-68143 — 路径遍历。MCP 服务器允许通过精心构造的路径参数访问预期目录之外的文件，实现代理主机上的任意文件读取。
• CVE-2025-68144 — 参数注入。接受命令行参数的工具可以被强制执行操作员未预期的额外标志，类似于上文 OX Security 四规则标准中记录的 STDIO 允许名单绕过模式。
• CVE-2025-68145 — 仓库范围绕过。应限制于单个仓库的服务器可以访问声明范围之外的仓库，暴露私有代码和密钥。

cyberdesserts.com 确认 2026 年 7 月 28 日的协议修订版未关闭授权模型缺口——允许受损工具描述或输出劫持代理行为的结构性漏洞在最终规范中仍然存在。无状态重设计提高了运营效率，但未解决 MCP03（tool poisoning）、MCP06（intent flow subversion）或 MCP10（context over-sharing）。治理层仍是操作员的责任——本标准是该责任的实现合约。

Spec final 迁移注释（2026 年 7 月 28 日）。 MCP 2026-07-28 规范作为最终版发布，限限 12 个月的 SSE 废弃策略：SSE 传输已废弃，必须在 12 个月内迁移到 Streamable HTTP 传输。四个 Tier 1 SDK（Python、TypeScript、Java、Kotlin）均已发布兼容版本。使用 SSE 传输的模块必须迁移；使用 STDIO 的模块不受影响。迁移是传输层更改——本标准中的工具注册、错误处理、速率限制和审计日志规则与传输无关。模块合约不变；变的只是传输绑定。

部署加固规则：

1. 切勿在未认证的情况下将 MCP 服务器暴露在公共接口上。 每个 MCP 服务器——无论是 STDIO、SSE 还是 HTTP 传输——都必须要求认证（OAuth 2.1 with PKCE、API key 或 mTLS）。一个在没有认证情况下可从 0.0.0.0:3000 访问的服务器是一个远程代码执行面，而非开发便利。

2. 绑定到 localhost 或私有网络。 生产 MCP 服务器绑定到 127.0.0.1 或私有子网。如果需要外部访问，请通过带有认证、速率限制和 TLS 终止的反向代理路由——而非直接暴露端口。

3. 切勿在 MCP 配置文件中硬编码凭据。 Trend Micro 扫描在可公开访问的 MCP 服务器配置中发现了硬编码的 API key、数据库密码和 OAuth 密钥。凭据必须来自环境变量或密钥管理器——绝不能来自攻击者可以读取的 JSON 文件。

4. 加密所有传输。 STDIO 按定义仅限本地，但 SSE 和 HTTP 传输必须使用 TLS。公共网络上的明文 HTTP MCP 服务器会将每次工具调用——包括认证令牌和 PII——暴露给网络级拦截。

Trend Micro 扫描是 OX Security 公告在部署侧的补充：代码层面的漏洞（未经清理的 STDIO、allowlist 绕过、配置注入）在服务器本身未认证暴露时变得可被远程利用。没有部署加固的代码加固是一扇锁着的门装在一个敞开的前廊上。

更新 — 2026-08-07：MCP 服务器可发现性和治理 — Black Hat 2026 产品维度

完整的 Black Hat 2026 产品清单（crn.com，2026年8月4日）为 MCP 代码标准增加了新的维度：MCP 服务器可发现性和治理。Black Hat USA 2026 上推出的三个产品直接解决了代码标准（管理模块如何编写）与部署现实（管理存在多少模块以及谁了解它们）之间的差距。

1. Cyera Agent Guardian — 影子 MCP 服务器发现。 代码标准假设每个 MCP 模块都已注册、文档化并遵循目录结构和错误合约。Cyera 的产品揭示了差距：大多数企业中存在不遵循代码标准的影子 MCP 服务器 — 由个别开发者安装、从收购中继承，或作为从未退役的概念验证部署。代码标准管理已授权模块；Cyera 发现未授权的。

2. SailPoint Identity Security — MCP 服务器身份生命周期。 代码标准管理模块如何认证。SailPoint 的产品增加了生命周期维度：每个 MCP 服务器都有一个必须通过身份治理工作流来配置、证明和撤销的身份。硬编码凭据的模块无法通过身份生命周期进行治理；使用 OAuth 2.1 和托管凭据的模块可以。

3. Check Point AI Network Firewall — 网络层 MCP 通信监控。 代码标准管理模块在应用层记录什么。Check Point 的产品增加了网络层维度：MCP 通信通道现在可以在网络层监控。在应用层不记录工具调用的模块仍可在网络层监控，但在两层都记录的模块才是产生完整审计跟踪的模块。

Black Hat 2026 MCP 服务器发现产品为代码标准增加了"可发现性和治理"维度：遵循目录结构、错误合约和安全规则的模块是编写良好的模块，但也注册在身份治理平台（SailPoint）中、可被影子服务器检测工具（Cyera）发现、并在网络层监控（Check Point）的模块是治理良好的模块。代码标准是基础；Black Hat 2026 产品是其上的治理层。

更新 — 2026-08-08：Skill/Plugin Security Scanning — 厂商侧供应链缓解

Anthropic 于 2026 年 8 月 6 日发布了 Skill/Plugin Security Scanning — 首个模型厂商侧第三方工具服务器供应链缓解措施。该扫描在第三方 Claude Code 上传（skills 和 plugins）到达 marketplace 之前检查其是否包含恶意内容。这是运营商对自身工具定义进行扫描的厂商侧补充：Control 10（工具投毒防御）管辖你对自身工具定义的扫描；Skill/Plugin Scanning 管辖模型厂商在其 marketplace 上做的检查。