MCP Toolbox 集成Integrations架构指南通过 tools.yaml 定义 Source 解锁数据库与 HTTP 专用工具集【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxMCP Toolbox for Databases 将集成抽象为一个清晰的三层模型Integration集成→ Source数据源连接→ Tools专用工具。本文以 docs/en/integrations/_index.md 为骨架结合仓库源码与预置配置系统讲解如何在tools.yaml中定义一次数据源连接、如何让 MCP 客户端立即获得该数据源专属的工具集查询数据、列出表、分析 Schema 等并给出 BigQuery、HTTP 等典型集成的可运行配置示例。读完本文你将掌握 Integration 的配置模型、注册机制、认证方式与只读约束能够独立为任意受支持的数据库或 HTTP 服务编写完整的集成配置。什么是 Integration连接外部数据源并解锁工具集根据 docs/en/integrations/_index.md 的定义AnIntegrationrepresents a connection to a database or a HTTP Server.集成Integration的本质是 MCP Toolbox 与外部数据源数据库或 HTTP 服务器之间的一条连接。这条连接通过Source来承载你只需要在tools.yaml配置文件中定义一次Source 连接集成即宣告建立此后该集成会解锁一组专门化的Tools如执行查询、列出数据表、分析表结构等MCP 客户端IDE、Agent、CLI可以立即调用这些工具。这种一次定义、多处复用的设计让配置与工具注册解耦连接参数只写一遍工具由该 Source 类型自动派生客户端无需关心底层驱动细节。核心概念Source、Tools 与 Group从仓库源码可以确认tools.yaml服务端通过 cmd/internal/config.go 解析是一份多文档 YAML其中每种资源通过kind字段区分支持以下类型source、tool、authService、embeddingModel、prompt、resource、resourceTemplate、group以及旧版toolset解析时会自动折叠为 group。Source数据源连接kind: source定义一个到数据库或 HTTP 服务的连接是集成的入口。其解析流程在 internal/server/config.go 中实现先读取type字段再通过sources.DecodeConfig在源注册表中查找对应的工厂函数完成解码。internal/sources/sources.go 定义了源注册机制的核心接口type SourceConfig interface { SourceConfigType() string Initialize(ctx context.Context, tracer trace.Tracer) (Source, error) } type Source interface { SourceType() string ToConfig() SourceConfig IsReadOnly() bool }每个具体数据源bigquery、postgres、mysql、http 等通过Register(sourceType, factory)将自己注册进sourceRegistry重复注册会被拒绝返回false启动解析时DecodeConfig按type字符串查表并调用对应工厂若类型未知会返回unknown source type错误并提示无法将 source 解析为对应类型Source.Initialize负责真正建立连接池且连接初始化会被埋入名为toolbox/server/source/connect的 OpenTelemetry span携带source_type、source_name属性用于可观测性追踪。Tool数据源解锁的专用能力kind: tool声明一个可被客户端调用的工具必须通过source字段关联到某个已定义的 Source。internal/tools/tools.go 中的Tool接口定义了工具的全部能力面包括GetName()/GetDescription()工具的元信息GetSourceName()工具绑定的数据源GetAnnotations(source)返回 MCP 工具注解如readOnlyHint、destructiveHint用于客户端展示与权限提示Invoke(...)执行工具逻辑入参为parameters.ParamValues与可选的AccessTokenAuthorized(verifiedAuthServices)结合authRequired判断调用是否被授权ValidateSource(source)校验工具与数据源的兼容性。工具同样通过注册表机制toolRegistryRegister实现类型分发internal/tools/tools.go 中的ErrUnknownToolType会在类型未知时被抛出。为了让工具编写者少写样板代码仓库提供了 BaseTool 泛型基类默认实现元信息、Manifest、参数获取等方法具体工具只需覆写需要定制的行为。Group把工具组织成语义分组kind: group将若干工具聚合成一个命名集合供客户端按场景发现和编排。以 internal/prebuiltconfigs/tools/bigquery.yaml 为例BigQuery 集成把工具分成两组data组execute_sql、list_dataset_ids、list_table_ids、get_dataset_info、get_table_info、search_catalog用于大规模数据探索与数据集管理analytics组analyze_contribution、ask_data_insights、forecast、search_catalog用于数据智能分析与预测。分组描述即何时该用这组工具的语义提示能被 Agent 直接当作技能选择依据。编写你的第一个集成BigQuery 示例完整继承 docs/en/integrations/bigquery/source.md 中的示例一个使用应用默认凭据ADC的 BigQuery Source 如下kind: source name: my-bigquery-source type: bigquery project: my-project-id # location: US # Optional: Specifies the location for query jobs. # readOnly: false # Optional: Enforces read-only mode across all tools (defaults writeMode to blocked). # writeMode: allowed # One of: allowed, blocked, protected. Defaults to allowed. # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets. # - my_dataset_1 # - other_project.my_dataset_2 # impersonateServiceAccount: service-accountproject-id.iam.gserviceaccount.com # Optional: Service account to impersonate # scopes: # Optional: List of OAuth scopes to request. # - https://www.googleapis.com/auth/bigquery # - https://www.googleapis.com/auth/drive.readonly # maxQueryResultRows: 50 # Optional: Limits the number of rows returned by queries. Defaults to 50. # maximumBytesBilled: 10737418240 # Optional: Per-query bytes scanned cap (in bytes). # apiEndpoint: http://localhost:9050 # Optional: Override the BigQuery API endpoint (proxy or local emulator).若希望以客户端/终端用户的 OAuth 访问令牌代发请求则使用useClientOAuthkind: source name: my-bigquery-client-auth-source type: bigquery project: my-project-id useClientOAuth: true # location: US # Optional: Specifies the location for query jobs. # readOnly: false # Optional: Enforces read-only mode across all tools (defaults writeMode to blocked). # writeMode: allowed # One of: allowed, blocked, protected. Defaults to allowed. # allowedDatasets: # Optional: Restricts tool access to a specific list of datasets. # - my_dataset_1 # - other_project.my_dataset_2 # impersonateServiceAccount: service-accountproject-id.iam.gserviceaccount.com # Optional: Service account to impersonate # scopes: # Optional: List of OAuth scopes to request. # - https://www.googleapis.com/auth/bigquery # - https://www.googleapis.com/auth/drive.readonly # maxQueryResultRows: 50 # Optional: Limits the number of rows returned by queries. Defaults to 50. # maximumBytesBilled: 10737418240 # Optional: Per-query bytes scanned cap (in bytes). # apiEndpoint: http://localhost:9050 # Optional: Override the BigQuery API endpoint (proxy or local emulator).BigQuery Source 参数参考fieldtyperequireddescriptiontypestringtrue必须为bigquery。projectstringtrue用于计费与默认项目的 Google Cloud 项目 ID。locationstringfalse执行查询作业的位置如us、asia-northeast1必须与查询中引用表的位置一致无法确定时默认使用表的位置或US。readOnlybooleanfalse是否全 Toolbox 只读。readOnly: true会协同 MCP 只读注解与工具抑制并把writeMode默认置为blocked也允许protected若同时提供writeMode必须与readOnly一致否则启动报配置错误。writeModestringfalse写行为控制。allowed默认放行全部查询blocked强制严格只读注册时抑制可写工具、只允许SELECTprotected启用会话级执行所有工具共享同一个 BigQuery 会话可用CREATE TEMP TABLE做有状态操作但保护永久数据集不能与useClientOAuth: true同用会话在无活动 24 小时或 7 天后自动终止。allowedDatasets[]stringfalse允许访问的数据集白名单越权访问会被拒绝同时禁止数据集级操作和无法静态分析表访问的操作如EXECUTE IMMEDIATE。useClientOAuthstringfalse设为true时从默认Authorization头转发客户端 OAuth 令牌也可设为自定义头名如X-My-Auth空串或false关闭。scopes[]stringfalse凭据使用的 OAuth 2.0 作用域缺省时使用默认作用域。impersonateServiceAccountstringfalse模拟的服务账号邮箱调用 BigQuery/Dataplex API 时使用认证主体需持有目标账号的roles/iam.serviceAccountTokenCreator。maxQueryResultRowsintfalse单次查询最多返回行数默认 50。maximumBytesBilledint64false单次查询最大计费字节数超限的查询在执行前即失败。apiEndpointstringfalse覆盖 BigQuery API 端点可用于代理或本地模拟器。sqlCommenterbooleanfalse覆盖全局--sql-commenter标志设置时优先缺省时沿用全局配置。结合源码看认证与安全细节ADC 与作用域默认使用应用默认凭据ADC在 GCE/GKE 上可通过scopes显式指定如https://www.googleapis.com/auth/bigquery或 internal/sources/sources.go 中定义的云平台全局作用域。客户端令牌useClientOAuth开启后internal/tools/tools.go 的AccessToken.ParseBearerToken会校验Authorization头必须符合Bearer token格式否则返回 401 客户端错误。工具注解工具通过注解向 MCP 客户端声明语义internal/tools/tools.go 提供了NewReadOnlyAnnotations只读、NewWriteAnnotations非破坏性写入、NewDestructiveAnnotations破坏性写入三组预设。只读抑制internal/tools/tools.go 的ShouldSuppress在数据源只读时自动抑制可写工具ReadOnlyHint: false并提示未标注ReadOnlyHint的工具补充注解以节省 Agent 上下文窗口。通过环境变量注入密钥所有配置项都支持${ENV_NAME}形式的环境变量替换也可以带默认值${ENV_NAME:default}。cmd/internal/config.go 中的parseEnv在 YAML 解析前完成替换注释内的占位符不会被替换。官方预置配置大量使用这一机制例如 internal/prebuiltconfigs/tools/bigquery.yamlkind: source name: bigquery-source type: bigquery project: ${BIGQUERY_PROJECT} location: ${BIGQUERY_LOCATION:} readOnly: ${BIGQUERY_READONLY:} writeMode: ${BIGQUERY_WRITE_MODE:} useClientOAuth: ${BIGQUERY_USE_CLIENT_OAUTH:false} scopes: ${BIGQUERY_SCOPES:} maxQueryResultRows: ${BIGQUERY_MAX_QUERY_RESULT_ROWS:50} impersonateServiceAccount: ${BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT:} maximumBytesBilled: ${BIGQUERY_MAXIMUM_BYTES_BILLED:0} apiEndpoint: ${BIGQUERY_ENDPOINT:} --- kind: tool name: execute_sql type: bigquery-execute-sql source: bigquery-source description: Use this tool to execute sql statement. --- kind: group name: data description: Use these skills when you need to handle large-scale data exploration and dataset management. tools: - execute_sql - list_dataset_ids - list_table_ids - get_dataset_info - get_table_info - search_catalog最佳实践将密钥如 API Key、密码放进${ENV_NAME}占位符而非硬编码在配置文件中同时避免在 YAML 注释中填写真实密钥——注释中的占位符不会被替换。预置配置开箱即用的工具集仓库通过 Go embed 把一组官方配置编译进二进制。internal/prebuiltconfigs/prebuiltconfigs.go 使用//go:embed tools/*.yaml加载internal/prebuiltconfigs/tools/目录下全部 YAML并以文件名去掉.yaml作为集成类型键。当前内置了超过 40 种数据源配置覆盖 BigQuery、PostgreSQL、MySQL、Cloud SQLmysql/mssql/postgres 及各自 admin 版、Spanner、Snowflake、Looker、ClickHouse、MongoDB、Redis、Valkey、SQLite、HTTP 等可通过GetPrebuiltSources()获取完整列表。以bigquery-source的预置工具为例一个 Source 即解锁 9 个专用工具bigquery-execute-sql、bigquery-conversational-analytics数据洞察问答、bigquery-analyze-contribution多维指标贡献分析、bigquery-forecast时序预测、bigquery-get-dataset-info、bigquery-get-table-info、bigquery-list-dataset-ids、bigquery-list-table-ids、bigquery-search-catalog——与 docs/en/integrations/bigquery/tools/ 中逐工具的文档一一对应。自定义工具与参数校验在预置工具之外你可以在tools.yaml中追加自定义kind: tool声明。internal/server/config.go 的UnmarshalYAMLToolConfig会执行若干启动期校验name必须为 1~128 字符且仅含 ASCII 字母、数字、下划线、连字符与点见 NameValidationauthRequired与useClientOAuth互斥只能二选一parameters中的valueFromParam引用必须指向已定义的同列表参数且不允许自引用若开启ignoreUnknownTools未知工具类型会被跳过并告警而不是让服务启动失败。HTTP 集成连接任意 HTTP 服务除数据库外Integration 也支持连接 HTTP 服务器让 Agent 能访问任意 Web API。docs/en/integrations/http/source.md 给出了完整示例kind: source name: my-http-source type: http baseUrl: https://api.example.com/data timeout: 10s # default to 30s headers: Authorization: Bearer ${API_KEY} Content-Type: application/json queryParams: param1: value1 param2: value2 # returnFullError: false # disableSslVerification: false字段含义fieldtyperequireddescriptiontypestringtrue必须为http。baseUrlstringtrueHTTP 请求的基础 URL。timeoutstringfalse请求超时如5s、1m遵循 Gotime.ParseDuration默认 30s。headersmap[string]stringfalse默认请求头。queryParamsmap[string]stringfalse默认查询参数。returnFullErrorboolfalse非 2xx 响应时是否在错误信息中包含原始响应体默认false。disableSslVerificationboolfalse禁用 SSL 证书校验仅建议本地开发使用默认false。allowPrivateNetworksboolfalse是否允许访问环回与私有网络RFC 1918 / link-local默认false。allowedIpRanges[]stringfalse显式放行的 IP 或 CIDR 白名单。customBlockedIpRanges[]stringfalse显式封禁的 IP 或 CIDR 列表。SSRF 防护SSRF GuardHTTP Source 默认内置严格的 SSRF 与 DNS RebindingTOCTOU防护自动拦截并阻断指向以下范围的连接私有 IP 段、环回地址如127.0.0.1、link-local如云元数据服务169.254.169.254、RFC 6598 共享地址段100.64.0.0/10常见于 Kubernetes 节点与 Pod 网络、RFC 6890 协议专用段192.0.0.0/24如 NAT64/DNS64 组件。需要放行内网或封禁特定主机时用三个覆盖字段配置kind: source name: my-http-source type: http baseUrl: https://internal.corp/api allowedIpRanges: - 10.0.0.0/24 # Explicitly trust internal subnet customBlockedIpRanges: - 10.0.0.99 # Block a specific sensitive host inside the subnet集成文档的组织方式如何在仓库中查阅每个集成docs/en/integrations/下每个集成一个目录如bigquery/、http/、postgres/、cloud-sql-pg/、snowflake/等统一采用连接配置 工具清单的组织结构source.md该数据源的连接配置说明含kind: sourceYAML 示例、字段参考表、认证方式ADC / 客户端 OAuth / 服务账号模拟与高级用法tools/该集成解锁的每个工具的独立文档参数、行为、示例prebuilt-configs/部分集成官方预置配置说明samples/部分集成端到端示例。索引页 docs/en/integrations/_index.md 通过{{ list-db }}短代码自动渲染全部集成列表。按需选取配置连接看source.md了解具体能力看对应tools/下的工具文档想快速起步则直接引用internal/prebuiltconfigs/tools/source.yaml并用环境变量替换占位符。完整工作流从配置到客户端调用在tools.yaml中声明kind: source数据库或 HTTP 连接可同时追加自定义kind: tool与kind: group服务启动时internal/server/config.go 的UnmarshalPrimitiveConfig逐文档解析 YAML通过注册表sources.Register/tools.Register校验类型并构建配置重复声明同名资源会报错Source 通过Initialize建立连接池工具按source字段绑定数据源只读源readOnly: true/writeMode: blocked会在注册阶段抑制可写工具客户端IDE / Agent通过 MCP 协议拉取工具 Manifest按authRequired与注解完成鉴权后调用Invoke执行查询、元数据发现或数据分析所有操作可通过 internal/telemetry 输出的 OpenTelemetry span如toolbox/server/source/connect与 SQL Commenter 标签进行追踪审计。小结MCP Toolbox 的 Integration 模型用最少的配置成本打通了外部数据源 → MCP 工具集这条链路一次kind: source声明即可解锁该数据源的全部专用工具预置配置让 BigQuery、PostgreSQL、HTTP 等几十种数据源开箱即用注册表机制保证了类型的可扩展性与启动期校验。理解 Source、Tool、Group 三者关系并掌握环境变量注入、认证方式与只读/写模式约束你就能在 docs/en/integrations/ 的指引下快速为任意受支持数据源编写生产可用的集成配置。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考