MCP 实战：为 AI Agent 设计标准化工具与资源接口

为什么 Agent 需要一层标准化连接协议

当一个 Agent 只接入两三个内部 API 时，直接写工具适配器很自然。随着数据源、文件系统、数据库和业务服务增加，问题会迅速出现：每个客户端维护一套工具定义，认证方式不一致，返回格式各自为政，新增能力还需要重新发布 Agent。

MCP（Model Context Protocol）解决的核心问题，不是替模型做决策，而是让应用用统一方式发现和调用外部能力。它把“模型如何思考”与“系统能提供什么上下文和动作”分开，使工具提供方和 Agent 应用可以独立演进。

Host、Client 与 Server 的职责

一个清晰的 MCP 接入通常包含三个角色。

Host 是用户真正使用的 Agent 应用。它拥有对话、模型选择、权限策略和用户界面，也是最终的信任边界。Host 决定某个 Server 是否可以连接、哪些能力可以暴露给模型，以及调用前是否需要审批。

Client 运行在 Host 内部，维护与某个 MCP Server 的会话。它负责能力发现、协议消息、超时和连接状态。一个 Host 可以同时管理多个 Client，但不应把不同 Server 的数据和凭据随意混合。

Server 对外提供工具、资源或可复用提示。它应封装具体系统的细节，例如把内部工单 API 转成语义清楚的 get_ticket 和 add_ticket_note，而不是把底层 HTTP 请求原样暴露出去。

这三个角色的边界很重要：Server 声明它能做什么，Host 决定是否允许做，模型只在当前被允许的动作空间内选择。

工具、资源和提示不要混为一谈

工具代表动作，通常带参数并可能产生副作用。查询订单和发送消息都属于工具，但风险完全不同，Host 应根据读写性质和当前用户权限分别处理。

资源更接近可读取的上下文，例如项目说明、数据库 Schema 或日志片段。资源 URI 应稳定、可引用，并且在读取时执行访问控制。不要把完整敏感数据库作为一个无限制资源暴露给 Agent。

提示模板可以提供特定工作流的建议输入结构，但它不应获得比用户或系统规则更高的权限。来自 Server 的任何文本都要被视为外部内容，而不是可信系统指令。

设计一个可用的 MCP Server

先从窄而清楚的业务能力开始。与其提供万能的 execute_api，不如提供少量语义明确的工具：

{
  "name": "create_incident_draft",
  "description": "创建事故记录草稿，不会通知外部人员",
  "inputSchema": {
    "type": "object",
    "required": ["title", "severity", "evidenceIds"],
    "properties": {
      "title": { "type": "string", "maxLength": 120 },
      "severity": { "enum": ["S1", "S2", "S3", "S4"] },
      "evidenceIds": {
        "type": "array",
        "items": { "type": "string" },
        "minItems": 1,
        "maxItems": 20
      }
    },
    "additionalProperties": false
  }
}

描述中既要说明能力，也要说明边界。“创建草稿”明确告诉 Agent 这不是正式发布；枚举和长度限制减少参数猜测；证据 ID 让结果可追溯。

返回值同样需要结构化。成功时包含业务主键、状态和下一步允许动作；失败时返回稳定错误码、是否可重试和用户可理解的说明。不要把内部堆栈、访问令牌或整页 HTML直接塞回模型。

连接方式不等于安全模型

无论 Server 运行在本机还是远程，都不能因为“连接成功”就默认可信。Host 应保存清楚的来源信息，首次接入时向用户说明能力范围，并在 Server 能力发生变化时重新确认。

本地进程需要限制环境变量、文件系统和子进程权限；远程服务需要加密传输、身份验证、租户隔离和请求级授权。凭据最好保存在 Host 或专门的凭据代理中，按调用注入，而不是写入模型上下文或工具参数。

高风险工具应由 Host 进行参数绑定审批。用户批准的是“向指定对象执行指定动作”，而不是永久信任某个 Server。Server 返回的网页、文档和错误文本也可能包含提示注入，不能改变 Host 的权限政策。

能力发现与版本演进

能力发现让 Agent 不必把所有工具写死，但动态变化也带来风险。Host 可以为每次运行保存能力快照：工具名、Schema、Server 版本和授权范围。这样出现问题时可以还原模型当时看到了什么。

破坏性 Schema 变化应使用新工具名或明确版本，不要静默改变字段含义。新增可选字段通常更安全，但仍要做回归评测。工具被移除时，正在运行的长任务需要收到可处理的错误，而不是无限重试。

不要一次把几百个工具全部交给模型。Host 可以先按 Server、任务阶段和用户权限筛选，再将十几个以内的候选能力放入当前上下文。动作空间越小，选择准确率通常越高。

可观测性与测试

每次调用至少记录运行 ID、Server、工具名、参数摘要、授权结果、耗时、结果码和业务对象 ID。敏感参数只能脱敏记录。连接断开、Schema 不匹配和权限拒绝需要区分，否则运维人员只会看到统一的“工具失败”。

测试应覆盖能力发现、参数边界、取消、超时、重复调用、Server 重启、恶意资源内容和授权过期。写操作必须具备幂等键或业务唯一约束。

小结

MCP 的价值在于标准化 Agent 与外部能力的连接面，但标准协议不会自动带来安全与可靠性。真正可用的接入仍需要清楚的工具语义、Host 侧授权、最小数据返回、版本管理和完整审计。把协议当作边界，而不是捷径，才能让更多能力接入后仍然可控。