存量业务系统MCP化落地实践：712个接口零改造接入AI Agent

这套方法论来自一套已落地的存量业务系统实践：712 个接口、零改造、端到端验证通过。读完本文，你能拿到目标架构、能力抽象方法、落地步骤、一份避坑清单，以及一个 MVP 定义——业务系统一行代码不动。

MCP #AIAgent #内部平台 #落地指南

一、目标架构：MCP Server 作为统一接入层

内部平台不直接为每个 Agent 各写一套接口，而是先抽象成一组标准化工具（MCP Tools），WorkBuddy、Hermes、OpenClaw 等各 Agent 通过 MCP 协议 或 HTTP 适配器统一接入。架构自顶向下四层，职责一句话说清：

维度	说明
Agent 层	理解用户意图、选择并调用工具；侧配置仅需 MCP 地址 + apiKey 请求头
接入层	MCP Server + HTTP API Gateway 统一暴露内部能力
治理层	账号映射、角色权限、审批单、审计日志、限流熔断，全部内嵌在接入层管道里
内部平台层	现有 REST API、数据库、流程引擎，原封不动；数据库只开一条只读通道兜底长尾查询

配套的第一条路线决策是外挂零改造。改造系统内部代码（塞 MCP 端点、改鉴权）会绑架业务发版节奏，老系统常有“框架冻结”的隐形铁律；逐接口一对一包装会让工具数量爆炸。外挂适配层让 AI 需求的迭代节奏与业务系统彻底解耦，并带来最重要的安全红利：Agent 登录的是真实用户账号，看得见什么数据由平台说了算。业务系统的权限体系就是 Agent 的权限体系，不用重建，也没有越权旁路。

二、内部平台能力抽象

接口众多，不能一股脑暴露。按业务场景归为四类：查询类（只读，优先开放）、写入类（需权限校验 + 审批）、流程类（工作流触发，高权限）、知识类（作 RAG 数据源）。每个工具定义五要素：名称、描述、输入参数 Schema、是否只读、是否需要审批及所需权限角色。

实测补充两条。一是盘点先行：不要从“要开放哪些”开始，从“系统到底有多少”开始。脚本扫描全部服务注册注解生成接口清单，机器初分类（查询/写/其他/认证），再补两轮人工复核——第一轮按代码实义纠错（名字像查询、实义是写的要剔除），第二轮对照前端页面实际调用实证。产出一份机读的开放口径：哪个域、哪些接口、是查询还是写。没有全量盘点，你回答不了安全评审的第一个问题：“开放的是全量还是漏了一部分？”

二是唯一事实源：所有“场景→接口”的映射只存一份机读目录文件（tools.yaml）。工具注册、运行时白名单、文档三者共用这一份，服务启动时动态生成工具定义——加接口等于加一行配置，不改代码。配套校验脚本做双向对账：目录里的码必须真实存在于盘点清单，盘点口径里的码必须被目录覆盖，全覆盖无重复才算数。

三、MCP Server 实现

部署一个独立的 MCP Server，核心职责四块：工具注册与管理（启动时自动注册，list_tools 供 Agent 发现）、身份校验与账号映射（禁止超级账号统一代理，操作可追溯至具体责任人）、工具调用执行（查询直接返回，写操作先落草稿人工确认）、审计日志记录（所有调用的完整上下文）。

实现选型的实测原则是与内部平台同生态、运维不用学新东西：Java 系用 Spring Boot + 官方 MCP Server Starter，Python 系用 FastMCP，不必追最新最好。传输统一 Streamable HTTP 部署为远程服务；另开一个极简 JSON 兼容通道给不支持 MCP 协议、只能配 HTTP 连接器的客户端——两个通道背后同一个路由器，治理逻辑不重复实现。

这一步有一条实测铁律：任何工具的参数定义里都没有 token 字段。token 是敏感凭据，进模型上下文就可能被记录、被幻觉；而服务端本来就要替 Agent 保管会话，没必要传。第一版只做登录、身份查询、身份切换、登出这几个会话工具，跑通“登录→token 托管→登出失效”闭环再扩展业务工具。未登录调用不出网关，直接返回结构化错误 + 登录指引，模型读错误即可自我修正——“会话过期→自动重登”的闭环不需要人参与。

四、防膨胀策略

工具列表直接进模型上下文，工具数量就是成本和选择错误率。方案给了六条策略，实测按四级分类执行最有效：

维度	说明
L1 高频核心	注册为独立工具，描述写精细
L2 中频场景	聚合为领域工具：一个域一个工具，内部用 scene 枚举参数路由到具体接口
L3 长尾接口	通用 execute_api 工具 + 白名单，通过参数指定目标接口
L4 敏感/复杂写操作	不暴露，走人工审批流，评审后才逐域开放

实测数据：712 个接口按此分级压到 23 个工具。三个配套手法：查询信息（目录、字段表、枚举字典）做成 MCP Resources，Agent 通过 URI 读取，不占工具名额；所有业务工具共用一个参数外壳（scene + id + keyword + 分页 + params 透传），场景特有参数走 params，服务端按字段表落位；业务域差异大的话再考虑拆分多个 MCP Server 按域管理。动态工具发现（按调用者身份返回不同工具集）放在写域开放阶段再做，第一版用不上。

五、权限与安全设计

企业内部系统接入 Agent，安全比连通性更重要。方案要求六项措施，实测补充执行细节：

身份映射：Agent 携带用户身份标识，映射到内部平台真实账号，禁止超级账号代理。权限分级：查询、写入、审批、管理员操作严格分离，每个工具声明最低权限角色。写操作审批：先落草稿人工确认后执行；实测约束更严——写场景只放行经过端到端验证的域，且 Agent 调用前必须向用户复述关键参数（单号/金额/客户）并获确认，平台状态机校验原样透传，不绕过不软化。审计日志：谁、经哪个 Agent、调了什么、参数摘要、结果、耗时，全部可回放；先落本地文件，尽快接日志平台做告警——只在本地文件里等于没有审计。限流熔断：令牌桶按 apiKey / 按用户分桶限流，系统级错误连续出现即熔断快速失败，防故障扩散。敏感字段脱敏：手机号、证件、银行卡掩码，密码类字段列名命中即置星号。

安全治理不做成独立“安全模块”，而是嵌入调用管道的每一环：入口校验 apiKey → 路由时限流 → 白名单闸 → 调用内部 API → 出口脱敏 + 超量行截断 → 错误语义映射 → 审计。白名单闸是关键一道：场景不在目录即拒绝，平台根本收不到请求。数据库直查工具（兜底长尾取数）必须三道闸缺一不可：专用只读账号（最硬，账号复用等于拆掉它）、语句白名单 + 禁多语句 + 自动 LIMIT、出口同一套脱敏策略。

六、各 Agent 接入方式

所有 Agent 优先走 MCP 协议统一接入，复用同一套工具定义。Agent 侧配置总共两行：

{
  "mcpServers": {
    "internal": {
      "url": "http://<host>:<port>/mcp",
      "headers": {
        "X-Api-Key": "ak-xxx"
      }
    }
  }
}

各平台的取舍：WorkBuddy 类支持 HTTP 连接器的，可先在集成中心配置 HTTP 连接器（定义 URL、请求头、参数映射）快速验证，再迁到 MCP 连接器；Hermes、OpenClaw 等原生支持 MCP 的直接注册 MCP Server 端点，按需暴露工具列表。不支持 MCP 的客户端统一走 HTTP 兼容通道桥接。实测多客户端验收标准：至少三个异构客户端用同一套工具定义完成同一场景，全过才算接入完成。后续接入新平台，连到同一个 MCP Server 即可，内部系统不再动。

七、推荐落地步骤

方案推荐六步，实测给每步补一个产出物门槛：

维度	说明
梳理平台能力	脚本盘点 + 两轮复核，产出接口清单和能力分级表（机读）
定义工具	五要素定义落进 tools.yaml，与盘点口径双向对账通过
搭建 Server	先只做查询类工具 + 会话闭环，产出可被 MCP Inspector 连通的服务
接入鉴权审计	身份绑定真实账号 + 审计日志上线，产出安全用例脚本全绿
分 Agent 接入	MCP 优先，HTTP 桥接兜底，三个异构客户端同场景验证
灰度开放	先少量用户只读场景，监控调用量与异常率，逐步扩到写操作和全流程

灰度环节实测追加一道发布门槛：覆盖矩阵逐码探测，FAIL=0 才准发布——直连网关对全部映射接口发最小参数查询，不依赖 MCP 实现，验证的是映射与开放口径本身。写操作的准入考试更严格：Agent 仅凭自然语言目标独立走完一个真实业务全流程，越状态操作被平台正确拒绝，该域才算通过。

八、最小可行版本

MVP 三件套：一个 MCP Server 基础版（MCP 协议 + HTTP 兼容通道）+ 两个只读工具（如查询订单、检索知识库）+ 完整的审计日志和权限校验。审计和权限从第一天就要有，这是后来一切扩展的地基——宁可工具少，不可治理缺。

跑通后的演进顺序：生产化加固（专用只读账号、apiKey 列表化可吊销、审计接日志平台、TLS、高危写操作人工二次审批）→ 写操作逐域开放（一次一个域，草稿 + 人工确认模式，每域过端到端准入）→ 评测体系（工具选择准确率、任务完成率基准集，防静默劣化）→ 多系统统一 Agent 入口。判断标准很简单：后续新 Agent 平台只需连到同一个 MCP Server，第二个内部系统两周能到同样验证水平，这套方案才算成立。

避坑清单

全部为实测踩过，你的系统大概率有同款：

维度	说明
隐藏必填字段	登录有字段由前端框架静默注入，接口定义里看不到——登录链路必须对照前端实际报文实证
参数命名不统一	同一平台 page 与 pageNo 并存是常态，统一参数必须在服务端按字段表改写落位，并实测翻页生效
响应结构各异	数据有的在 list、有的在 data、有的在 rows，出口归一化，别让模型猜
静默降级	缺字段不报错但后续流程被拒，最隐蔽——只有端到端验证能抓住
状态机隐性依赖	“能查到”不等于“能操作”，中间可能隔着前置步骤，业务流程图写进工具描述
平台默认选择	有分支的业务规则（如差额处理方式）必须让模型显式询问用户，不能吃平台默认值