ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

数据库Mysql简单配置转换为MCP Server:从REST API到Higress的落地实践

数据库Mysql简单配置转换为MCP Server:从REST API到Higress的落地实践 1. 为什么要把 MySQL 和 REST API 改造成 MCP Server如果你最近在折腾 AI Agent大概率会遇到一个很现实的问题模型再聪明它也拿不到你数据库里的真实数据也调不动你手头那堆 REST API。传统做法是给每个接口写一个 Function Calling 函数接口一多维护成本直接爆炸。MCP Server 就是来解决这个问题的——它把「数据源」和「工具」用统一协议暴露给 Agent模型自己决定调哪个、传什么参数。这篇要聊的场景很具体你手上有一个 MySQL 数据库还有几个已经跑起来的 REST API想把它们快速变成 MCP Server让 Cline、Claude Code 这类 AI Agent 直接调用。核心工具是 Higress 网关它内置了数据库对接能力同时支持把任意 REST API 通过配置转成 MCP Server。整个过程不需要你写后端代码配置 验证就能跑通。适合谁看有 Docker 基础、想给 Agent 接真实数据源的后端同学正在做 AI 工具链、需要把内部 API 快速 MCP 化的开发者以及想搞明白 MCP Server 到底怎么落地、不想只看概念的人。下面我会从 Higress 部署开始一步步给出可复制的配置片段、路由规则和 curl 验证步骤最后用 Cline 实际调一次 MySQL 和 REST API把整条链路跑通。在开始之前先明确一个概念MCP Server 本质是一个遵循 Model Context Protocol 的服务端它对外暴露「工具列表」和「工具调用」两个能力。Agent 启动时会拉取工具列表用户提问时模型根据工具描述决定调用哪个工具、传什么参数MCP Server 执行后把结果返回给模型。Higress 在这里扮演的是「MCP 网关」角色它把 MySQL 和 REST API 包装成标准 MCP 工具同时处理 SSE 连接、Redis 缓存这些底层细节。2. 前置准备Higress 部署与 MCP Server 全局配置这一章是整条链路的地基配置错了后面全白搭。我实测下来最容易踩坑的地方是 Redis 地址和端口映射下面会重点标出来。2.1 用 Docker 部署 Higress all-in-one先创建一个工作目录所有配置都会映射到这个目录下持久化。注意后续操作过程中不要切换终端工作目录否则数据映射会出问题。mkdir higress cd higress docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest docker run -d --rm --name higress-ai \ -v ${PWD}:/data \ -e O11Yon \ -p 8001:8001 \ -p 8081:8080 \ -p 8443:8443 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one:latest这里我把容器内的 8080 映射到主机的 8081后面访问 MCP SSE 地址时要用 8081。8001 是控制台端口8443 是 HTTPS 端口。2.2 部署 RedisMCP SSE 依赖MCP Server 的 SSE 功能需要 Redis 做数据缓存没有 Redis 的话 SSE 连接会不稳定甚至直接失败。如果你已经有现成的 Redis可以跳过这步直接在全局配置里填地址。docker run -d --rm --name higress-redis \ -p 6379:6379 \ higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/redis-stack-server:7.4.0-v32.3 开启 MCP Server 全局功能浏览器访问http://localhost:8001或http://你的机器IP:8001首次访问会要求设置控制台账号密码。登录后进入「系统设置」找到 MCP Server 全局参数配置填入下面这段 YAMLapiVersion: v1 data: higress: |- mcpServer: sse_path_suffix: /sse enable: true redis: address: 192.168.18.158:6379 username: password: db: 0 match_list: [] servers: []注意redis.address必须填主机 IP不要用127.0.0.1。因为 Higress 跑在容器里127.0.0.1指向的是容器自身连不到宿主机上的 Redis。我一开始就是这里填错SSE 一直连不上排查了半天。sse_path_suffix是 SSE 连接的路径后缀默认/sse后面 MCP 工具的 URL 会以它结尾。enable: true是总开关别忘了。2.4 关于 TaoToken 的接入位置如果你后续想让 Agent 调用模型时走统一入口可以在 TaoToken 控制台创建 API Key然后在 Cline 或 Claude Code 里把 Base URL 指向https://taotoken.net/api模型 ID 按你实际用的填。这一步不是 MCP Server 本身的必需项但如果你想让整条链路模型 MCP 工具都走一个可控入口可以顺手配上。API Key 在控制台的 API Keys 页面创建接入文档里有各客户端的详细配置方式。3. 可复制配置MySQL 转 MCP Server 完整片段这一章是核心我会给出 MySQL 转 MCP Server 的完整配置以及 REST API 转 MCP Server 的 YAML 片段。所有配置都可以直接复制改一下 IP 和数据库连接信息就能用。3.1 MySQL 转 MCP Server 配置进入控制台「AI 网关管理」→「MCP 管理」→「创建 MCP 服务」服务类型选DB填入你的 MySQL 连接信息{ mcpServers: { db: { url: http://192.168.18.158:8081/mcp-servers/db/sse } } }创建完成后在 MCP 管理列表点击「详情」切换到「工具视图」就能看到 SSE 连接信息。同时去「全局配置」里确认一下MySQL 的连接信息应该已经自动写进去了。这里有个细节Higress 内置的 DB 对接能力会自动把 MySQL 的表结构解析成 MCP 工具也就是说你不需要手写每个查询的 SQL模型会根据表结构自己生成查询语句。实测下来对于简单的单表查询和聚合准确率还不错复杂多表 JOIN 建议还是自己封装成 REST API 再转 MCP。3.2 REST API 转 MCP Server 配置REST API 的转换分两步先加服务来源再配 MCP 工具。第一步在「服务来源」里添加目标 REST API。本示例用公网服务randomuser.me你也可以换成自己开发的服务。添加完成后服务列表会多一条记录。第二步在「MCP 管理」→「创建 MCP 服务」服务类型选OpenAPI选择上面配置的后端服务。创建后点击「详情」→「工具视图」→「编辑工具」切到 YAML 模式填入server: name: random-user-server tools: - description: Get random user information name: get-user requestTemplate: method: GET url: https://randomuser.me/api/ responseTemplate: body: |- {{- with (index .results 0) }} - **Name**: {{.name.first}} {{.name.last}} - **Email**: {{.email}} - **Location**: {{.location.city}}, {{.location.country}} - **Phone**: {{.phone}} {{- end }}这段配置的意思是定义一个叫get-user的工具请求方式是 GET目标是randomuser.me/api/返回结果用模板格式化后给模型。responseTemplate里的 Go template 语法可以让你控制返回给模型的数据结构避免把整个原始 JSON 塞进去浪费 token。对应的 MCP 客户端配置{ mcpServers: { test: { url: http://192.168.18.158:8081/mcp-servers/test/sse } } }注意如果mcp-servers的匹配规则没有添加用 Cline 调用时会报 405。这个坑我在第 5 章会详细说。3.3 三件套对照表不管你是接 MySQL 还是 REST APIMCP 客户端配置都离不开这三样配置项MySQL 示例REST API 示例Base URLhttp://192.168.18.158:8081/mcp-servers/db/ssehttp://192.168.18.158:8081/mcp-servers/test/sseKey无需额外 Key网关内部鉴权无需额外 KeyModel ID由 Agent 侧配置如 qwen3-max由 Agent 侧配置如果你用的是 TaoToken 统一入口Base URL 填https://taotoken.net/apiKey 填控制台创建的 API KeyModel ID 按实际模型填。MCP Server 的 URL 还是指向 Higress 网关。4. 验证请求用 Cline 实际调用 MySQL 和 REST API配置写完不算完得实际调一次才算跑通。这一章我用 VS Code 插件 Cline 来验证模型用阿里的千问 qwen3-max。4.1 Cline 配置 MCP Server在 Cline 的 MCP 配置里填入 MySQL 的 SSE 地址{ mcpServers: { db_higress_mcp: { type: sse, url: http://192.168.18.158:8081/mcp-servers/db/sse } } }保存后 Cline 会自动连接连接成功后你能在工具列表里看到 Higress 暴露出来的 MySQL 工具。4.2 调用 MySQL MCP 工具给 Cline 提问比如「帮我查一下 users 表里有多少条数据」。Cline 会把 MCP 工具信息作为提示词喂给模型模型分析后返回需要调用的工具和参数然后 Cline 调用 MCP 工具操作 MySQL拿到查询结果后再丢给模型丰富内容输出。我实测的数据库里有 31 条数据模型返回的结果和实际条数一致。这说明整条链路是通的Cline → Higress MCP Server → MySQL → 返回结果 → 模型 → 用户。4.3 调用 REST API MCP 工具同样在 Cline 里配置 REST API 的 SSE 地址{ mcpServers: { test_higress_mcp: { type: sse, url: http://192.168.18.158:8081/mcp-servers/test/sse } } }提问「帮我获取一个随机用户信息」模型会调用get-user工具拿到randomuser.me的返回数据按responseTemplate格式化后输出。你能看到姓名、邮箱、地址、电话这些字段被整齐地列出来。4.4 用 curl 直接验证 SSE 连接如果你不想装 Cline也可以用 curl 直接验证 MCP Server 是否正常curl -N http://192.168.18.158:8081/mcp-servers/db/sse正常的话会返回 SSE 事件流包含endpoint事件和工具列表。如果返回 404 或 405说明路由规则或匹配规则有问题看下一章。5. 本篇常见错排查401、405、SSE 连不上怎么办这一章我把实际踩过的坑列出来对照报错找原因基本能覆盖 90% 的问题。5.1 报 405 Method Not Allowed这是最常见的错误。原因通常是mcp-servers的匹配规则没有添加。Higress 需要知道哪些路径要走 MCP Server 处理如果全局配置里的match_list是空的请求就匹配不到 MCP 路由返回 405。解决办法去「系统设置」→ MCP Server 全局配置确认match_list里包含了/mcp-servers/前缀。或者直接在 MCP 管理里重新保存一次服务让 Higress 自动生成匹配规则。5.2 报 401 Unauthorized401 一般是鉴权问题。如果你在 Higress 控制台开启了登录鉴权MCP 请求也需要带上凭证。检查两点一是 MCP 客户端配置里有没有漏掉必要的 header二是 Higress 的鉴权开关是不是开得太严把 MCP 路径也拦了。如果你用的是 TaoToken 的 API Key确认 Key 没有过期且 Base URL 填的是https://taotoken.net/api而不是带 UTM 的官网地址。5.3 SSE 连接超时或 local proxy failedlocal proxy failed这个报错通常和 Redis 有关。MCP SSE 依赖 Redis 做缓存如果 Redis 地址填错比如填了127.0.0.1而不是主机 IP或者 Redis 容器没起来SSE 连接就会失败。排查步骤先docker ps确认higress-redis容器在运行然后redis-cli -h 192.168.18.158 -p 6379 ping看能不能通最后检查全局配置里的redis.address是不是主机 IP。5.4 报 reading choices 或模型返回空reading choices这类报错一般是模型侧的问题不是 MCP Server 的问题。可能是模型 ID 填错、API Key 无效或者模型不支持 Function Calling。确认你用的模型比如 qwen3-max支持工具调用且 Agent 侧配置的 Base URL 和 Key 正确。5.5 OAuth 相关报错如果你接的是需要 OAuth 的 MCP Server报错通常和 token 获取有关。Higress 本身不处理 OAuth需要你在服务来源里配置好鉴权信息。检查服务来源的认证配置确认 token 没有过期。5.6 端口映射错误我一开始把容器 8080 映射到主机 8081但配置里还是写的 8080结果一直连不上。确认你的 MCP URL 端口和docker run里的-p映射一致。-p 8081:8080意味着外部访问用 8081。6. 长期编码与 Agent 场景的接入建议如果你只是临时验证上面的配置够用了。但如果你要把 MCP Server 用在长期编码或 Agent 工作流里有几个点值得注意。第一MySQL 转 MCP Server 适合读多写少的场景。Higress 内置的 DB 能力会自动解析表结构模型生成的查询语句对简单查询够用但涉及写操作INSERT/UPDATE/DELETE建议还是封装成受控的 REST API 再转 MCP避免模型误操作。第二REST API 转 MCP Server 的关键在responseTemplate。原始 API 返回的 JSON 往往字段很多直接塞给模型会浪费大量 token。用 Go template 把关键字段提取出来模型理解起来更准成本也更低。第三如果你有多个 MCP Server 要管理建议统一走 TaoToken 的 Coding Plan 或 API 入口把模型调用和 MCP 工具调用都收敛到一个可控的网关后面。这样排查问题的时候链路清晰也方便做用量统计。第四SSE 连接在生产环境建议加心跳和重连机制。Higress 的 SSE 实现已经比较稳定但网络抖动时客户端还是要能自动重连。Cline 和 Claude Code 都支持自动重连配置里不用额外写。最后说个实际经验MCP Server 的工具描述description写得好不好直接决定模型调用的准确率。描述里把工具能做什么、参数含义、返回什么写清楚模型选错工具的概率会大幅下降。这个比调模型参数管用得多。如果你还没创建 TaoToken 的 API Key可以去控制台的 API Keys 页面建一个接入文档里有 Cline、Claude Code 等客户端的详细配置步骤。模型对话页面可以直接测试模型连通性确认 Base URL 和 Key 没问题之后再接到 Agent 里。
返回列表