跳到主要内容
翻译页面

本页面由 AI 辅助从英文翻译而来。如两者存在差异，以英文版本为准。

如何将 StackQL 与 AI 智能体配合使用

StackQL 内置了 Model Context Protocol（MCP）服务器。任何支持 MCP 的智能体（Claude、Cursor、Continue 或自定义智能体框架）都可以连接到它，并获得一个自描述、受治理的 SQL 接口，用于访问 StackQL 注册表中的每个云和 SaaS Provider。

步骤​

  1. 设置 Provider 凭据，在启动服务器之前以环境变量的形式提供（服务器会继承这些变量）：
export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY

也可以（在 v0.10.542 之后的 StackQL 发布版本中）使用 --env.file 指定一个 dotenv 风格的凭据文件；reload_credentials MCP 工具会在会话中途重新加载该文件，因此轮换后的凭据无需重启即可到达正在运行的服务器。

  1. 启动 MCP 服务器。 对于独立的 HTTP 服务器：
stackql mcp \
  --mcp.server.type=http \
  --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9912", "allow_unauthenticated": true}}'

从 v0.12.742 起，HTTP 传输方式要么需要 server.auth_token_env_var（一个环境变量，保存每个请求都必须携带的预共享 bearer 令牌），要么需要像此处所示显式选择启用 allow_unauthenticated，否则服务器会拒绝启动；对于其他进程或主机可以访问的任何监听器，请使用令牌。stdio 不受影响。

对于嵌入编辑器的客户端，使用 --mcp.server.type=stdio 并让客户端启动进程（参阅如何将 StackQL 与 Claude 配合使用）。要在一个进程中同时提供 MCP 和 PostgreSQL 线协议，使用 stackql srv，并附带相同的 MCP 标志和 --pgsrv.port。

  1. 选择安全模式。 模式在服务器配置中设置，并对智能体可以执行的操作进行门控：
模式SELECT / 元数据INSERT / UPDATEDELETEEXEC
read_only允许拒绝拒绝拒绝
safe（默认）允许需要审批需要审批需要审批
delete_safe允许允许需要审批需要审批
full_access允许允许允许允许

“需要审批”使用 MCP 征询（elicitation）流程：客户端向用户显示待执行的 SQL，由用户接受或拒绝。对于资源清单智能体，固定使用 read_only；full_access 只保留给受信任且审计日志有人审查的流水线。包含多条语句的负载按其中权限最高的语句进行门控（从 v0.12.742 起），因此变更无法藏在开头的 SELECT 之后绕过门控。

  1. 让智能体先发现，再查询。 典型的智能体会话：调用一次 server_info，然后 list_providers -> list_methods（它会给出必需的 WHERE 参数）-> validate_select_query -> run_select_query：
SELECT name, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';

智能体从不加载 SDK；schema 在运行时发现，查询则是普通的 SQL。

审计​

每次工具调用都会向支持轮转的文件接收器写入一条 JSONL 记录：时间戳、工具、模式、决策、查询类别、SQL、耗时。审计默认开启，记录智能体做了什么（不记录结果行）。在默认的 strict 失败模式下，审计写入失败会作为错误报告，而不会让未经审计的变更悄悄通过。