1. 为什么要在本地跑一个 MCP 服务给 Dify 用如果你正在用 Dify 搭智能体又想让智能体去查公司内部的业务系统、数据库或者某个老接口大概率会碰到一个尴尬Dify 自带的工具市场解决不了你的私有数据问题。这时候 MCPModel Context Protocol就是那个“通用插座”。它把外部工具和数据源抽象成标准接口模型只要按协议去“发现工具、调用工具”就行不用为每个 API 写一套定制胶水代码。我这次要落地的场景很具体用 Spring Boot 写一个本地 MCP 服务通过 SSEServer-Sent Events暴露出来然后让 Dify 的 Agent 节点去发现并调用它。为什么选 SSE 而不是 STDIO因为 STDIO 是进程内通信适合本地调试而 SSE 走 HTTPDify 跑在 Docker 里也能直接访问宿主机服务部署上更省心。Spring 生态里spring-ai-starter-mcp-server-webmvc这个 starter 已经把 SSE 端点封装好了你只需要写业务方法、加注解、注册 ToolCallbackProvider 三步。这篇文章面向的是有 Spring 基础、想快速把私有能力接进 Dify 的开发者。我会给出可复制的服务端骨架、Dify 侧的 MCP 配置片段以及用 TaoToken 统一 Key 和 API 通道的settings.json示例。最后会做一次本地调用验证确认智能体能正常发现并调用 MCP 工具。整个过程不需要你改 Dify 源码也不需要把内部接口暴露到公网。2. TaoToken 前置统一 Key 与 API 通道怎么准备在写代码之前先把模型侧的通道理顺。Dify 里的 Agent 节点需要调用大模型而模型调用需要 API Key。如果你同时用多个模型比如 Qwen 做工具调用、Claude 做长文本推理每个厂商一套 Key、一套计费、一套限流管理起来很碎。TaoToken 在这里的角色是提供一个统一的 API 通道和 Key 管理入口让你在 Dify 和本地开发环境里用同一套凭证。具体操作上你先到 TaoToken 控制台创建一个 API Key。这个 Key 后面会用在两个地方一是 Dify 的模型供应商配置里二是本地settings.json里给编码工具或测试脚本用。创建入口在控制台的 API Keys 页面建议按项目命名比如dify-mcp-local方便后面排查是哪个环境在调用。拿到 Key 之后你需要确认两件事第一模型对话通道是否可用可以到模型对话页面发一条测试消息确认 Key 有权限第二如果你后面要用 Coding Plan 做长期编码或 Agent 任务可以提前了解套餐的调用额度避免调试到一半被限流。接入文档里有完整的端点说明和参数格式建议先扫一遍尤其是 base URL 和鉴权头的写法。注意TaoToken 的 API 地址是https://taotoken.net/api不要在后面拼多余的路径。鉴权头用标准的Authorization: Bearer 你的Key。官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end控制台和文档都可以从那里进。这一步看起来简单但实际踩坑最多。很多人 Key 创建了却忘了在 Dify 里重新授权或者本地settings.json里把 base URL 写成了带/v1的旧格式结果一直 401。先把通道跑通再写 MCP 服务顺序不要反。3. Spring SSE 服务端骨架从 pom 到 ToolCallbackProvider3.1 依赖与版本选择Spring AI 的 MCP Server Starter 目前对 Spring Boot 版本有要求。实测下来spring-boot-starter-parent用 3.2.5 比较稳3.4.x 在某些快照版本上会出现自动配置冲突。JDK 用 17Maven 用 3.9.x。核心依赖就两个spring-ai-starter-mcp-server-webmvc和spring-cloud-starter-openfeign如果你要调第三方 HTTP 接口。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version /parent dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version1.1.0-SNAPSHOT/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId /dependency dependency groupIdorg.springframework.cloud/groupId artifactIdspring-cloud-starter-openfeign/artifactId /dependency /dependencies仓库配置里需要加 Spring Milestones 和 Snapshots因为 1.1.0-SNAPSHOT 还没进中央仓库。如果你不想用快照版可以换成 1.0.0 的正式版但部分Tool注解的特性会少一些。3.2 写一个带 Tool 注解的业务服务新建一个BIService类用Service标注。每个要暴露给模型的方法加Tool注解description一定要写清楚“什么时候调用、参数是什么”。模型是靠这段描述来决定要不要调这个工具的描述含糊会导致该调不调、或者乱调。Service public class BIService { Tool(description 根据客户名称查询项目信息输入参数是客户名称customerName) public String getProjectInfoByCustomerName(String customerName) { return 系统查询客户 customerName 项目信息; } Tool(description 根据合同号查询项目信息输入参数是合同编号contractNum) public String getProjectInfoByContractNum(String contractNum) { System.out.println(getProjectInfoByContractNum start contractNum); return 装备守护api项目信息; } Tool(description 获取当前系统时间) public String getCurrentTime() { LocalDate currentDate LocalDate.now(); DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd); return currentDate.format(formatter); } }这里有个细节Tool的name不写就默认用方法名但同一个类里不能有两个同名工具。description里把参数名也带上模型解析参数时会更准。如果你要调第三方接口可以在方法里注入 FeignClient把返回的 Map 转成 JSON 字符串返回。3.3 注册 ToolCallbackProvider光有Tool注解还不够Spring 需要知道哪些对象里的工具要暴露出去。在启动类里加一个ToolCallbackProviderBeanSpringBootApplication EnableFeignClients(basePackages org.springframework.ai.mcp.sample.rest) public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } Bean public ToolCallbackProvider biTools(BIService biService) { return MethodToolCallbackProvider.builder() .toolObjects(biService) .build(); } }启动之后SSE 端点默认在/sse。你可以先在浏览器里访问http://localhost:8080/sse如果看到一串event: endpoint之类的流式输出说明服务端已经就绪。这一步是后面 Dify 配置的前提别跳过。4. Dify 侧 MCP 配置与 settings.json 统一 Key4.1 Dify 里安装 MCP 插件并配置 AgentDify 1.4.0 之后对 MCP 的支持已经比较完整。进入 Dify 控制台点右上角插件市场搜索 MCP安装官方那个“MCP SSE”插件。安装完在“设置-模型供应商”里确认你的大模型已经授权比如 Qwen 或 ClaudeKey 就用前面 TaoToken 控制台创建的那个。然后新建一个 ChatFlow 或 Agent 应用。在编排页面开始节点后面加一个 Agent 节点Agent 策略选ReAct(Support MCP Tools)。工具列表右侧点选择“发现和调用 MCP 工具”再点“获取 MCP 工具列表”的授权按钮填入{ bi-mcp-server: { url: http://你的宿主机IP:8080/sse, headers: {}, timeout: 60, sse_read_timeout: 300 } }注意 URL 最后必须带/sseIP 不能写localhost因为 Dify 跑在 Docker 容器里localhost指向的是容器自己。Windows 或 Mac 上用host.docker.internal也可以Linux 上直接用宿主机局域网 IP。4.2 settings.json 里统一 Key 的写法如果你本地还用 Claude Code 或其他编码工具做联调可以在settings.json里把 TaoToken 的通道配成统一入口。这样 Dify 和本地工具用的是同一套 Key排查问题时不用来回切换。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的TaoToken Key } }这个配置的作用是让本地工具走 TaoToken 的 API 通道而不是直连某个厂商。如果你用的是 Coding Plan 做长期 Agent 任务建议把 Key 单独放一个环境变量文件不要硬编码在settings.json里提交到 Git。提示Dify 里的模型 Key 和settings.json里的 Key 可以是同一个但建议在 TaoToken 控制台按用途建两个比如dify-prod和local-dev方便看调用量。5. 验证请求确认智能体发现并调用 MCP 工具配置完成后在 Dify 的 Agent 节点里写一段指令比如分析 {{#sys.query#}} 的内容 1、使用最合适的工具整理返回 2、能从记忆里获取到的数据优先从记忆获取如果记忆里没有再调工具获取 查询 {{#sys.query#}} 最大迭代数 5然后在预览窗口输入“帮我查一下合同号 HT-2024-001 的项目信息”。如果一切正常你会看到 Agent 的思考过程里出现“调用 getProjectInfoByContractNum”这样的步骤最终回复里包含“装备守护api项目信息”。同时你本地 Spring 服务的控制台会打印getProjectInfoByContractNum startHT-2024-001说明请求真的打到了你的 MCP 服务。如果模型没有调用工具先检查三件事Agent 策略是不是ReAct(Support MCP Tools)工具列表里有没有成功加载出bi-mcp-server下的工具Tool的 description 是不是写得太模糊。实测下来description 里带上参数示例调用成功率会明显提高。6. 本篇常见错排查第一个坑Dify 里填了 localhost。这是最高频的问题。Dify 在 Docker 里localhost:8080是容器内部的 8080不是你的宿主机。改成宿主机 IP 或host.docker.internal并且确认防火墙放行了 8080。第二个坑SSE 连接超时。如果 Dify 报sse_read_timeout相关错误把配置里的sse_read_timeout从默认值调到 300 秒。MCP 的 SSE 是长连接工具调用过程中如果模型思考时间较长短超时会直接断流。第三个坑ToolCallbackProvider 没注册。表现是 SSE 端点能连上但工具列表是空的。检查启动类里有没有MethodToolCallbackProvider.builder().toolObjects(biService).build()这个 Bean以及BIService有没有加Service。第四个坑TaoToken Key 在 Dify 里没重新授权。如果你在 TaoToken 控制台轮换了 KeyDify 的模型供应商配置不会自动更新需要手动重新填一次。表现是模型调用返回 401但 MCP 服务本身是通的。第五个坑Spring Boot 版本冲突。用 3.4.x 配 1.1.0-SNAPSHOT 时可能出现McpServerAutoConfiguration找不到的情况。降回 3.2.5 或者把 Spring AI 换成正式版。这个坑我踩过日志里会报NoSuchBeanDefinitionException看起来像业务代码问题其实是版本不匹配。排障的时候先用浏览器直接访问http://IP:8080/sse确认服务端活着再用 Dify 的“获取 MCP 工具列表”按钮确认工具能发现最后才在对话里测调用。分层排查比一上来就改代码快得多。如果你在接入过程中遇到 Key 或通道问题可以到 TaoToken 的 API Keys 页面重新生成一个然后对照接入文档检查 base URL 和鉴权头。模型对话通道可以用模型对话页面单独验证长期编码或 Agent 任务建议走 Coding Plan避免调试期间额度不够。
