企业官网建设流程全解析

DB-GPT MCP 协议接入指南：让 Agent 通过 Model Context Protocol 连接外部工具与服务

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

导读

Model Context Protocol（MCP）是 AI 应用连接外部数据源与工具的标准开放协议。本文以 DB-GPT 的 MCP 支持为核心，系统讲解 MCP 在 DB-GPT 中的整体架构、客户端与服务端两种角色、TOML 配置方法与 Web UI 操作流程、stdio 与 SSE/Streamable HTTP 传输类型，并结合 mcp_utils.py、MCPToolPack、ConnectorManager 等源码揭示其底层工作原理。读完本文，你将能够：为 DB-GPT Agent 配置并挂载任意 MCP 服务器工具、在对话中自动触发工具调用、理解 MCP 客户端连接与工具加载的内部机制，以及将 DB-GPT 自身能力以 MCP Server 形式暴露给外部应用。

MCP 是什么：为什么 Agent 需要它

Model Context Protocol（MCP）是一个开放的协议，它为 AI 应用与外部数据源、工具之间提供了一套标准化的连接方式。在没有 MCP 之前，每个工具都需要为 AI 应用编写一套独立的适配代码；MCP 统一了“工具发现、参数描述、调用执行”的交互模型，使得任何实现了 MCP 的服务都可以被任意 MCP 客户端直接使用。

DB-GPT 对 MCP 提供了双重角色支持（详见 官方文档）：

• 作为 MCP 客户端（Client）：消费外部 MCP 服务器暴露的工具，让 DB-GPT Agent 具备调用文件系统、Web 搜索、GitHub、数据库等外部能力；
• 作为 MCP 服务器（Server）：将 DB-GPT 自身的能力（知识库查询、数据库访问 Text2SQL、Agent 执行等）以 MCP 工具的形式暴露给其他 MCP 兼容的应用。

这意味着 MCP 在 DB-GPT 中不是一条单向链路，而是双向互联：DB-GPT Agent 可以"走出去"用外部工具，也可以"迎进来"让外部应用用 DB-GPT 的能力。

架构总览：DB-GPT 在 MCP 生态中的位置

官方文档给出了 MCP 在 DB-GPT 中的整体架构（见 mcp.md）：

图中清晰地展示了两个方向：

1. 下行（客户端方向）：DB-GPT Agent 作为 MCP Client，可同时挂载多个 MCP Server（如文件系统、Web 搜索、自定义 API），每个 Server 提供一组工具；
2. 上行（服务端方向）：外部 MCP Client 可以连接 DB-GPT 暴露的 MCP Server，进而调用 DB-GPT 的知识库查询、Text2SQL、Agent 执行等能力。

源码视角：MCP Client 的双传输实现

在 DB-GPT 的源码中，MCP Client 的核心传输层实现在 mcp_utils.py，由mcp_transport_client统一分发到两种底层客户端：

# 摘要自 packages/dbgpt-core/src/dbgpt/agent/util/mcp_utils.py _SSE_TRANSPORTS = frozenset({"sse"}) _STREAMABLE_HTTP_TRANSPORTS = frozenset({"streamable_http", "streamablehttp"}) def _normalise_transport(transport: str | None) -> str: """Lowercase + strip ``-``/``_`` separators so all variants collapse to one key.""" if not transport: return "sse" key = transport.strip().lower().replace("-", "").replace("_", "") return key

从源码可以看出几个关键实现细节：

• 传输名做了归一化处理："Streamable-HTTP"、"streamable_http"、"streamableHttp"都会被归一化为同一个 key，调用方无需纠结命名变体；
• 默认传输是sse，当transport参数为空时回退到 SSE；
• streamable_http传输封装了官方mcp.client.streamable_http.streamablehttp_client，但要求 mcp 库版本 ≥ 1.8.0（见streamable_http_client中ModuleNotFoundError分支的提示："MCP Streamable HTTP transport requires mcp>=1.8.0"）；
• sse_client是自实现的 HTTP+SSE 传输，支持自定义请求头、TLS 校验（verify参数）与超时控制（timeout默认 5 秒、sse_read_timeout默认 5 分钟）。

两种传输经过统一封装后，产出相同形状的(read_stream, write_stream)流，因此下游MCPToolPack的调用代码完全一致——这是接口抽象带来的好处。

支持的 MCP Server 类型

DB-GPT 支持以下 MCP Server 传输类型（见 官方文档）：

此外，从源码可以看到 DB-GPT 还完整支持 MCP 2026-03-26 规范定义的Streamable HTTP传输（transport="streamable_http"），它是 SSE 的演进形态。Web UI 连接器表单（ConnectorForm.tsx）中明确列出了两种传输选项及其端点格式：

• SSE：http://your-mcp-server/sse
• Streamable HTTP：https://your-mcp-server/mcp

补充说明：stdio 传输是本地进程通信（如npx启动的本地 MCP Server），主要面向本地开发场景；SSE/Streamable HTTP 则用于连接远程服务，是生产环境接入外部 API 的主要方式。

在 Agent 中使用 MCP 工具：三步实战流程

官方文档给出了从配置到使用的完整流程，共三步。

Step 1 — 配置 MCP Servers

MCP Server 的配置有两种途径：TOML 配置文件或Web UI 的 Agent 配置界面。

TOML 配置示例（完整示例如 官方文档）：

[[agent.mcp_servers]] name = "filesystem" command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"] [[agent.mcp_servers]] name = "web-search" command = "npx" args = ["-y", "@modelcontextprotocol/server-brave-search"] env = { BRAVE_API_KEY = "${env:BRAVE_API_KEY}" }

配置要点：

• 每个[[agent.mcp_servers]]定义一个 MCP Server，name用于标识该服务器；
• command+args指定启动方式，上例通过npx直接拉取并运行 MCP 官方 Server 包（无需手动安装 npm 包）；
• env用于注入环境变量，这里${env:BRAVE_API_KEY}表示引用进程环境中的BRAVE_API_KEY，避免把密钥硬编码进配置文件；
• 需要连接远程 MCP Server 时，可将command/args替换为远程端点地址（如http://127.0.0.1:8000/sse），并指定传输类型。

Step 2 — 为 Agent 分配工具

在 Web UI 中完成工具分配：

1. 进入Apps→ 创建或编辑一个应用；
2. 在 Agent 配置中勾选可用的 MCP 工具；
3. 保存后，该 Agent 即可在对话中调用这些工具。

从源码看工具加载机制：当 Agent 需要挂载 MCP 资源时，后端通过MCPToolPack（tool/pack.py）完成工具发现与注册。其preload_resource方法执行如下关键链路：

# 摘要自 packages/dbgpt-core/src/dbgpt/agent/resource/tool/pack.py async with mcp_transport_client( url=server, transport=self._transport, headers=server_headers, verify=server_ssl_verify, ) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # 1. 建立 MCP 会话 result = await session.list_tools() # 2. 枚举服务器所有工具 for tool in result.tools: tool_name = tool.name self.tool_server_map[tool_name] = server args = self.switch_mcp_input_schema(tool.inputSchema) # 3. 转换参数 Schema # 4. 将每个工具注册为 Agent 可调用的命令（add_command）

• 会话初始化：每个 MCP Server 连接后先执行session.initialize()握手；
• 工具枚举：session.list_tools()拉取服务器全部工具，tool_server_map记录"工具名 → 服务器"的映射关系；
• Schema 转换：switch_mcp_input_schema把 MCP 的 JSON Schema 输入定义（properties、required、items、anyOf、default等字段）转换为 DB-GPT Agent 统一的参数格式（见 tool/pack.py）；
• 命令注册：通过add_command将每个工具以闭包形式注册，调用时再建立一次性连接并执行session.call_tool(tool_name, arguments=kwargs)。

Step 3 — 在对话中使用

当与启用了 MCP 工具的 Agent 对话时，Agent 会根据你的请求自动选择并调用合适的工具——你无需手动指定工具名称，只需用自然语言表达意图（如"帮我搜索 XX 的最新动态""读取本地某个文件"），Agent 会在推理过程中决定是否调用某个 MCP 工具、填充参数并执行。

配置中的头部与 SSL 校验选项

通过源码（MCPSSEToolPack 与 MCPToolPack 的 docstring）可以看到，DB-GPT 还支持以下高级配置：

MCPSSEToolPack的type_alias()返回"tool(mcp(sse))"，表明它是 SSE 传输的 MCP 工具资源类型；其资源参数类（_DynMCPSSEPackResourceParameters）提供了mcp_servers（默认http://127.0.0.1:8000/sse）、token（标记为privacy隐私字段）、no_ssl_verify、ssl_ca_cert四个可配置项，多个服务器地址统一用;分隔。

常用 MCP Server 速查

以下 MCP Server 均来自官方@modelcontextprotocol生态（见 官方文档），可直接在配置中使用：

连接器体系：Web UI 中管理 MCP 的另一条路径

除了 TOML 配置，DB-GPT 还内置了一套Connector（连接器）体系，用于在 Web UI 中统一管理 MCP 连接。相关实现位于 connector 目录 和 前端连接器组件：

• 目录（Catalog）：catalog.py 定义了ConnectorCatalogEntry模型（type、display_name、description、icon、category、mcp_server等字段），mcp_server内部包含server_uri与transport（默认"sse"）。目录从catalog.json加载，内置了多个 MCP 服务器模板；
• 管理器（Manager）：manager.py 中的ConnectorManager负责实例化连接器，并执行工具名加前缀策略：每个 MCP 工具会被重命名为mcp__{prefix}__{original_tool_name}格式（如mcp__github__create_issue、mcp__my-arxiv__search_papers）。该命名刻意对齐 Claude Code 的mcp__<server>__<tool>惯例，mcp__前缀让 LLM 和运维人员能一眼识别工具来源；
• 前端表单：ConnectorForm.tsx 提供连接器配置界面，其中server_uri对所有连接器类型都是顶层必填字段，transport提供 SSE / Streamable HTTP 两种选择，token、header_name等鉴权信息与连接配置分离存储。

借助连接器体系，你可以在 Web UI 的 Connectors 页面创建自定义 MCP 连接（custom_mcp类型），填写server_uri、选择传输类型、配置鉴权，然后在 App/Agent 的配置中选择启用哪些 MCP 工具——这与 TOML 配置是殊途同归的两种方式。

DB-GPT 作为 MCP Server：对外暴露自身能力

DB-GPT 不仅消费 MCP 工具，还可以把自身能力包装为 MCP Server，供其他 MCP 兼容应用调用。官方文档列出的可暴露能力包括：

• 知识库查询：让外部应用检索 DB-GPT 中已建立的 RAG 知识库；
• 数据库访问（Text2SQL）：让外部应用通过自然语言查询数据库；
• Agent 执行：让外部应用触发 DB-GPT Agent 完成复杂任务。

结合整体架构图（上行链路），外部 MCP Client → DB-GPT MCP Server → DB-GPT Capabilities，DB-GPT 相当于在 Agent 能力之上又叠加了一层"开放网关"。这使得 DB-GPT 既能作为 AI 应用的中枢大脑，也能作为能力供给方嵌入到更大的 MCP 生态中——例如，其他聊天工具、IDE、自动化平台都可以通过 MCP 协议直接调用 DB-GPT 的检索与 Text2SQL 能力。

常见问题与最佳实践

1. 传输类型如何选？本地开发、希望零网络依赖时用 stdio（npx启动）；连接远程 MCP Server 时用 SSE 或 Streamable HTTP，其中 Streamable HTTP 是 MCP 新版规范推荐形态，但需要 mcp 库 ≥ 1.8.0。
2. 密钥如何管理？TOML 配置中用${env:VAR_NAME}引用环境变量，避免把 API Key 写死在配置文件中；Web UI 中鉴权字段会按隐私字段存储（如token带privacy标签）。
3. HTTPS 自签名证书怎么办？使用ssl_ca_cert指定 CA 证书；仅在可信内网环境才考虑no_ssl_verify=True，生产环境不推荐关闭校验。
4. 同名工具冲突怎么办？连接器体系会自动按mcp__{server}__{tool}重命名避免歧义；overwrite_same_tool参数控制同名工具的覆盖行为。
5. MCP Server 连不上？可检查 SSE/Streamable HTTP 端点的netloc与scheme是否与连接地址一致——sse_client在收到endpoint事件时会做同源校验，不一致会直接报错（见 mcp_utils.py）。

延伸阅读

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT