配好 tools.yaml：MCP Toolbox 配置实战与避坑

配好 tools.yaml：MCP Toolbox 配置实战与避坑

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

凌晨排查一个 AI Agent 连不上数据库的问题：日志里反复刷 connection refused，Agent 那边只回"无法访问数据"。最后发现不是数据库挂了，而是 tools.yaml 里端口写死了本地 3306，环境变量名和部署环境对不上。MCP Toolbox 把数据源连接、工具能力和工具集组合全部收敛在这一个 YAML 文件里，改对它就是解决问题的唯一入口。

先把厨房想明白：数据源、工具、工具集各管什么

把 MCP Toolbox 想成一家餐厅的后厨，三类配置就各归其位了。sources 是备菜区：每种食材（数据源）洗好备好放在那儿，Toolbox 启动时为每个数据源建好一条独立的连接池；tools 是菜品：具体做什么动作，执行 SQL、查表结构、看锁，每道菜指定用哪个备菜区；toolsets 是套餐：把几道菜组成一个逻辑单元，让不同 Agent 按角色各取所需。

MCP Toolbox 是一个开源的数据库 MCP 服务器，支持 MySQL、Postgres 到 BigQuery 等二十多种数据源，全部通过 tools.yaml 这一个文件声明，格式是带---分隔符的多文档 YAML。

逐层拆解：每块只记三样东西

下面按 sources → tools → toolsets 的顺序拆。每一块我都按"最小可跑片段 → 参数速查 → 一句易错提醒"来讲，看完三段就能照抄改造。

sources：5 行 YAML 连上 MySQL

先给数据源起个名字，写 5 行让它连上 MySQL：

kind: source name: mysql-source type: mysql host: ${MYSQL_HOST:localhost} port: ${MYSQL_PORT:3306} database: ${MYSQL_DATABASE} user: ${MYSQL_USER} password: ${MYSQL_PASSWORD}

值里支持环境变量替换：${变量名:默认值}，冒号后面给兜底值，冒号留空就是没有默认值。密码这类敏感信息永远走环境变量，别写死。

核心参数速查：

⚠️ 易错提醒：name是工具引用数据源的唯一句柄，type 里拼错一个字母，服务启动时就会直接报未知类型。

tools：让 AI 看懂你的工具描述

数据源连上了，接下来要告诉 Toolbox 拿它做什么。工具最小片段：

kind: tool name: execute_sql type: mysql-execute-sql source: mysql-source description: Use this tool to execute SQL.

type决定工具能力，命名规则是"数据源类型-能力"，比如mysql-execute-sql、mysql-list-tables、postgres-sql。除了这些内置类型，还可以自己写一条带占位符的 SQL：

kind: tool name: get_query_plan type: mysql-sql source: mysql-source statement: | EXPLAIN FORMAT=JSON {{.sql_statement}} templateParameters: - name: sql_statement type: string description: 要分析执行计划的 SQL 语句 required: true

注意占位符是 Go 模板写法{{.参数名}}，不是$1也不是?；templateParameters里的参数会直接替换进 SQL 文本，比预编译参数更易注入，文档建议尽量给allowedValues收紧取值范围。

参数速查（工具级）：

description 是 Agent 理解这个工具的唯一依据：写清什么时候该用、输入是什么、返回什么，模型才会选对工具；写得含糊，调用就会飘。required不写默认就是必填，想留空用required: false，千万别写default: null——YAML 里它等于没给默认值，参数依然是必填。

⚠️ 易错提醒：source填的是数据源的 name，不是 type；把mysql填进source是新手最常见的写法。

toolsets：把工具打包成职能套餐

工具集就是一张清单，零配置，把工具按职能装进篮子：

kind: toolset name: data_analyst_set tools: - execute_sql - list_tables - get_query_plan

速查：

客户端 SDK 可以load_toolset("data_analyst_set")按名加载，不传名字则默认加载全部工具。仓库文档现在建议迁移到kind: group（能挂描述、能和 prompts 组合），但 toolset 语法照常工作，老配置不用急着动。

⚠️ 易错提醒：tools 列表里每一项必须和上面 tools 的 name 一字不差，多一个空格都会导致启动时校验失败。

完整拼装：一份能跑的 MySQL tools.yaml

把三段拼起来，就是一个可以直接启动的完整配置：

kind: source name: mysql-source type: mysql host: ${MYSQL_HOST:localhost} port: ${MYSQL_PORT:3306} database: ${MYSQL_DATABASE} user: ${MYSQL_USER} password: ${MYSQL_PASSWORD} queryTimeout: 30s --- kind: tool name: execute_sql type: mysql-execute-sql source: mysql-source description: Use this tool to execute SQL. --- kind: tool name: list_tables type: mysql-list-tables source: mysql-source description: Lists detailed schema information as JSON for user-created tables. --- kind: toolset name: data_analyst_set tools: - execute_sql - list_tables

设好环境变量后执行toolbox serve。启动日志会依次打印数据源初始化完成、加载的工具数量；如果工具数和你定义的对不上，先怀疑---分隔符和缩进——YAML 用 tab 缩进会直接解析错。

故障速查：现象、根因、修复动作

收尾

一份 tools.yaml 只说三件事：连哪里（sources）、能做什么（tools）、按职能怎么分（toolsets），把这三件事写对，配置基本就稳了。仓库 internal/prebuiltconfigs/tools/ 里有 40 个预置 YAML 示例，从 MySQL 到 BigQuery 可以直接抄改造；遇到某个数据源参数拿不准，欢迎提 issue 交流。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox