概述
连接器 让 Buddy 通过 MCP（Model Context Protocol）接入外部工具，连接成功后，Buddy 可以在对话中直接调用这些外部工具，您无需在 DataBuddy 与外部系统之间反复切换，实现「对话即操作」。
连接器提供三类来源：
来源 | 说明 |
市场 | 平台预置的连接器，完成授权即可使用 |
自定义连接器 | 通过 JSON 配置接入任意 MCP Server，兼容标准 mcp.json 格式 |
工作空间共享 | 由工作空间管理员发布到本空间连接器市场的 MCP，空间内成员可见并自行连接 |
添加连接器时需要选择 访问方式 ：
访问方式 | 适用场景 | 支持的地址 |
公网访问 （默认） | MCP 服务有公网域名或公网 IP | HTTPS 公网地址 |
内网访问（VPC） | MCP 服务部署在您自己的 VPC 或 IDC 内（经云联网 / 专线接入 VPC），不暴露公网、数据不能出公网 | 私有 IP、内网域名，支持 http |
使用限制
限制项 | 说明 |
生效范围 | 单个工作空间 + 用户维度，即每个用户在每个工作空间下的连接器相互独立 |
生效场景 | 数据开发、数据分析等场景均生效 |
授权时效 | 跳转第三方授权需在 5 分钟内完成，超时需重新发起 |
共享连接器 | 管理员添加到市场后空间内所有成员可见；需要授权的连接器由成员自行授权连接，固定密钥等无鉴权连接器默认对所有用户启用 |
自定义连接器数量 | 每个用户在每个工作空间最多 100 个 |
共享连接器数量 | 每个工作空间最多 50 个 |
mcp.json 大小 | 不超过 1 MB |
操作步骤
进入连接器页面
1. 在 Buddy 左侧导航中打开 连接器·技能 目录，切换到 连接器 Tab。
2. 页面提供三个分类：
市场 ：浏览并选择平台预置连接器，支持按服务商分类查找。
工作空间共享 ：查看管理员发布到当前工作空间的共享连接器（仅在存在共享连接器时出现）。
已安装 ：管理已添加的连接器，标题上展示已安装数量。
3. 页面右上角支持 + 自定义连接器 与 添加共享连接器 （仅管理员可见）。
添加连接器
方式一：从市场添加
适用于使用平台预置的连接器：
1. 在 市场 中按服务商分类找到目标连接器，点击卡片打开详情弹窗。弹窗中展示连接器图标、名称、能力描述与典型场景，并提供连接。
2. 点击 连接 ，浏览器会新开标签页跳转到该服务方的授权页面完成授权。
3. 授权成功后自动跳回 DataBuddy，状态变为 已连接 ，弹窗提示授权成功。
4. 弹窗底部的 试试这样用 提供若干示例 Prompt，点击即可直接在对话中使用该连接器。
已连接的预置连接器可在同一弹窗中单击解绑 ；解绑后如需再次使用，重新连接即可。
方式二：添加自定义连接器
适用于所需 MCP Server 不在市场中时，通过 JSON 配置自行接入：
1. 单击右上角 + 自定义连接器 ，打开配置弹窗。若该 MCP 服务部署在您自己的 VPC 内，请将 访问方式 切换为 内网访问（VPC） 并完成网络设置（详见本页面的内网访问（VPC））；公网服务保持默认的 公网访问 。
2. 将 MCP Server 提供方给出的配置粘贴到
mcp.json 中（页面展示当前已配置内容）。未配置时的初始内容为：{"mcpServers": {}}
1. 单击 保存 。保存后系统自动加载该配置并尝试建立连接，已安装列表同步更新。
2. 如需返回列表，单击 返回 MCP 列表 。
说明：
请只使用您信任的 MCP Server；配置中的令牌、密钥属于敏感信息，服务端保存后请勿对外分享。
方式三：添加共享连接器（仅工作空间管理员）
适用于管理员将公司内部的 MCP 一次性配置给整个工作空间：
1. 在连接器页面点击 添加共享连接器 （仅管理员可见）。
2. 在弹窗中填写 名称 、 描述 与 MCP Server JSON 配置 ；如该 MCP 服务部署在 VPC 内，将 访问方式 切换为 内网访问（VPC） 并选择 VPC 与子网。点击保存。
3. 保存后该 MCP 发布至当前工作空间的连接器市场，归入 工作空间共享 分类，空间内所有成员可见。
说明：
管理员的操作是「发布到市场」。需要授权的连接器由成员自行完成授权连接；固定密钥、无鉴权等直连连接器默认对所有用户启用。共享连接器支持直连与 OAuth 2.0 两种配置形态，详见下文 mcp.json 配置说明。
mcp.json 配置说明
自定义连接器通过
mcp.json 描述 MCP Server，支持两种形态：形态 A 直连（自带 API Key / Token，保存后即可使用）与 形态 B OAuth 2.0 授权（每个用户用自己的账号授权）。通用规则
mcp.json 仅支持下表列出的字段，出现其他字段会直接报错（不会忽略）：层级 | 字段 | 必填 | 说明 |
根 | mcpServers | 必填 | 对象，至少包含 1 个条目 |
每个条目 | type | 必填 | 固定为 http |
每个条目 | url | 必填 | MCP Server 地址。公网访问需为 HTTPS 公网地址；内网访问可为私有 IP 或内网域名 |
每个条目 | headers | 可选 | Header 名到字符串值的映射，值必须为字符串 |
每个条目 | description | 可选 | 仅作备注，不会下发给 Agent |
每个条目 | auth | 可选 | OAuth 2.0 配置，见下方形态 B |
auth | type、clientId、clientSecret、authorizationUrl、tokenUrl、scope | - | type 固定为 oauth2；scope 为字符串数组 |
其他约束：
mcp.json 必须是合法 JSON，根节点为对象，大小不超过 1 MB，不允许重复字段与尾部多余内容。ServerName（
mcpServers 下每个条目的名称）只能由小写字母、数字与连字符组成，以字母或数字开头，最长 64 个字符。ServerName 不得与以下名称冲突，否则整批保存失败：以
databuddy- 开头的平台保留名、当前工作空间可见的预置或共享连接器名称、您本人已有的自定义连接器名称、同一次提交中的其他条目。一次提交多个条目时为整批校验：任一条目不合法，全部不保存。
鉴权形态由写法决定：有
headers 为静态 Header 鉴权；没有 headers 但有 auth 为 OAuth 2.0；两者都没有为无鉴权。建议不要同时写 headers 与 auth。形态 A：直连（无鉴权 / API Key / PAT）
适用于 MCP Server 不需要鉴权，或您已有长期有效的 API Key、Personal Access Token。保存后无需授权即可使用。
{"mcpServers": {"my-crm": {"type": "http","url": "https://mcp.example.com/crm/mcp","headers": {"Authorization": "Bearer <your-api-key>","X-Tenant": "acme"},"description": "CRM 查询"}}}
Header 使用说明：
所有 Header 值均视为敏感信息，保存时加密存储，后续任何查看方式都只返回掩码，不会回显明文。
对话调用时，Header 会原样随请求发送到该条目的
url，不会发送到其他连接器。数量与长度限制：最多 32 个 Header；单个值不超过 4096 字节；名与值合计不超过 16384 字节；值中不能包含换行符。
以下 Header 禁止使用（不区分大小写）：
Host、Cookie、Content-Length、Connection、Transfer-Encoding、TE、Trailer、Upgrade、Keep-Alive、Via、Forwarded、X-Real-IP、staffname、taiidentity，以及前缀为 Proxy-、X-Forwarded-、X-TC-、X-Tencent-、X-Rio-、X-Polaris- 的 Header。形态 B：OAuth 2.0 授权码
适用于需要每个用户用自己的账号登录、Agent 以该用户身份调用工具的场景。
{"mcpServers": {"my-gitlab": {"type": "http","url": "https://mcp.example.com/gitlab/mcp","auth": {"type": "oauth2","clientId": "<client-id>","clientSecret": "<client-secret>","authorizationUrl": "https://sso.example.com/oauth/authorize","tokenUrl": "https://sso.example.com/oauth/token","scope": ["api", "read_user"]},"description": "GitLab"}}}
您需要在自己的 OAuth 服务中准备：
项目 | 说明 |
回调地址（Redirect URI） | 固定登记为 https://databuddy.tencentcloud.com/mcp/auth ，不接受自定义 |
授权流程 | 标准授权码流程（Authorization Code）；仅凭 clientSecret 无法代替用户授权 |
authorizationUrl / tokenUrl | 公网访问时需为 HTTPS、443 端口的公网地址 |
clientSecret | 字段本身选填，但平台发起授权、获取 Token、撤销授权都依赖它，实际接入请务必填写 |
Refresh Token | 强烈建议签发。access token 过期后由平台使用 refresh token 续期；无法获取有效 Token 时连接器状态会变为凭证过期，需要用户重新授权 |
MCP 鉴权 | 对话时 Agent 以 Authorization: Bearer <access_token> 请求您的 MCP Server |
使用须知：
保存后状态为「待鉴权」，需点击 连接 完成授权后才能使用。
clientSecret 与授权后获取的 Token 由平台加密托管，任何界面都不会回显明文，请自行妥善保存密钥信息。修改
url、clientId、authorizationUrl、tokenUrl 或 scope 中任意一项，均视为定义变更：旧授权立即撤销，需要重新填写 clientSecret 并重新授权。仅修改 description 不影响已有授权。说明：
授权页面由您的浏览器直接打开，若只部署在内网，需您所在的办公网可访问该地址（专线 / VPN）。
共享连接器的配置要求
管理员添加的共享连接器同样使用
mcp.json 描述，配置要求如下：支持 形态 A（直连） 与 形态 B（OAuth 2.0） 两种配置形态。
需要授权的连接器（形态 B）由用户自行完成授权连接；固定密钥、无鉴权等直连连接器默认对所有用户启用。
每个工作空间最多 50 个共享连接器。
需要工作空间管理员权限（主账号或空间管理员角色）。
改写共享定义时，一次只能提交 1 个条目。管理员改写定义后成员需要重新授权；删除共享定义会同时清理全部成员的安装记录。
管理已安装连接器
在 已安装 列表中，每个连接器以卡片展示：图标 + 名称 + 工具启用数量（如「9/10 个工具已启用」）+ 状态指示，右侧提供 刷新 、 删除 与下拉菜单。
内网连接器卡片额外展示「内网」标签与所绑定的 VPC ID（如「连接正常 · 12/12 个工具已启用 · vpc-1a2b3c4d」）。
卡片可执行的操作：
操作 | 说明 |
展开 / 折叠 | 点击卡片头部或箭头，展开查看该连接器下的工具列表（工具名称与描述） |
启用 / 禁用开关 | 默认启用；禁用后该连接器在对话中不再被 Agent 调用 |
工具级启用 / 禁用 | 展开后在工具列表中逐个控制；禁用某个工具不影响连接器本身的连接状态 |
刷新 | 重新检测连接状态并刷新工具列表，刷新期间按钮显示加载态 |
网络设置 | |
删除 | 从已安装列表中移除该连接器 |
在对话中使用连接器
连接成功后，Buddy 会在对话中按需自动调用已连接、已启用的工具；涉及外部写入或敏感操作时，会先向您确认再执行。
如需在某一轮对话中明确指定连接器，可在输入框中通过
@ 选择该连接器，使用方式与 @ 其他对象一致，详见 Agent 基础能力中的 @ 能力说明。内网访问（VPC）
当 MCP 服务部署在您自己的 VPC 或 IDC 内（经云联网 / 专线接入 VPC）、不暴露公网且数据不能出公网时，可使用 内网访问（VPC） 。打通后，从 DataBuddy 到该 MCP 服务的整条链路都走腾讯云内网，数据不经过公网，且不会自动回落公网。
适用场景与限制
项 | 说明 |
适用对象 | 部署在 VPC 内、只有私有 IP 或内网域名的 MCP 服务 |
打通方式 | 在所选子网中创建弹性网卡打通网络，会占用 VPC 的私有 IP，请提前在子网中预留足够 IP |
绑定数量 | 一个连接器仅支持绑定 1 条网络连接，不跨连接器共享 |
地域 | 不支持跨地域 VPC 打通，跨地域请先通过云联网接入同地域 VPC |
授权页访问 | 第三方授权页由您的浏览器直接打开，若只部署在内网，需您所在的办公网可访问（专线 / VPN） |
操作步骤
步骤 1：添加连接器时选择内网访问（VPC）
在 + 自定义连接器 或 + 添加共享连接器 弹窗中：
1. 访问方式 选择 内网访问（VPC） ，弹窗展开网络设置。
2. 分别选择 VPC 与 子网 。下拉展示当前账号有权限的 VPC / 子网，支持刷新；如现有网络不合适，可点击文案中的「新建私有网络 / 新建子网」跳转控制台创建。
3. 单击保存 。
保存后的状态变化：
阶段 | 卡片展示 |
网络打通中 | 显示网络连接中加载标识，暂无 连接 按钮 |
网络打通完成 | 连接 按钮出现，状态为待鉴权，点击完成授权后即可使用 |
说明：
网络打通耗时约 3~5 分钟，期间内网访问不可用。
步骤 2：进入连接器网络设置页
在 已安装 列表中，点击内网连接器卡片右侧的下拉菜单 网络设置 ，进入「连接器网络设置」页。该页展示当前连接器的全部网络连接，包含 VPC 名称 / ID（附网段）、子网（ID、名称、网段、可用区）、状态、创建人、创建时间与操作（编辑 / 删除）。
当网络连接状态为「可用」（绿色）时，经由该网络连接的内网访问才可用；状态非「可用」时内网访问不可用。
步骤 3：新建网络连接
1. 单击右上角 + 新建网络连接 。
2. 在弹窗中选择 VPC 与 子网 （子网列表随所选 VPC 联动），单击确定。
3. 系统异步创建弹性网卡与网络代理，预计 3~5 分钟，完成后状态变为可用。
4. 在目标 MCP 服务的安全组中放行该子网网段的入站访问。
步骤 4：编辑网络连接
1. 在列表中单击网络连接的编辑 。
2. VPC 为只读，不支持更换；如需更换 VPC，请删除后重新新建。
3. 修改 子网 并保存，下方会展示该子网的 IP 总数与可用数量，可用 IP 不足时会拦截提交。
4. 保存后系统重建弹性网卡，状态为变更中，期间内网访问暂不可用，完成后自动恢复。
说明：
修改子网会使进行中的工具调用失败，建议在低峰时段操作；变更后请同步更新目标服务安全组放行的网段。
步骤 5：删除网络连接
1. 在列表中点击网络连接的 删除 ，在二次确认弹窗中点击确定。
2. 系统异步回收弹性网卡，期间状态为删除中，回收完成后从列表移除。
删除该连接器的全部网络连接后，连接器卡片显示网络不可用，对话中内网调用会失败并给出排查引导，不会自动回落公网。
验证结果
完成上述操作后，您可以通过以下方式确认：
1. 已安装 列表出现该连接器，状态指示为绿色正常。
2. 展开卡片可看到该连接器提供的工具列表与启用数量。
3. 在对话中提出相关诉求，Buddy 思考过程中出现调用该连接器工具的记录，并基于返回结果作答。
4. 内网连接器还需确认：连接器网络设置页中网络连接状态为可用，且卡片展示内网标签与所绑定的 VPC ID。
常见问题
Q：连接失败怎么办？
卡片会自动展开错误信息。建议先点击 刷新 重试；若持续失败，请确认 MCP Server 地址与令牌是否正确、网络是否可达，并联系该 MCP 服务提供方。
Q：授权页面超时了如何处理？
授权需在 5 分钟内完成，超时后连接器回到未连接状态，重新点击 连接 发起授权即可。
Q：禁用和删除有什么区别？
禁用后连接器仍保留在已安装列表中，随时可重新启用；删除则从列表中移除，需要重新添加配置。
Q：管理员已经添加了共享连接器，为什么我还不能用？
管理员添加只是将其发布到工作空间连接器市场。若该连接器需要授权（OAuth 2.0），您需要在 工作空间共享 分类中找到它并自行点击连接完成授权后才能使用；若为固定密钥、无鉴权等直连连接器，则默认已为您启用，无需额外操作。
Q：保存 mcp.json 时提示字段不合法怎么办？
mcp.json 只接受本文档列出的字段（见 通用规则），出现其他字段会直接报错。请检查是否出现了多余字段、ServerName 是否与保留名或已有连接器重名；一次提交多个条目时，只要有一条不合法就整批不保存。Q：修改了 OAuth 配置后为什么需要重新授权？
修改
url、clientId、authorizationUrl、tokenUrl 或 scope 中任意一项都属于定义变更，旧授权会被立即撤销，需要重新填写 clientSecret 并重新授权。仅修改 description 不会影响已有授权。Q：修改 JSON 配置后会立即生效吗？
会。保存后系统自动重新加载配置并更新「已安装」列表，无需重启。您也可以点击卡片上的 刷新 手动检测最新状态。
Q：某个连接器不可用时，会影响其他连接器吗？
不会。单个 MCP Server 不可达只影响其自身，其他连接器仍可正常使用。
Q：我的 MCP 服务只有内网地址，可以添加吗？
Q：删除网络连接后，连接器会自动改用公网访问吗？
不会。内网连接器删除网络连接后显示「网络不可用」，不会自动回落公网；如需恢复，请在网络设置中重新新建网络连接。
Q：内网连接器的网络可以多个连接器共用吗？
不可以。网络连接按连接器维度绑定，一个连接器仅支持 1 条网络连接，不同连接器需各自打通。
