使用 TypeScript 构建 Anthropic Agent SDK：架构与 MCP 安全

围绕 Anthropic 工具构建安全的 TypeScript 智能体时，应将 MCP 服务器与工具结果视为彼此独立的信任域。不要把凭据放进提示词，只允许白名单中的服务器和工具，验证每个参数，对有重要外部影响的写操作要求审批，并验证事后条件。具体 SDK API 和软件包版本可能变化，因此应以当前官方文档为准确认实现细节。

先梳理运行时，再编写代码

先画出各个组件：用户界面、智能体运行时、模型提供方、MCP 客户端、MCP 服务器、本地或远程工具、数据存储和审批服务。标明在哪里建立身份、密钥存放在哪里，以及哪个组件能够产生外部影响。这个威胁模型比从一张庞大的工具清单开始更有用。

在 TypeScript 中为请求、工具输入、结果、错误和审批凭证定义领域类型。但仍然需要运行时校验，因为静态类型在跨进程边界时会消失。应使用 JSON Schema 或校验库，在工具运行前拒绝未知字段、无效枚举、超大值和意外 URL。

MCP 边界与服务器信任

MCP 规范化了上下文交换，但建立协议连接并不代表对方值得信任。为每个服务器记录其所有者、传输方式、版本、可用工具和所需的数据访问权限。优先采用显式配置，而不是自动发现。锁定依赖版本，并审查工具描述的变更，因为描述会影响模型选择。

遵循最小权限原则。读取仓库的功能不需要 Shell 权限；总结工单的功能不需要编辑工单的权限。可行时分离读服务器和写服务器。对于远程传输，应依据最新官方指引验证身份认证、TLS、受众和租户边界。对于本地传输，应保护可执行文件路径、环境变量和工作目录。

工具 Schema、审批与事务

工具名称应描述一个动作。输入应使用严格的枚举和有长度上限的字符串，而不是自由格式命令。在可信代码中解析资源标识符。不要让模型构造任意文件路径、SQL、Shell 片段或回调 URL。对于写操作，返回预览，让用户检查准确的目标和载荷。

用 nonce、过期时间、执行者和哈希将审批绑定到该预览。如果载荷发生变化，审批就会失效。使用幂等键，并在写入后读取状态进行验证。当网络超时导致结果不确定时，重试前先查询当前状态。这样可以避免重复评论、订单、部署或删除。

密钥、上下文与提示词注入

密钥应存放在密钥管理器或受保护的进程环境中，并且只注入需要它的工具。绝不要把 API 密钥放进模型上下文或日志。发送到遥测系统前，先对请求头、令牌、用户数据和工具结果进行脱敏。按工具应用外发规则，防止被攻破的服务器向任意目的地发送数据。

将所有由 MCP 提供的文本视为不可信。文档可能要求智能体忽略指令或调用其他工具。保留来源标签和引用边界。系统策略、用户审批和工具授权必须优先于检索到的内容。对于敏感决策，应要求证据，而不是接受文档自称的权威。

可观测性与安全失败

记录结构化追踪信息：请求 ID、模型决策、选定工具、已验证参数、策略结果、审批引用、工具回执和事后条件。日志应支持事故调查，但不要保留不必要的提示词内容。将安全事件与应用调试分开，并根据敏感程度定义保留期限。

在身份缺失、审批过期、Schema 不匹配、服务器未知或事后条件不明确时，应默认拒绝。只重试已分类的临时错误。按用户和工具限流，限制循环步数，并提供停止开关。无法证明已完成的智能体应报告不确定性，而不是声称成功。

测试控制平面

独立于模型对校验器和授权进行单元测试。增加集成测试，使用会返回格式错误 Schema、注入指令、超大载荷、慢响应和虚假成功的模拟 MCP 服务器。测试跨租户标识符和过期审批的重复使用。对工具描述和返回内容都进行红队测试。

上线前，确认当前的 Anthropic Agent SDK 与 MCP 文档、软件包版本、传输要求和安全建议。本指南定义的是一种架构模式，并不声称某个特定 SDK 版本会自动执行所有控制。

实现工作表

在连接生产数据前，先构建最小测试工具架。注册一个只读 MCP 服务器，在运行时验证输入，并记录经过脱敏的追踪信息。只有在准备、审批、提交和验证都被表示为独立操作后，才添加写工具。然后测试未知服务器、变更后的工具 Schema、过期令牌、注入的文档文本、重复请求和不确定的超时。在实现过程中持续查看最新的官方 SDK 与协议文档，因为软件包名称、API 和传输指引可能变化。