第一次写数据库 MCP 的人常常卡在同一个地方:模型给出的 SQL 里表名是编的,或者明明是同一个库,换个会话就认不出来了。问题不在模型笨,而在于「表结构怎么进到上下文里」这一步没有设计好。这篇按调用链拆开讲:谁负责把表名送进去、送多少、什么时候送,最后给一份能照着搭的排查顺序。
第一次写数据库 MCP 的人常常卡在同一个地方:模型给出的 SQL 里表名是编的,或者明明接的是同一个库,换个会话它就认不出来了。问题不在模型笨,而在于「表结构怎么进到上下文里」这一步没设计好。模型不会自己去翻你的库,它能看到的只有你发进上下文的那段文本。
这篇按调用链拆开讲:谁负责把表名送进去、送多少、什么时候送,边界在哪里,最后给一份能照着搭的排查顺序。看完你应该能自己判断,手上这套 MCP Server 是「没给信息」还是「给了但给错了」。
先接受一个事实:模型天生看不见你的库
大模型对数据库是一个彻底的黑盒。它没有连接、没有元数据缓存,也不具备「猜一下这个库大概有什么表」的能力。所谓「模型知道有哪些表」,本质是 MCP Server 在某一刻把表结构查出来、拼进提示词,模型读到的只是这段文本的副本。
由此可以推出两个判断:信息准不准,取决于查询那一刻库里的真实状态;信息全不全,取决于你让它查了多少、有没有被截断。这两件事都不在模型手里,在你的服务端代码里。
- 表结构来源
- MCP Server 向数据库元数据表或 information_schema 发起的查询结果
- 上下文
- 本次请求真正发给模型的全部文本,只有落在这里的内容模型才「看得见」
- 注入时机
- 启动时一次性拼好,还是每次对话按需查,直接决定新加的表模型认不认
表结构进上下文的四条路,各适合什么场景
把这四条路摆在一起对比,主要看三个维度:token 开销、交互轮次、结构变更后的新鲜度。没有一条通吃,选错路最常见的症状是「简单库也要绕好几轮」或者「库一大上下文直接爆」。
| 做法 | 适合场景 | 主要代价 |
|---|---|---|
| 工具列表 | 表多、只查其中几张 | 模型要多调一轮,延迟增加 |
| 资源挂载 | 表少、结构稳定的小库 | 库一大就把上下文撑爆 |
| 预置提示词 | 核心表固定、内部报表库 | 改表要改提示词,容易忘记同步 |
| 混合 | 生产环境的多数情况 | 实现稍复杂,要维护两份信息 |
- 工具列表:注册 list_tables、describe_table 这类函数,模型需要时自己调,省 token 但多一轮往返
- 资源挂载:把库结构做成可读资源,客户端启动时注入,简单直观但库大了会撑爆上下文
- 预置提示词:在系统提示里写死核心表说明,适合表少、结构稳定的内部报表库
- 混合做法:系统提示里只给表名清单,字段细节留给工具按需查,是多数生产环境的选择
判断标准很简单:如果你的库超过几十张表、或者经常加字段,就别只走资源挂载这一条;如果是三张表的小工具库,挂上去最省事,不必为了架构好看上工具调用。
决定送多少:表多、字段多时怎么控
很多 MCP Server 的第一个版本是把所有表的全部字段一次性拼进提示词,跑通没问题,库一长就出事:上下文被无关的日志表占满,真正的业务表反而排在后面。做法是先分层,再给必送清单,最后主动排除噪音。
- 第一层只送表名每张表配一句话中文用途,先让模型能选对表;这一步的 token 成本最低,也最容易维护
- 第二层按需补字段模型点名要哪张表,再用工具查该表的字段清单;验证方式是看首版 SQL 用的字段是否都真实存在
- 必送字段单列主键、外键、时间字段、状态枚举这几类影响连表和过滤的字段,在第一层就带上,别等第二层
- 主动排除噪音日志表、临时表、备份表、大字段列不进默认清单;改完观察模型是否还会去连那些没人用的表
一个可操作的判断标准:改完之后,看模型第一版 SQL 的连表对不对。连错表比字段写错更常见,如果它还老是去连某张不相关的表,说明选表信息不够或噪音没清干净,回去调第一层。
光给表名字段名不够,把语义写进去
字段名是英文的,业务口径只有你知道。模型看到 status 这个字段,不知道它到底是 0/1、A/B 还是拼音缩写,只能猜,猜错的概率不低。把口径写成一句注释,效果往往远好于多给十列。
| 要补什么 | 写法示例方向 | 为什么重要 |
|---|---|---|
| 中文备注 | 一句话说明这个字段的业务含义 | 模型据此决定过滤还是展示 |
| 枚举值 | 把取值和含义对应写清楚 | 避免状态过滤条件写反 |
| 从属关系 | 标明是明细表还是快照表 | 决定连表方向,错方向结果就错 |
| 时间口径 | 说明是创建时间还是业务发生时间 | 报表类查询最容易踩的坑 |
什么情况下这条不适用:字段语义本来就稳定且命名规范,比如主键、创建时间、更新时间这类通用字段,再写注释收益很低,反而占位置。把力气花在业务字段和状态枚举上。
实时查还是缓存:一致性和延迟的取舍
实时查的好处是表结构一变立刻生效,代价是每次会话多一次数据库往返;缓存的好处是快且稳,代价是加字段、改字段名之后模型还按旧结构写 SQL,报错很隐蔽,经常查半天以为是模型的问题。
- 表名清单做缓存,并带上版本号,版本变了就清
- 字段细节实时查,因为它变化频繁、单次查询也便宜
- 改过表结构后行为没变,第一反应应该是缓存没失效,而不是模型变笨了
- 查元数据的连接也用只读账号,别拿业务主账号去跑结构查询
取舍标准看你的变更频率:一周改好几次表结构的活跃库,缓存窗口要短;几个月不动一次的老库,缓存长一点没坏处。这块没有统一定值,到 /tools/speed-test 对比一下各类工具和接口的响应表现,再定你的会话策略。
安全边界:表结构本身也是敏感信息
表名和字段名常常直接暴露业务模型,比如一张叫 user_payment_retry_log 的表,外人一看就知道你们在做什么。对外场景,比如给客户演示、接外部工具,要把表结构脱敏,或者只开放白名单视图。
- 最小权限:MCP Server 用的数据库账号只给只读,且只对允许的表授权,靠权限兜底比靠提示词约束可靠
- 白名单放在服务端:可查表清单写在代码配置里,不要指望模型自己守规矩
- 对外演示用视图:把真实表结构包一层视图再暴露,字段名也可以顺手改成中性的
- 什么情况下可以先放过:纯内部开发调测试库,脱敏成本高于收益,但上生产前必须补上
这块的判断标准是「谁能看到这段上下文」。只有内部开发者能看到,风险可控;一旦经过第三方客户端或外部工具,就该按对外接口的标准处理。
出问题按这个顺序排查
模型写错表名、字段对不上、连错表,这些症状看着像一类问题,其实原因分层。乱猜很浪费时间,按下面顺序走,基本能定位到具体某一环。
- 查连接先用工具或命令行直接跑一遍元数据查询,看 list_tables 是否能正常返回;返回空或报错,问题在连接和权限
- 查注入翻客户端日志里的请求体,确认工具定义和资源真的发给了模型;很多「模型不知道」其实是定义没注册上
- 查内容看返回的表清单有没有被截断,大库常见只拿到前几十张,后面的表模型永远看不到
- 查口径表能查到但模型连错、字段用错,回到语义注释和枚举值上补信息,别急着换模型
- 查缓存改过表结构后行为没变,先确认缓存是否失效、版本号是否更新
落地清单:搭完对照这几项
按上面几节搭完,拿这份清单过一遍。每一项都能对应到一个具体故障模式,不是走过场。
| 检查项 | 不合格时的典型症状 |
|---|---|
| 只读账号与白名单表已配置 | 模型能查到不该查的表,或元数据查询直接报权限错 |
| 默认注入表名清单,细节走工具 | 要么每次都要多轮问,要么上下文被塞满 |
| 核心表有中文口径与枚举值 | 状态过滤写反、连表方向错 |
| 表结构变更有清缓存或版本机制 | 加了字段,模型还按旧结构写 SQL |
| 新表同步进入注入清单的流程已定 | 新表上线后模型始终不知道它存在 |
最后一条最容易被忽略,却最值得写进文档:模型看不到没给它的东西。加新表不在「上线数据库」这一步结束,还要同步更新注入清单,否则下次会话模型照样当它不存在。
下一步服务端搭稳了,选哪家接口、走官方还是中转、各家的实时价格怎么变,这些到 /sites 和 /price-watch 看当时的数字再决定;先把自己这边的表结构注入做对,换接口才不会白折腾。→常见问题
模型老是把表名写错,是不是该换个更大的模型?
先别换。多数情况是表结构没进上下文,或者只进了几十张表的名字。检查 MCP Server 是否真的把表清单返回给客户端、是否被截断。信息补齐后,中小模型连表也基本能对。
表特别多,几百张,全塞进提示词行吗?
不行,会吃掉大量上下文还降低准确率。做法是只给核心表清单和一句话用途,其余通过查询工具按需获取。优先保证模型能先选对表,字段细节后补。
能不能让模型自己写 SQL 查元数据?
技术上可以,等于把查表结构也变成一次工具调用。但要确认账号能访问信息模式表,且服务端限制了可选范围,否则模型可能查到不该看的库。
表结构改了,模型还按旧的写,怎么办?
一般是缓存没失效。检查缓存策略,给元数据加版本号或加失效时间。另外把变更同步写进注入清单,避免只改库没改提示。
接数据库会不会把数据泄露给模型厂商?
取决于你送了什么。送表名和字段名属于元数据,不送行数据;如果用的是外部 API,要评估表名本身是否敏感。对外场景建议只开白名单视图并做脱敏。