配好 tools.yamlMCP 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 refusedAgent 那边只回无法访问数据。最后发现不是数据库挂了而是 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 的顺序拆。每一块我都按最小可跑片段 → 参数速查 → 一句易错提醒来讲看完三段就能照抄改造。sources5 行 YAML 连上 MySQL先给数据源起个名字写 5 行让它连上 MySQLkind: source name: mysql-source type: mysql host: ${MYSQL_HOST:localhost} port: ${MYSQL_PORT:3306} database: ${MYSQL_DATABASE} user: ${MYSQL_USER} password: ${MYSQL_PASSWORD}值里支持环境变量替换${变量名:默认值}冒号后面给兜底值冒号留空就是没有默认值。密码这类敏感信息永远走环境变量别写死。核心参数速查参数必填作用kind是固定写 source声明这是一段数据源配置name是数据源唯一名工具靠它引用这个源type是数据源类型决定要哪些连接参数如 mysql、postgres、cloud-sql-postgreshost / port / database / user / password视 type 定常规数据库的连接五件套托管型数据源换成 project、region、instancequeryParams否连接串附加查询参数queryTimeout否查询超时时间如 30s⚠️ 易错提醒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。除了这些内置类型还可以自己写一条带占位符的 SQLkind: tool name: get_query_plan type: mysql-sql source: mysql-source statement: | EXPLAIN FORMATJSON {{.sql_statement}} templateParameters: - name: sql_statement type: string description: 要分析执行计划的 SQL 语句 required: true注意占位符是 Go 模板写法{{.参数名}}不是$1也不是?templateParameters里的参数会直接替换进 SQL 文本比预编译参数更易注入文档建议尽量给allowedValues收紧取值范围。参数速查工具级参数必填作用name是工具唯一名toolset 和 SDK 都靠它引用type是内置能力名或 *-sql 类用于自定义语句source是指向哪个数据源必须是上面定义过的 namestatement视 type 定自定义 SQL 模板description强烈建议直接喂给 LLM 的工具说明写清用途、输入、边界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速查参数必填作用name是工具集唯一名给 Agent 或应用按名加载tools是成员工具名列表按行罗列description已废弃写上去会被丢弃并告警客户端 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 缩进会直接解析错。故障速查现象、根因、修复动作现象常见根因修复动作启动即报 connection refused 或连接挂起端口/环境变量名写错或数据库不在白名单网段核对 host、port、queryParams确认数据库监听正常且 Toolbox 所在网段可达启动报 source not found工具里 source 填的不是已定义的 name全文搜索 source 字段与 source 的 name 逐一比对调用被拒parameter ... is required参数默认必填Agent 少传了确认真必填就补齐说明想留空改required: falsedefault: null无效收尾一份 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考