一、背景为什么要把普通接口包装成 MCP在传统 Web 项目中后端接口主要是给前端页面调用的。典型链路是前端页面 → HTTP REST 接口 → 后端 Controller → Service → 数据库比如用户在页面上点击“保存闪念”前端会请求后端的保存接口然后后端完成数据入库。但是在 Agent 场景下调用方式变了。Agent 不一定通过页面按钮操作它更像是一个“能理解自然语言并主动选择工具执行任务”的智能助手。例如用户对 Trae Agent 说帮我记录一条闪念以后给人生系统加一个每日自动复盘功能。Agent 需要知道有没有“保存闪念”这个能力这个能力叫什么需要传哪些参数调用后会产生什么结果这个能力能不能安全执行。这时候普通 REST 接口本身是不够的。它需要被包装成 Agent 能理解、能选择、能调用的 MCP 工具。二、什么样的接口可以被 Agent 直接调用在当前项目中判断一个接口能否被 Agent 直接调用核心标准是Controller 方法上同时具备Tool和McpOperation并且通过 MCP endpoint 暴露出去的功能才算 Agent 可以直接调用的接口。也就是说普通 Controller 方法并不会自动变成 Agent 工具。普通接口通常是这样的PostMapping(/save)publicResult?save(RequestBodyThoughtSaveReqreq){returnthoughtService.save(req);}它可以被前端页面调用但 Agent 不一定知道它的存在。如果要让 Agent 能调用就需要增加工具声明例如Tool(thought_save)McpOperation(namethought_save,description保存一条闪念可附带多个关联事件)PostMapping(/save)publicResult?save(RequestBodyThoughtSaveReqreq){returnthoughtService.save(req);}这样之后这个方法就不仅是一个 HTTP 接口也成为了一个 MCP Tool。三、当前项目中 Agent 可以直接调用的能力目前项目里已经暴露了一些 MCP 工具例如MCP 工具名对应能力Agent 可以做什么thought_save保存闪念Agent 可以帮用户新增一条灵感、想法、随手记time_record_queryByDateRange按日期范围查询时间记录Agent 可以拉取一段时间的时迹用于总结分析time_record_save保存时间记录Agent 可以新增一条时迹甚至附带运动记录例如用户说帮我记录一条闪念以后做一个自动整理每日总结的功能。Agent 在连接 MCP 后就可以选择调用thought_save再比如用户说帮我查询这周的时间记录然后总结我主要把时间花在哪些事情上。Agent 就可以调用time_record_queryByDateRange然后再基于返回的数据进行分析和总结。四、完整链路示例Agent 帮用户保存一条闪念下面以“保存闪念”为例完整说明一次 Agent 调用 MCP 工具的过程。假设用户在 Trae Agent 中输入帮我记录一条闪念以后给人生系统加一个每日自动复盘功能关联事件是“晚上看完时间记录后自动总结”。完整链路如下用户自然语言 ↓ Trae Agent / MCP Client 理解用户意图 ↓ 发现 MCP 工具中存在 thought_save ↓ Agent 构造 thought_save 的结构化参数 ↓ 请求 MCP endpoint例如 http://localhost:45678/api/mcp ↓ MCP endpoint 接收工具调用 ↓ 根据工具名找到 Tool McpOperation 对应的方法 ↓ 执行 ThoughtController.save(...) ↓ 调用 ThoughtService / Mapper ↓ 写入数据库 ↓ 返回保存结果给 Agent ↓ Agent 回复用户已保存这个过程本质上就是自然语言 → 工具选择 → 参数构造 → 工具调用 → 业务执行 → 结果反馈五、Agent 如何把自然语言变成工具参数用户说的是帮我记录一条闪念以后给人生系统加一个每日自动复盘功能关联事件是“晚上看完时间记录后自动总结”。这不是一个 HTTP 请求也不是 JSON 参数。Agent 要先理解用户意图用户想新增一条闪念并且带一个关联事件。然后 Agent 会根据 MCP 工具描述选择thought_save并构造类似这样的参数{content:以后给人生系统加一个每日自动复盘功能,events:[{content:晚上看完时间记录后自动总结}]}这个过程就是 Agent 调用工具的核心能力自然语言 → 结构化参数而 MCP 工具描述的作用就是告诉 Agent这个工具叫什么这个工具适合什么场景需要什么参数参数分别代表什么调用后会产生什么结果。六、MCP endpoint 在链路中起什么作用Agent 并不是直接请求普通业务接口例如/api/thought/save而是统一请求 MCP 入口例如http://localhost:45678/api/mcpMCP endpoint 的作用类似一个“工具分发中心”。它负责接收 Agent 的工具调用请求然后根据工具名找到后端对应的方法。例如 Agent 调用的是thought_save后端 MCP 框架就会找到类似下面的方法Tool(thought_save)McpOperation(namethought_save,description保存一条闪念)publicResult?save(...){...}最终再进入真实业务逻辑ThoughtController.save ↓ ThoughtService.save ↓ ThoughtMapper.insert ↓ MySQL 数据库所以 MCP 并不是替代原来的业务系统而是在原有业务系统外面增加了一层 Agent 可调用入口。七、普通 REST 接口和 MCP Tool 的区别普通 REST 接口更多是“技术接口”主要面向前端页面。MCP Tool 更像是“Agent 可理解的业务能力”主要面向智能体。两者区别如下对比项普通 REST 接口MCP Tool使用对象前端页面、外部系统Agent、MCP Client、Trae调用方式HTTP 请求MCP 工具调用是否需要工具描述通常不需要必须需要参数设计偏页面表单、接口 DTO偏业务语义、自然语言可映射调用入口具体 URL统一 MCP endpointAgent 是否能理解默认不能可以理解安全要求常规接口权限控制需要额外考虑 Agent 误调用风险简单来说REST 接口解决的是“前端怎么请求后端”MCP Tool 解决的是“Agent 怎么理解并调用一个业务能力”。八、普通接口如何包装成 Agent 可调用的 MCP 工具把一个普通接口包装成 MCP 工具不是简单加一个接口地址而是要补齐 Agent 调用所需要的信息。核心步骤如下普通业务方法 ↓ 增加工具名称 ↓ 增加工具描述 ↓ 设计适合 Agent 的参数 ↓ 明确返回结果 ↓ 增加安全校验 ↓ 暴露到 MCP endpoint以“保存闪念”为例原来的普通接口可能是PostMapping(/save)publicResult?save(RequestBodyThoughtSaveReqreq){returnthoughtService.save(req);}包装成 MCP 工具后可以变成Tool(thought_save)McpOperation(namethought_save,description保存一条闪念可附带多个关联事件)PostMapping(/save)publicResult?save(RequestBodyThoughtSaveReqreq){returnthoughtService.save(req);}这样这个方法既可以被前端页面通过 REST 调用也可以被 Agent 通过 MCP Tool 调用。九、更推荐的设计REST Controller 和 MCP Tool Controller 分开虽然可以在同一个 Controller 方法上同时加 REST 注解和 MCP 注解但在实际项目中更推荐把两类入口拆开。推荐结构如下ThoughtController └─ /api/thought/save 给前端页面调用 ThoughtMcpToolController └─ thought_save 给 Agent 调用 ThoughtService └─ saveThought(...) 执行真实业务逻辑也就是说REST Controller 负责页面接口 MCP Tool Controller 负责 Agent 工具 Service 负责复用业务逻辑这样前端和 Agent 的入口分开但底层业务逻辑复用同一套 Service。推荐链路如下前端页面 ↓ ThoughtController.save ↓ ThoughtService.saveThought ↓ 数据库Agent / Trae ↓ MCP endpoint ↓ ThoughtMcpToolController.thoughtSave ↓ ThoughtService.saveThought ↓ 数据库这样设计的好处是好处说明职责更清晰REST 给页面MCP 给 Agent参数更可控MCP 参数可以专门设计得更适合自然语言安全性更好可以对 Agent 调用做单独限制不影响前端MCP 工具调整不会破坏已有页面接口后续扩展更容易新增 Agent 工具时结构更清楚十、为什么不建议所有普通接口都直接暴露给 AgentAgent 调用工具的特点是根据自然语言判断用户意图自然语言本身可能存在歧义。例如用户说把昨天那条闪念删掉。这句话就有很多不确定性昨天可能有多条闪念 用户到底想删哪一条 是永久删除还是放入回收站 是否需要二次确认。如果直接把删除接口暴露给 Agent就可能出现误删数据的问题。所以并不是所有普通接口都适合包装成 MCP 工具。MCP 工具应该优先暴露那些语义明确参数清晰风险可控适合自然语言触发不容易造成严重副作用的能力。十一、哪些接口适合包装成 MCP1. 查询类接口最适合例如查询本周时间记录 查询最近闪念 查询今天待办 查询本月消费查询类接口一般没有破坏性适合优先包装成 MCP 工具。可以设计成time_record_queryByDateRange thought_query todo_query expense_query2. 新增类接口比较适合例如保存闪念 新增时迹 新增待办 新增消费记录 新增学习记录新增操作和自然语言输入非常匹配。可以设计成thought_save time_record_save todo_save expense_save study_record_save3. 修改类接口可以包装但要限制例如修改闪念内容 更新时间记录 修改待办状态这类接口最好要求必须传明确 ID例如thoughtId timeRecordId todoId不要只依赖模糊表达例如昨天那个 刚才那个 上次那个否则 Agent 可能会改错数据。4. 删除类接口最谨慎例如删除闪念 删除时间记录 批量删除待办删除类接口风险最高建议不要直接暴露或者设计成两段式先查询确认 ↓ 再执行删除例如thought_prepare_delete thought_confirm_delete也可以只允许软删除把 status 改成 deleted这样即使发生误操作也有恢复空间。十二、设计 MCP 工具时需要注意什么1. 工具名要清晰建议使用模块_动作例如thought_save thought_update time_record_queryByDateRange todo_complete不建议使用过于模糊的名称例如save update doSomething handle因为 Agent 需要根据工具名和描述判断是否调用名称越清晰误调用概率越低。2. 工具描述要明确工具描述要告诉 Agent这个工具能做什么什么时候应该调用需要哪些必要参数有没有副作用有没有调用限制。例如修改一条已有闪念的内容、类型或关联事件。必须提供 thoughtId。这句话就明确告诉 Agent没有 thoughtId 时不应该直接调用该工具。3. 入参要偏业务语义不要偏页面状态前端表单可能包含很多字段id title content themeKey status sort createTime updateTime eventList uiState pageFlag但 MCP 工具不一定要暴露这么多。Agent 更适合使用偏业务语义的参数例如{thoughtId:123,content:新的闪念内容,events:[{content:新的关联事件}]}MCP 参数设计应该服务于 Agent 理解而不是照搬前端页面 DTO。4. MCP 方法里必须做校验例如thoughtId 不能为空 content 不能为空 不能修改别人的数据 不能覆盖 createTime 不能绕过权限 不能直接执行高风险操作。Agent 工具更要重视校验因为它不是用户手动点击页面表单而是由 Agent 根据自然语言自动触发。5. 业务逻辑要复用 Service不要在 MCP Tool Controller 里重新写一套保存逻辑。推荐方式是MCP Tool ↓ 转换参数 ↓ 调用 ThoughtService ↓ 返回结果这样可以避免前端保存逻辑一套 Agent 保存逻辑一套 两边行为不一致。十三、结合当前项目的后续扩展方向当前项目已经有这些 Agent 可调用能力thought_save time_record_queryByDateRange time_record_save完整调用链路是Agent / Trae / MCP Client ↓ http://localhost:45678/api/mcp ↓ MCP 根据工具名分发 ↓ Tool McpOperation 对应的方法 ↓ Controller / Service ↓ 数据库后续如果要让 Agent 支持更多操作可以继续把以下普通能力包装成 MCP 工具闪念查询 闪念修改 时间记录更新 待办新增 待办完成 消费记录新增 学习记录新增但对于删除、批量修改、状态覆盖等高风险操作需要谨慎设计最好加入确认机制或软删除机制。十四、总结普通接口包装成 Agent 可调用 MCP 工具本质上不是简单地“多加一个接口”而是把原来的后端能力升级成 Agent 能理解、能选择、能传参、能安全执行的工具。可以用一句话概括MCP Tool 是把后端业务能力暴露给 Agent 的标准化工具入口。普通 REST 接口解决的是前端页面怎么调用后端MCP Tool 解决的是Agent 怎么理解并调用后端能力在项目设计上推荐采用REST Controller给前端页面用 MCP Tool Controller给 Agent 用 Service复用真实业务逻辑这样既能保持原有前端接口稳定又能逐步把核心业务能力开放给 Agent 使用。最终项目就可以从传统的“页面驱动系统”逐步升级为“页面 Agent 双入口系统”用户可以在页面上操作 也可以直接对 Agent 说一句话 让 Agent 自动调用 MCP 工具完成任务这就是 MCP 在个人系统、人生管理系统、时间记录系统中的实际价值。