企业官网建设流程全解析

MCP Toolbox 连接指南：通过官方 SDK、MCP 客户端、Gemini CLI 与 IDE 将数据库工具接入 AI 工作流

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

MCP Toolbox for Databases 是一款开源的 MCP（Model Context Protocol）服务器，为数据库提供统一、可复用的 AI 工具层。当你完成服务器配置并成功运行后，下一步就是把工具真正投入使用。本文基于仓库 connect-to 文档 的完整脉络，系统讲解四类连接方式——官方 Client SDK（Python / JavaScript / Go）、MCP 兼容客户端与 CLI、Gemini CLI Extensions、IDE 集成，并深入源码层面（如 cmd/internal/flags.go 与 internal/server/mcp）解释其底层原理。读完本文，你将能够根据自身应用场景选择正确的接入路径，并独立完成从终端到 IDE 的各类客户端配置。

一、连接方式总览：MCP Toolbox 如何作为"通用控制平面"

因为 MCP Toolbox 构建在 Model Context Protocol（MCP）之上，它天然充当一个通用控制平面（universal control plane），可以被种类繁多的客户端消费——无论是代码中的应用、终端中的 CLI、还是你日常使用的 IDE。官方文档按使用场景将连接方式划分为三类：

• Client SDKs（应用集成）：面向需要构建自定义 AI Agent 或在代码中编排多步工作流的开发者。官方 SDK 允许应用在运行时动态获取工具 schema 并执行查询。
• MCP Clients & CLIs：面向不想编写完整应用的场景。你可以直接使用 MCP 兼容的命令行客户端与已配置的数据库交互并执行工具。
• IDE 集成：把 Toolbox 直接接入 MCP 兼容的 IDE，让 AI 编程助手实时访问数据库 schema，从而写出精准匹配的查询与应用代码。

此外，Available Connection Methods一节提示：一旦 Toolbox 服务器配置完成并运行，选择哪种方式完全取决于你的使用场景。以下各节将逐一展开。

二、方式一：官方 Client SDK（Python / JavaScript / Go）

2.1 SDK 能为你做什么

Toolbox Client SDK 是连接自定义应用到 Toolbox 服务器的"积木"。无论你只是写一个执行单条查询的脚本，还是在构建复杂的多 Agent 编排系统，SDK 都会替你处理底层的 Model Context Protocol 通信，让你专注于业务逻辑。具体来说，SDK 负责：

• 从运行中的 Toolbox 实例获取工具定义；
• 提供代表这些工具的便捷 Python / JS / Go 对象或函数；
• 调用工具（即调用 Toolbox 中配置的底层 API / 服务）；
• 按需处理认证、参数绑定与安全参数（Secure Parameters）。

官方对三种主流语言提供完整支持与框架深度集成，详见 Toolbox SDKs 总览：

• Python SDKs：包含 Core SDK，以及针对 LangChain、LlamaIndex 和 ADK（Agent Development Kit）的原生集成。
• JavaScript / TypeScript SDKs：面向 Node.js 应用，提供 Core SDK 与 ADK 集成。
• Go SDKs：提供高并发友好的 Go Core SDK，以及用于 Genkit 和 ADK 的集成包。

2.2 Python 包选择：用哪个包取决于你的编排框架

以 Python SDK 文档 为例，选包逻辑非常清晰：

安装方式（任选其一）：

# 用于 Google ADK 集成 pip install google-adk[toolbox] # 或：核心框架无关 SDK pip install toolbox-core # 或：LangChain/LangGraph 集成 pip install toolbox-langchain # 或：LlamaIndex 集成 pip install toolbox-llamaindex

使用前需先按 本地快速上手 将主 MCP Toolbox 服务运行起来。

2.3 跨 SDK 的 Secure Parameters 支持

Secure Parameters（安全参数）允许开发者把敏感的、由应用控制的参数（如租户 ID、会话令牌）**带外（out-of-band）**直接传给工具，完全隔离于 LLM 上下文与提示注入。各语言 SDK 的支持情况如下（数据来自 SDK 总览）：

三、方式二：MCP 客户端与 CLI

你并不需要构建完整应用才能使用 Toolbox。官方文档在 MCP Client 章节 中详细说明了如何从终端直接与数据库交互。

3.1 先理解：Toolbox SDK 与 MCP 的关系

Toolbox 通过 Model Context Protocol 支持连接，但它有若干不被 MCP 规范覆盖的特性，例如：

• Authenticated Parameters（已认证参数）：要求每个调用附带已认证的属性（如用户 ID、租户 ID 或请求 ID），无法被注入到 LLM 上下文中的工具调用；
• Authorized Invocation（授权调用）：在工具执行前强制执行声明式 RBAC 权限检查，检查基于调用者附带的已验证属性。

官方建议：优先使用原生 Toolbox Client SDK以充分利用这些特性；同时 SDK 与 MCP 客户端在很多场景下可以组合使用。

3.2 支持的 MCP 协议版本

Toolbox 当前支持以下 MCP 规范版本：

• 2026-07-28
• 2025-11-25
• 2025-06-18
• 2025-03-26
• 2024-11-05

对应到仓库源码，这些版本分别在 internal/server/mcp 下的v20260728、v20251125、v20250618、v20250326、v20241105各目录中实现，每个目录都包含 5～7 个协议实现文件。

3.3 Secure Parameters 与 MCP 客户端的行为约定

Secure Parameters 在 MCP 协议版本2026-07-28及更新版本上通过com.google.cloud/toolbox.v1扩展支持。仓库源码 internal/server/mcp/v20260728/extensions.go 与 manifests.go 印证了以下完整行为约定：

• 扩展协商：MCP 客户端需在params._meta["io.modelcontextprotocol/clientCapabilities"].extensions["com.google.cloud/toolbox.v1"]中声明对该扩展的支持；
• Manifests（tools/list）：协商成功后，工具会在inputSchema（常规模型参数）之外，通过secureInputSchema定义应用控制的参数；
• 调用（tools/call）：安全参数通过params.secureArguments带外传递，模型生成的参数仍走params.arguments；
• 通用 MCP 客户端的降级行为：未协商该扩展（或使用2026-07-28之前协议版本）的客户端，其tools/list响应会自动过滤掉需要安全参数的工具。若仍直接调用，则：
  • 在协议2026-07-28上返回MissingRequiredClientCapabilityError（JSON-RPC 错误码-32021）；
  • 在更早协议版本上返回ToolNotFoundError/INVALID_PARAMS（JSON-RPC 错误码-32602，"tool does not exist"），因为安全工具在旧协议上完全不可见；
• 注入防御：若客户端或模型尝试把安全参数塞进标准arguments，服务器会拒绝该参数并返回工具执行错误（isError: true）。

3.4 连接前置条件

MCP 仅兼容 Toolbox0.3.0及以上版本。开始之前需要：

1. 安装 Toolbox0.3.0+（参见安装说明中的 Installing the server 一节）；
2. 确保数据库已设置并初始化；
3. 配置好 tools.yaml。

3.5 通过 stdio 连接

Toolbox 支持 MCP 的 stdio 传输协议，使用 stdio 时必须携带--stdio标志：

./toolbox --stdio

• 启用 stdio 后，Toolbox 不再作为远程 HTTP 服务器，而是通过标准输入输出监听；
• 日志默认设为warn级别，stdio 模式下不支持debug与info日志；
• Toolbox 默认启用动态重载（dynamic reloading），如需关闭请加--disable-reload标志。

从源码看，这些标志在 cmd/internal/flags.go 中定义：--stdio对应Listens via MCP STDIO instead of acting as a remote HTTP server.，--disable-reload对应Disables dynamic reloading of tools file.。动态重载在 cmd/root.go 中通过 fsnotify 文件监听器实现，支持配置文件的 Write/Create/Rename 事件，并带 100ms 防抖；NFS 环境下可通过--poll-interval指定轮询秒数（源码 cmd/root.go 的watchChanges函数）。

3.6 通过 HTTP 连接

Toolbox 同时支持带 SSE 与不带 SSE 的 HTTP 传输协议。

HTTP with SSE（已弃用，仅2024-11-05）——MCP 客户端配置示例：

{ "mcpServers": { "toolbox": { "type": "sse", "url": "http://127.0.0.1:5000/mcp/sse" } } }

如需连接特定工具集（toolset），将url替换为http://127.0.0.1:5000/mcp/{toolset_name}/sse。

Streamable HTTP（推荐）：

{ "mcpServers": { "toolbox": { "type": "http", "url": "http://127.0.0.1:5000/mcp" } } }

同理，连接特定工具集时使用http://127.0.0.1:5000/mcp/{toolset_name}。

这里的默认地址与端口127.0.0.1:5000对应源码中--address（默认127.0.0.1）与--port（默认5000）两个服务端标志（见 cmd/internal/flags.go）。

3.7 使用 MCP Inspector 调试

官方推荐使用 MCP Inspector 测试与调试 Toolbox 服务器，三种传输方式均支持：

STDIO 模式：

npx @modelcontextprotocol/inspector ./toolbox --stdio

随后在 Inspector 界面：Transport Type 选STDIO，Command 填./toolbox（或二进制实际路径），Arguments 填--stdio，点击 Connect。

HTTP with SSE（已弃用）：先运行 Toolbox，再单独执行npx @modelcontextprotocol/inspector；Transport Type 选SSE，URL 填http://127.0.0.1:5000/mcp/sse（全部工具）或http://127.0.0.1:5000/mcp/{toolset_name}/sse（指定工具集）。

Streamable HTTP：同样先运行 Toolbox 与npx @modelcontextprotocol/inspector；Transport Type 选Streamable HTTP，URL 填http://127.0.0.1:5000/mcp或http://127.0.0.1:5000/mcp/{toolset_name}。

3.8 官方测试过的客户端

根据官方文档的 Tested Clients 表，以下客户端在 SSE 模式下验证可用：

四、方式三：Gemini CLI Extensions

Gemini CLI 是一款开源 AI Agent，用于辅助开发工作流（编码、调试、数据探索、内容创作等），其使命是为数据库与分析服务提供 agentic 交互界面。Gemini CLI 高度可扩展，可通过 GitHub URL、本地目录或可配置的 registry 加载扩展；扩展提供新的工具、斜杠命令（slash commands）与提示词（prompts）。

以下是官方列出的一批由 MCP Toolbox 驱动的 Gemini CLI Extensions（扩展代码托管于独立的 gemini-cli-extensions 仓库，通过 URL 加载）：

• alloydb、alloydb-observability
• bigquery-conversational-analytics、bigquery-data-analytics
• cloud-sql-mysql、cloud-sql-mysql-observability
• cloud-sql-postgresql、cloud-sql-postgresql-observability
• cloud-sql-sqlserver、cloud-sql-sqlserver-observability
• knowledge-catalog
• firestore-native
• looker
• mcp-toolbox
• mysql、postgres
• spanner、sql-server

加载这些扩展后，即可直接在终端里用自然语言管理、查询你的数据。仓库中对应的预构建配置可在 internal/prebuiltconfigs/tools 目录下找到（如alloydb-postgres.yaml、bigquery.yaml、cloud-sql-postgres.yaml等）。

五、方式四：IDE 集成——以 PostgreSQL 为例

将 Toolbox 直接接入 MCP 兼容 IDE 后，AI 编程助手即可实时访问数据库 schema，编写精准的查询与应用代码。仓库的 IDEs 章节 收录了面向 AlloyDB、BigQuery、Cloud SQL、Firestore、Looker、MSSQL、MySQL、Neo4j、Oracle、PostgreSQL、Spanner、SQLite 等多个数据库的接入指南。

这里以 PostgreSQL using MCP 指南 为例，演示完整流程（该指南同样适用于 AlloyDB Omni）。

5.1 准备数据库

1. 创建或选择 PostgreSQL 实例（本地安装 PostgreSQL，或安装 AlloyDB Omni）；
2. 创建或复用数据库用户，并准备好用户名与密码。

5.2 安装 MCP Toolbox（v0.6.0+）

1. 下载与操作系统、CPU 架构匹配的最新二进制（按平台选择下载链接，例如linux/amd64或darwin/arm64），要求 Toolbox 版本V0.6.0+（当前文档示例版本为 v1.11.0）；
2. 赋予执行权限并验证：

chmod +x toolbox ./toolbox --version

5.3 配置 MCP 客户端

各客户端配置的核心思路一致：以 stdio 方式启动 toolbox，使用--prebuilt postgres加载预构建的 PostgreSQL 工具配置，并通过环境变量注入连接信息。以下配置在 Claude Code、Claude Desktop、Cline、Cursor、Windsurf、Gemini CLI、Gemini Code Assist 中结构相同，仅存放位置与入口不同：

{ "mcpServers": { "postgres": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "postgres", "--stdio"], "env": { "POSTGRES_HOST": "", "POSTGRES_PORT": "", "POSTGRES_DATABASE": "", "POSTGRES_USER": "", "POSTGRES_PASSWORD": "" } } } }

各客户端的配置入口差异如下：

5.4 使用工具

连接成功后，你的 AI 工具即已通过 MCP 接入 PostgreSQL。可以尝试让 AI 助手列出表、创建表、定义并执行其他 SQL 语句。预构建的 PostgreSQL 工具集中，LLM 可用的核心工具包括：

1. list_tables：列出表及描述；
2. execute_sql：执行任意 SQL 语句。

注意：预构建工具仍处于 pre-1.0 阶段，工具可能在版本间变化；由于 LLM 会自适应可用的工具，这对大多数用户影响不大。

六、连接方式选型建议与源码佐证

综合官方文档与仓库源码，可以给出如下选型建议：

1. 构建自定义 Agent / 编排系统：选择官方 Client SDKs。SDK 完整支持动态获取工具、绑定参数、带外安全参数、添加认证与运行时执行命令，是唯一能完整利用 Authenticated Parameters 与 Authorized Invocation 等超集特性的路径；
2. 终端快速交互：选择 MCP Client（stdio 或 Streamable HTTP）或 Gemini CLI Extensions，无需编写应用即可使用自然语言查询数据；
3. IDE 内的 AI 编程助手：选择 IDEs 接入指南，让助手获得数据库 schema 的实时访问能力。

从源码结构看，cmd/root.go 是这一切连接的入口枢纽：它注册了根命令及各子命令，统一解析--stdio、--address、--port、--prebuilt、--disable-reload等标志；stdio 模式走s.ServeStdio，HTTP 模式走s.Listen+s.Serve。而 MCP 协议层的版本差异与安全参数扩展逻辑集中在 internal/server/mcp，其中v20260728目录下的 extensions.go 与 manifests.go 正是上文 3.3 节行为约定的实现依据——这从侧面印证：若你的客户端需要 Secure Parameters，务必选择支持2026-07-28协议的 MCP 客户端或直接使用官方 SDK。

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