1. 金融数据问答为什么总卡在“最后一公里”做金融数据类 Agent 的朋友大概率都遇到过这个场景用户问“帮我查一下最近三个交易日沪深300成分股里涨幅超过5%的标的”模型能理解意图但真正落到数据库查询时就开始掉链子——要么 SQL 写错字段名要么把trade_date和report_date搞混要么干脆编造一个不存在的表。问题的根子不在模型能力而在于 Agent 缺少一个稳定的“手”去触碰真实的结构化数据。Dify 的 SQLAgent 思路正好补上这一环用工作流把自然语言转成 SQL再通过一个受控的服务接口去执行查询最后把结果回传给模型做分析。而 MCPModel Control Protocol在这里扮演的是“工具总线”的角色让 Dify 的 Agent 能以标准化方式调用外部数据库服务而不是把数据库连接串硬编码在提示词里。这套组合适合谁适合手里有行情、财报、持仓等结构化数据、想让业务人员用自然语言直接问数的开发者也适合正在用 Cursor 写代码、希望顺手就能查库验证逻辑的工程师。我试过把这套链路拆成三段来搭FastAPI 做 SQL 执行层、Dify 工作流做 NL2SQL 编排、MCP Server 做工具暴露。下面按可复制的顺序把配置骨架给出来重点放在 MCP 服务声明、Dify 工具节点参数和 config.toml 这三块最后跑一次从提问到结果返回的验证。2. TaoToken 前置先把模型调用通道理清楚在搭 SQLAgent 之前得先确认模型调用这条路是通的。Dify 工作流里的 LLM 节点需要调用大模型来完成关键词提取和 SQL 生成如果你用的是本地模型或者自建网关这一步可以跳过但如果想快速跑通、不想在模型部署上耗时间可以用 TaoToken 这类聚合通道来统一管理模型调用。TaoToken 的定位是给开发者提供一个兼容 OpenAI 接口规范的模型调用入口你可以在控制台里创建 API Key然后在 Dify 的模型供应商配置里填入对应的 Base URL 和 Key。这样 Dify 的 LLM 节点就能直接选用你配置的模型不用改代码。具体操作路径先到控制台创建一个 API Key然后进入接入文档确认接口格式把 Base URL 填成https://taotoken.net/apiKey 填你刚创建的那串。Dify 里配置模型供应商时选“OpenAI-API-compatible”类型把这两项填进去即可。如果你后面要长期跑编码类 Agent可以看看 Coding Plan 的额度方案如果只是验证模型对话效果模型对话页面可以直接试。注意TaoToken 的 API 地址不带 UTM 参数直接写https://taotoken.net/api就行别把营销参数混进代码里。这一步做完Dify 里就有了可用的 LLM接下来才能让工作流里的“关键词提取”和“SQL 生成”两个节点跑起来。3. 可复制配置MCP 服务声明 Dify 工具节点 config.toml3.1 MCP 服务声明怎么写MCP Server 的核心作用是把 Dify 的 Agent API 包装成一个标准工具让 Cursor 或其他 MCP 客户端能直接调用。项目里的dify_agent_server.py就是干这个的你需要关注两个环境变量DIFY_API_KEY和DIFY_API_URL。# dify_agent_server.py 关键配置段 import os from mcp.server import Server from mcp.server.stdio import stdio_server DIFY_API_KEY os.getenv(DIFY_API_KEY, app-xxxxxxxxxxxxxxxx) DIFY_API_URL os.getenv(DIFY_API_URL, https://你的dify域名/v1/chat-messages) server Server(dify-sql-agent) server.tool() async def query_financial_data(question: str) - str: 接收自然语言问题调用 Dify 工作流返回 SQL 查询结果 import httpx async with httpx.AsyncClient(timeout60) as client: resp await client.post( DIFY_API_URL, headers{ Authorization: fBearer {DIFY_API_KEY}, Content-Type: application/json }, json{ inputs: {}, query: question, response_mode: blocking, user: mcp-client } ) data resp.json() return data.get(answer, 查询无返回)这段代码里server.tool()装饰器把query_financial_data注册成一个 MCP 工具入参是自然语言问题出参是 Dify 工作流返回的答案。response_mode用blocking是为了让调用方同步拿到结果适合查询类场景。3.2 Dify 工具节点参数怎么填在 Dify 工作流里你需要加一个“工具”节点来调用上面这个 MCP 服务。工具节点的配置分三块第一块是工具类型选“自定义工具”或“MCP 工具”取决于你的 Dify 版本。第二块是入参映射把工作流上游 LLM 节点输出的 SQL 语句或者自然语言问题映射到工具的question参数上。第三块是出参处理把工具返回的answer字段接到下游的“结束”节点或者再送进 LLM 做分析。# Dify 工具节点参数示意在 UI 里对应填写 tool_name: query_financial_data input_mapping: question: {{#llm_node.text#}} output_mapping: result: {{#tool_node.answer#}} timeout: 60 retry: 1这里的关键是input_mapping的变量引用要写对Dify 里用{{#节点ID.字段#}}的语法。如果你上游是 LLM 节点生成的 SQL那question传的其实是 SQL 语句这时候 MCP 服务那边要能识别并直接执行如果传的是自然语言那 Dify 工作流里得先有一个 NL2SQL 的 LLM 节点。3.3 config.toml 骨架MCP 客户端比如 Cursor需要一个配置文件来知道去哪里启动这个 Server。在 Cursor 的mcp.json或者通用 MCP 客户端的config.toml里写法如下# config.toml — MCP 客户端配置骨架 [mcp_servers.dify_sql_agent] command python args [/path/to/dify-mcp/dify_agent_server.py] env { DIFY_API_KEY app-xxxxxxxxxxxxxxxx, DIFY_API_URL https://你的dify域名/v1/chat-messages }如果你用的是 Cursor路径通常在C:\Users\{你的用户名}\.cursor\mcp.json格式是 JSON 而不是 TOML但字段含义一样command指定解释器args指定脚本路径env注入环境变量。配好之后重启 Cursor在 MCP 面板里应该能看到dify_sql_agent这个服务处于运行状态。注意DIFY_API_KEY不要硬编码在脚本里提交到 Git用环境变量或者.env文件管理.env记得加进.gitignore。4. 验证请求从自然语言到 SQL 结果返回配置写完得跑一次完整链路确认能通。验证分两步先确认 FastAPI 的 SQL 执行层没问题再确认 Dify 工作流 MCP 的端到端链路能返回结果。4.1 先验 FastAPI 的 SQL 查询服务进入fastapi-sqlapi目录装依赖、起服务pip install -r requirements.txt uvicorn app.main:app --reload --host 0.0.0.0 --port 8000然后跑客户端测试脚本python client.py如果client.py里配的是一条简单的SELECT语句比如查某张行情表的前几行你应该能在终端看到返回的 JSON 数据。这一步通了说明数据库连接串、表结构、查询接口都没问题。4.2 再验 Dify MCP 端到端在 Cursor 里打开 MCP 面板确认dify_sql_agent服务已连接。然后在对话里输入一个自然语言问题比如“查一下最近5个交易日成交额最大的3只股票”。MCP 客户端会把这个问题通过query_financial_data工具发给 DifyDify 工作流里的 LLM 节点提取关键词、生成 SQLCode 节点调用 FastAPI 执行查询最后把结果回传。# 也可以用测试脚本直接验 Dify API python test_agent_dify.py这个脚本会直接调 Dify 的 chat-messages 接口绕过 MCP 层适合排查是 Dify 工作流的问题还是 MCP 封装的问题。如果脚本能返回结果但 Cursor 里不行那问题多半在 MCP 配置或环境变量上。实测下来一次成功的返回应该包含三部分生成的 SQL 语句、查询结果数据、以及 LLM 对结果的简要分析。如果只返回了 SQL 没有数据检查 FastAPI 服务是否在跑如果返回了数据但格式乱检查 Dify 结束节点的输出变量映射。5. 本篇常见错排查5.1 MCP 服务启动失败command 路径不对最常见的报错是 Cursor 里 MCP 面板显示服务离线日志里提示spawn python ENOENT或者No such file or directory。这通常是command字段写的是python但系统 PATH 里找不到或者args里的脚本路径是相对路径。解决办法command写 Python 解释器的绝对路径args写脚本的绝对路径。Windows 上路径用双反斜杠或者正斜杠。5.2 Dify API 返回 401Key 无效或没带 Bearer如果test_agent_dify.py报 401先检查DIFY_API_KEY是不是复制完整了有没有多余空格。Dify 的 API Key 格式通常是app-开头的一长串。另外确认请求头里Authorization的值是Bearer {key}少了Bearer前缀也会 401。5.3 SQL 执行报错字段名或表名对不上金融数据库的表结构往往比较复杂LLM 生成的 SQL 里字段名可能和实际不一致。排查方法先在 FastAPI 的client.py里手动跑一条已知正确的 SQL确认表名和字段名然后在 Dify 的 RAG 知识库里把表结构说明补全包括库名、表名、字段名、字段类型、字段注释。知识库越详细LLM 生成的 SQL 越准。5.4 查询超时数据量太大或没加 LIMIT金融行情数据动辄几百万行如果 LLM 生成的 SQL 没有加LIMIT查询可能跑很久然后超时。解决办法有两个一是在系统提示词里明确要求“生成的 SQL 必须带 LIMIT 100”二是在 FastAPI 层加一个查询超时和行数上限的保护。5.5 MCP 工具调用返回空response_mode 不对如果 MCP 工具返回的answer是空的检查 Dify 工作流的response_mode是不是blocking。如果是streamingMCP 这边的同步 HTTP 请求拿不到完整结果。另外确认 Dify 工作流的“结束”节点有输出变量且变量名和 MCP 脚本里取的一致。6. 把链路跑通之后下一步做什么配置跑通只是起点。接下来你可以做三件事第一把 Dify 工作流里的 LLM 节点换成更适合 SQL 生成的模型通过 TaoToken 的模型对话页面先对比几个模型在 NL2SQL 任务上的表现再决定用哪个第二把 MCP 服务扩展到多个工具比如除了查询还加一个“导出 CSV”的工具让 Agent 的能力更完整第三如果这套 Agent 要长期跑在编码或数据分析场景里可以看看 Coding Plan 的额度方案避免频繁手动换 Key。接入文档里有完整的接口说明和示例API Keys 页面可以管理你的调用凭证。整套链路的核心思路就一句话让模型负责理解意图让 MCP 负责标准化调用让 FastAPI 负责安全执行 SQL。三者各司其职金融数据的自然语言查询就能稳定跑起来。
Dify_SQLAgent 实战：用 MCP 打通金融数据库的 Agent 配置骨架
1. 金融数据问答为什么总卡在“最后一公里”做金融数据类 Agent 的朋友大概率都遇到过这个场景用户问“帮我查一下最近三个交易日沪深300成分股里涨幅超过5%的标的”模型能理解意图但真正落到数据库查询时就开始掉链子——要么 SQL 写错字段名要么把trade_date和report_date搞混要么干脆编造一个不存在的表。问题的根子不在模型能力而在于 Agent 缺少一个稳定的“手”去触碰真实的结构化数据。Dify 的 SQLAgent 思路正好补上这一环用工作流把自然语言转成 SQL再通过一个受控的服务接口去执行查询最后把结果回传给模型做分析。而 MCPModel Control Protocol在这里扮演的是“工具总线”的角色让 Dify 的 Agent 能以标准化方式调用外部数据库服务而不是把数据库连接串硬编码在提示词里。这套组合适合谁适合手里有行情、财报、持仓等结构化数据、想让业务人员用自然语言直接问数的开发者也适合正在用 Cursor 写代码、希望顺手就能查库验证逻辑的工程师。我试过把这套链路拆成三段来搭FastAPI 做 SQL 执行层、Dify 工作流做 NL2SQL 编排、MCP Server 做工具暴露。下面按可复制的顺序把配置骨架给出来重点放在 MCP 服务声明、Dify 工具节点参数和 config.toml 这三块最后跑一次从提问到结果返回的验证。2. TaoToken 前置先把模型调用通道理清楚在搭 SQLAgent 之前得先确认模型调用这条路是通的。Dify 工作流里的 LLM 节点需要调用大模型来完成关键词提取和 SQL 生成如果你用的是本地模型或者自建网关这一步可以跳过但如果想快速跑通、不想在模型部署上耗时间可以用 TaoToken 这类聚合通道来统一管理模型调用。TaoToken 的定位是给开发者提供一个兼容 OpenAI 接口规范的模型调用入口你可以在控制台里创建 API Key然后在 Dify 的模型供应商配置里填入对应的 Base URL 和 Key。这样 Dify 的 LLM 节点就能直接选用你配置的模型不用改代码。具体操作路径先到控制台创建一个 API Key然后进入接入文档确认接口格式把 Base URL 填成https://taotoken.net/apiKey 填你刚创建的那串。Dify 里配置模型供应商时选“OpenAI-API-compatible”类型把这两项填进去即可。如果你后面要长期跑编码类 Agent可以看看 Coding Plan 的额度方案如果只是验证模型对话效果模型对话页面可以直接试。注意TaoToken 的 API 地址不带 UTM 参数直接写https://taotoken.net/api就行别把营销参数混进代码里。这一步做完Dify 里就有了可用的 LLM接下来才能让工作流里的“关键词提取”和“SQL 生成”两个节点跑起来。3. 可复制配置MCP 服务声明 Dify 工具节点 config.toml3.1 MCP 服务声明怎么写MCP Server 的核心作用是把 Dify 的 Agent API 包装成一个标准工具让 Cursor 或其他 MCP 客户端能直接调用。项目里的dify_agent_server.py就是干这个的你需要关注两个环境变量DIFY_API_KEY和DIFY_API_URL。# dify_agent_server.py 关键配置段 import os from mcp.server import Server from mcp.server.stdio import stdio_server DIFY_API_KEY os.getenv(DIFY_API_KEY, app-xxxxxxxxxxxxxxxx) DIFY_API_URL os.getenv(DIFY_API_URL, https://你的dify域名/v1/chat-messages) server Server(dify-sql-agent) server.tool() async def query_financial_data(question: str) - str: 接收自然语言问题调用 Dify 工作流返回 SQL 查询结果 import httpx async with httpx.AsyncClient(timeout60) as client: resp await client.post( DIFY_API_URL, headers{ Authorization: fBearer {DIFY_API_KEY}, Content-Type: application/json }, json{ inputs: {}, query: question, response_mode: blocking, user: mcp-client } ) data resp.json() return data.get(answer, 查询无返回)这段代码里server.tool()装饰器把query_financial_data注册成一个 MCP 工具入参是自然语言问题出参是 Dify 工作流返回的答案。response_mode用blocking是为了让调用方同步拿到结果适合查询类场景。3.2 Dify 工具节点参数怎么填在 Dify 工作流里你需要加一个“工具”节点来调用上面这个 MCP 服务。工具节点的配置分三块第一块是工具类型选“自定义工具”或“MCP 工具”取决于你的 Dify 版本。第二块是入参映射把工作流上游 LLM 节点输出的 SQL 语句或者自然语言问题映射到工具的question参数上。第三块是出参处理把工具返回的answer字段接到下游的“结束”节点或者再送进 LLM 做分析。# Dify 工具节点参数示意在 UI 里对应填写 tool_name: query_financial_data input_mapping: question: {{#llm_node.text#}} output_mapping: result: {{#tool_node.answer#}} timeout: 60 retry: 1这里的关键是input_mapping的变量引用要写对Dify 里用{{#节点ID.字段#}}的语法。如果你上游是 LLM 节点生成的 SQL那question传的其实是 SQL 语句这时候 MCP 服务那边要能识别并直接执行如果传的是自然语言那 Dify 工作流里得先有一个 NL2SQL 的 LLM 节点。3.3 config.toml 骨架MCP 客户端比如 Cursor需要一个配置文件来知道去哪里启动这个 Server。在 Cursor 的mcp.json或者通用 MCP 客户端的config.toml里写法如下# config.toml — MCP 客户端配置骨架 [mcp_servers.dify_sql_agent] command python args [/path/to/dify-mcp/dify_agent_server.py] env { DIFY_API_KEY app-xxxxxxxxxxxxxxxx, DIFY_API_URL https://你的dify域名/v1/chat-messages }如果你用的是 Cursor路径通常在C:\Users\{你的用户名}\.cursor\mcp.json格式是 JSON 而不是 TOML但字段含义一样command指定解释器args指定脚本路径env注入环境变量。配好之后重启 Cursor在 MCP 面板里应该能看到dify_sql_agent这个服务处于运行状态。注意DIFY_API_KEY不要硬编码在脚本里提交到 Git用环境变量或者.env文件管理.env记得加进.gitignore。4. 验证请求从自然语言到 SQL 结果返回配置写完得跑一次完整链路确认能通。验证分两步先确认 FastAPI 的 SQL 执行层没问题再确认 Dify 工作流 MCP 的端到端链路能返回结果。4.1 先验 FastAPI 的 SQL 查询服务进入fastapi-sqlapi目录装依赖、起服务pip install -r requirements.txt uvicorn app.main:app --reload --host 0.0.0.0 --port 8000然后跑客户端测试脚本python client.py如果client.py里配的是一条简单的SELECT语句比如查某张行情表的前几行你应该能在终端看到返回的 JSON 数据。这一步通了说明数据库连接串、表结构、查询接口都没问题。4.2 再验 Dify MCP 端到端在 Cursor 里打开 MCP 面板确认dify_sql_agent服务已连接。然后在对话里输入一个自然语言问题比如“查一下最近5个交易日成交额最大的3只股票”。MCP 客户端会把这个问题通过query_financial_data工具发给 DifyDify 工作流里的 LLM 节点提取关键词、生成 SQLCode 节点调用 FastAPI 执行查询最后把结果回传。# 也可以用测试脚本直接验 Dify API python test_agent_dify.py这个脚本会直接调 Dify 的 chat-messages 接口绕过 MCP 层适合排查是 Dify 工作流的问题还是 MCP 封装的问题。如果脚本能返回结果但 Cursor 里不行那问题多半在 MCP 配置或环境变量上。实测下来一次成功的返回应该包含三部分生成的 SQL 语句、查询结果数据、以及 LLM 对结果的简要分析。如果只返回了 SQL 没有数据检查 FastAPI 服务是否在跑如果返回了数据但格式乱检查 Dify 结束节点的输出变量映射。5. 本篇常见错排查5.1 MCP 服务启动失败command 路径不对最常见的报错是 Cursor 里 MCP 面板显示服务离线日志里提示spawn python ENOENT或者No such file or directory。这通常是command字段写的是python但系统 PATH 里找不到或者args里的脚本路径是相对路径。解决办法command写 Python 解释器的绝对路径args写脚本的绝对路径。Windows 上路径用双反斜杠或者正斜杠。5.2 Dify API 返回 401Key 无效或没带 Bearer如果test_agent_dify.py报 401先检查DIFY_API_KEY是不是复制完整了有没有多余空格。Dify 的 API Key 格式通常是app-开头的一长串。另外确认请求头里Authorization的值是Bearer {key}少了Bearer前缀也会 401。5.3 SQL 执行报错字段名或表名对不上金融数据库的表结构往往比较复杂LLM 生成的 SQL 里字段名可能和实际不一致。排查方法先在 FastAPI 的client.py里手动跑一条已知正确的 SQL确认表名和字段名然后在 Dify 的 RAG 知识库里把表结构说明补全包括库名、表名、字段名、字段类型、字段注释。知识库越详细LLM 生成的 SQL 越准。5.4 查询超时数据量太大或没加 LIMIT金融行情数据动辄几百万行如果 LLM 生成的 SQL 没有加LIMIT查询可能跑很久然后超时。解决办法有两个一是在系统提示词里明确要求“生成的 SQL 必须带 LIMIT 100”二是在 FastAPI 层加一个查询超时和行数上限的保护。5.5 MCP 工具调用返回空response_mode 不对如果 MCP 工具返回的answer是空的检查 Dify 工作流的response_mode是不是blocking。如果是streamingMCP 这边的同步 HTTP 请求拿不到完整结果。另外确认 Dify 工作流的“结束”节点有输出变量且变量名和 MCP 脚本里取的一致。6. 把链路跑通之后下一步做什么配置跑通只是起点。接下来你可以做三件事第一把 Dify 工作流里的 LLM 节点换成更适合 SQL 生成的模型通过 TaoToken 的模型对话页面先对比几个模型在 NL2SQL 任务上的表现再决定用哪个第二把 MCP 服务扩展到多个工具比如除了查询还加一个“导出 CSV”的工具让 Agent 的能力更完整第三如果这套 Agent 要长期跑在编码或数据分析场景里可以看看 Coding Plan 的额度方案避免频繁手动换 Key。接入文档里有完整的接口说明和示例API Keys 页面可以管理你的调用凭证。整套链路的核心思路就一句话让模型负责理解意图让 MCP 负责标准化调用让 FastAPI 负责安全执行 SQL。三者各司其职金融数据的自然语言查询就能稳定跑起来。
