从连接到安全落地：KES MCP Server 工程化实践的全记录

1. 为什么要在 Cursor 里接 KES MCP Server

KES MCP Server 是电科金仓围绕 KingbaseES 开源的一个中间层服务，它把数据库的结构探索、SQL 执行、执行计划分析、健康巡检、索引推荐这些高频操作，封装成一组标准化的 MCP 工具，让 Cursor、TRAE、Claude Desktop 这类支持 MCP 协议的客户端可以直接调用。简单说，它让 AI 从"只会聊天"变成"能真正摸到你的库"，但又不会让 AI 绕过权限直接乱来。

它适合谁？我总结了三类人：一是天天写 SQL 的后端和数据库开发，想把"切客户端看表结构、复制执行计划、再丢给 AI 分析"这套碎片动作收进一个对话窗口；二是做数据分析和运维的同学，想用自然语言跑查询、做巡检；三是正在搭 AI Agent 应用的团队，需要一个受控的数据库访问通道。它基于开源的 postgres-mcp 二次开发，MIT 协议，如果你用的是 PostgreSQL 系数据库，整套思路基本可以平移。

我自己的痛点很具体：排查一条慢查询，要在 IDE、数据库客户端、AI 网页之间来回切，截图粘贴十几分钟就没了。KES MCP Server 把这套流程收进 Cursor 一个窗口后，问一句"orders 表有哪些索引"，AI 直接调工具返回结构化结果，效率差别是肉眼可见的。下面我从环境准备一路写到智能运维助手搭建，把连接配置、SQL 调用、权限收敛、踩坑排查都过一遍。

2. 前置准备：环境清单与最小权限账号

动手前先把家底摸清楚，不然装到一半卡住很浪费时间。KES MCP Server 对运行环境有几个硬性要求，我整理成一张表，你可以对照自查。

生产环境绝对不能拿 DBA 账号给 MCP 用，这是纵深防御的第一道闸。先用 system 账号连上库，建一个只读的 AI 专用账号：

CREATE USER ai_mcp WITH PASSWORD 'K1ngbase@2026#Mcp'; GRANT CONNECT ON DATABASE testdb TO ai_mcp; GRANT USAGE ON SCHEMA public TO ai_mcp; GRANT SELECT ON ALL TABLES IN SCHEMA public TO ai_mcp; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ai_mcp;

这样即使 MCP 的受限模式被绕过，账号本身也只有 SELECT 权限，删不掉数据。接着把两个可选扩展装上，不然后面的索引推荐和慢查询分析都会报"扩展不存在"：

CREATE EXTENSION IF NOT EXISTS sys_stat_statements; CREATE EXTENSION IF NOT EXISTS sys_hypo;

拉代码和装依赖用 uv 管理最省事。这里有两个我亲自踩过的坑，提前给你排掉。第一个是 PyPI 下载超时，ruff、pyright 这些 dev 依赖走官方源容易断流，换清华镜像一劳永逸：

uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple .

第二个是 MCP SDK 版本飘了。仓库声明的是mcp[cli]>=1.25.0,<2，但如果你手动装依赖没钉版本，uv 可能给你拉到 MCP 2.0，启动直接报 ImportError。显式钉一下就行：

uv pip install "mcp<2"

传输方式有三种，按部署形态选一个：Stdio 是本地子进程、不开端口，本机开发最省事，客户端自动拉起；SSE 是早期远程方案，HTTP 长连接；Streamable HTTP 走/mcp路径，支持反向代理加 HTTPS 和网络隔离，官方推荐用于企业集中部署。我本机调试用 Stdio，团队共享那台库上跑 Streamable HTTP。

3. 可复制配置：Cursor 侧 mcp.json 与鉴权参数

这一节是全文最该照着抄的部分。Stdio 模式下不用手动启动 Server，客户端会自动拉起。找到 Cursor 的配置文件，Windows 是%USERPROFILE%\.cursor\mcp.json，macOS 是~/.cursor/mcp.json，写入下面这段：

{ "mcpServers": { "kingbase-mcp": { "command": "uv", "args": [ "--directory", "/home/kingbase/kingbase-mcp", "run", "kingbase-mcp", "--access-mode", "restricted" ], "env": { "DATABASE_URI": "kingbase://ai_mcp:K1ngbase@2026#Mcp@127.0.0.1:54321/testdb" } } } }

这里三个关键点必须写全，缺一个都连不上。Base URL 对应DATABASE_URI里的127.0.0.1:54321，这是 KES 默认端口；Key 对应 URI 里的用户名密码ai_mcp:K1ngbase@2026#Mcp；Model ID 在 MCP 场景里对应的是--access-mode restricted这个访问模式参数，它决定了 AI 能调哪些工具、能执行什么 SQL。如果你用 TRAE，在项目根目录建.trae/mcp.json，结构略有不同，照着填即可。

--directory一定要用绝对路径，我见过太多人写相对路径导致客户端识别不到工具。配置存盘后完全退出 Cursor 再打开，MCP 面板里能看到kingbase-mcp已加载、10 个工具全部可见，就说明接通了。这 10 个工具覆盖四类场景：结构探索有list_schemas、list_objects、get_object_details；查询计划有execute_sql、explain_query；运维诊断有analyze_db_health、get_top_queries、analyze_db_config；索引优化有analyze_workload_indexes、analyze_query_indexes。

注意：restricted模式下execute_sql走的是 AST 白名单，只放行 SELECT、EXPLAIN、SHOW、VACUUM/ANALYZE 这类只读语句。哪怕 AI 生成了一条DELETE FROM orders，也会被直接拦截并报Error validating query。这是权限收敛的核心机制，别为了图方便改成 unrestricted。

如果你走 Streamable HTTP 集中部署，配置里把command换成 URL 形式，并在反向代理层加 HTTPS 和网络隔离。团队共享场景下，我建议把 MCP Server 部署在数据库同网段的独立机器上，只暴露/mcp路径，其余端口全部关掉。

4. 验证请求：连接自检与 SQL 读写验证

配置完别急着上生产，先做连接自检。在 Cursor 对话框里敲一句：

列出当前数据库的所有 schema

如果 AI 返回了public、sys_catalog、information_schema这些，说明连通成功。这一步验证的是list_schemas工具和底层连接是否正常。

接着验证结构探索能力，问：

查看 public schema 下 orders 表的字段、约束和现有索引

AI 会调get_object_details，返回结构化的列定义、主键、外键、索引清单。我排查订单查询时第一句就问这个，确认user_id和status上到底有没有联合索引。返回结果大概长这样：

orders 表结构 ├─ 字段 │ ├─ id BIGINT, 主键 │ ├─ user_id BIGINT, NOT NULL │ ├─ status VARCHAR(20), 默认 'pending' │ ├─ amount NUMERIC(12,2) │ └─ created_at TIMESTAMP ├─ 约束 │ ├─ 主键: orders_pkey (id) │ └─ 外键: fk_orders_user → users(id) └─ 索引 └─ orders_pkey (id) ← 只有主键索引，没有 (user_id, status)

能看出按user_id和status过滤的查询会全表扫描。然后验证执行计划分析：

分析这条 SQL 的执行计划：SELECT * FROM orders WHERE user_id = 123 AND status = 'pending'

AI 调explain_query，返回的真实执行计划会显示 Seq Scan，代价不低。它还会解读："当前走了全表扫描，因为 user_id 上没有可用的索引，estimated rows 远大于实际，统计信息可能过期。"这种"给结果加给判断"的输出，比单纯 EXPLAIN 一行行密密麻麻的文本好读太多。

最后验证自然语言转 SQL 和只读执行：

查询本月销售额前 5 的商品，包含商品名和销售额

AI 会先用get_object_details摸清表结构，生成一条 JOIN 查询，再用execute_sql在 restricted 模式下跑出来。整个过程你不用写一行 SQL。如果这一步报Error validating query，说明 AI 生成的语句不在白名单里，检查是不是误触发了写操作。

5. 常见报错排查：401、local proxy failed 与扩展缺失

工程化落地最耗时的就是排错。我把实际遇到的报错和对应解法整理成清单，你对照着查。

401和local proxy failed是最常见的两个。前者九成是 URI 里的密码含特殊字符没转义，比如#在 URI 里是片段标识符，得写成%23。后者多半是--directory用了相对路径，或者 uv 环境没激活。我试过在终端手动跑uv run kingbase-mcp --access-mode restricted，能启动就说明是客户端配置问题，启动不了就是环境问题，二分法很快能定位。

Error reading choices这个报错特别隐蔽，它不会直接告诉你版本问题，而是解析响应时失败。遇到它先查uv pip list | grep mcp，版本高于 2.0 就降下来。OAuth报错则通常是配置里混进了远程 URL，Stdio 模式纯本地子进程通信，不涉及任何鉴权跳转。

提示：排障时优先看 MCP Server 的 stderr 输出，Cursor 的 MCP 面板里能展开日志。大部分连接问题在日志里都有明确堆栈，比猜快得多。

6. 能力落地与安全边界：从 SQL 调用到智能运维

接通只是第一步，真正体现价值的是日常场景。结构查询不用再背表结构，一句"查看 orders 表的字段、约束和索引"就拿到结构化结果。SQL 生成与执行计划分析更省事，把慢查询丢给 AI，它调explain_query返回计划并解读，比纯 EXPLAIN 文本好读。数据查询走自然语言转 SQL，业务同学描述"上个月华东区各品类销量对比"，AI 转 SQL、执行、整理成表格。

运维辅助是我用得最多的。一句"检查一下数据库健康状况"，AI 调analyze_db_health跑 7 项检查：索引、连接利用率、vacuum 回卷风险、序列耗尽、复制延迟、缓存命中率、约束有效性。有次真实输出里大部分正常，但有一项亮黄灯：

Vacuum 回绕预警 对象: sys_catalog._kingbase_loginfo 剩余事务数: -9,999,999（阈值 10,000,000） 建议: VACUUM sys_catalog._kingbase_loginfo;

慢查询排查同样省事，"找出最近总耗时最高的 5 条查询"，AI 调get_top_queries基于 sys_stat_statements 返回 Top N。我那次发现前两条慢查询吃掉了 83.5% 的总耗时，一条JOIN ... ON id != id跑了 7 次扫了 460 万行，另一条 CROSS JOIN 跑了 80 次。过去要自己写一大堆 sys_stat_statements 查询去捞，现在一句话的事。

索引优化配合 sys_hypo 扩展最惊艳。"在 orders 表上加联合索引，对比执行计划变化"，AI 调explain_query并传入 hypothetical_indexes 参数，返回对比：优化前 Seq Scan 代价 34910.76，优化后 Index Scan 代价 8.32。确认有效后再让 DBA 手动 CREATE INDEX，避免盲目建索引浪费存储、拖慢写入。analyze_workload_indexes更猛，它分析历史负载用 DTA 算法推荐索引，我在测试库上跑过，推荐在products(price)上建索引，预估总成本从 6780 万降到 669 万。

安全边界必须说清楚。restricted 模式下 AI 没法直接建表，生成的 DDL 要人复制出来手动跑，DDL 这种结构性变更本就该有人 review。数据分析助手场景我们踩过一个坑：大表全量查询把库拖慢了，restricted 虽然只读但没限制返回行数，后来在账号层加了查询超时，并在对话里约束 AI"超过 1 万行的查询先告知用户"。智能运维助手用 Streamable HTTP 集中部署，配调度脚本定时触发健康检查，但健康检查结果里的"建议操作"不可以无人 review 直接执行，比如 VACUUM 大表可能锁库，还是得走 DBA 审批流程。

如果你想把这条链路跑通，建议从 Stdio 模式本机调试起步，用只读账号加 restricted 模式，先把结构查询和执行计划分析用顺，再逐步扩展到运维巡检和索引推荐。需要统一 Key 和 API 通道管理多个模型时，可以到 TaoToken API Keys 配置，接入细节看 TaoToken 接入文档，想先验证模型对话效果可以直接用 TaoToken 模型对话，长期做编码和 Agent 的团队可以了解 TaoToken Coding Plan。