使用 MCP 模板为智能体实例按需生成连接
MCP 模板把一条连接中“所有实例都相同的规则”和“每个实例各自填写的值”分开。Server URL 结构、超时、TLS 和 Header 名称只需配置一次；创建智能体实例时，再填写该实例使用的访问凭证、工作区、客户或环境参数。智能体模板引用 MCP 模板后，智能体开发服务平台（AgentWorks）会根据这些值生成并保存一个实际可用的 MCP 实例，再让智能体实例使用该连接。
当同一种智能体需要按环境、区域、客户或工作区使用不同连接时，MCP 模板可以减少重复配置，并让生成后的连接分别管理。所有智能体实例都使用完全相同的连接时，直接使用 MCP 实例连接外部工具更简单。
什么时候使用 MCP 模板生成独立连接
先确认每个智能体实例是否真的需要不同的 MCP 连接值。所有智能体实例使用完全相同的 MCP 地址、Header 值和第三方 MCP 服务账号和凭证时，复用一个 MCP 实例更直接；只有地址或 Header 值需要随实例变化时，才需要 MCP 模板。
| 实际需要 | 更直接的选择 | 得到的结果 |
|---|---|---|
| 所有智能体实例使用相同地址、相同 Header 值和同一个外部账号 | 关联一个已有 MCP 实例 | 所有智能体实例复用同一条连接 |
| 每个智能体实例需要不同的地址、凭证或其他 Header 值 | 关联 MCP 模板 | 创建智能体实例时生成一条独立的 MCP 连接 |
连接值通常有两类差异：
| 需要变化的内容 | 适合开放的字段 | 直接收益 |
|---|---|---|
| 每位使用者或服务账号的 API Key | Authorization Header 值 | 各实例使用自己的外部身份，不必共用一个凭证 |
| 每个团队的工作区或租户 | X-Workspace-ID、X-Tenant-ID 等 Header 值 | 同一种智能体连接各自的工作区或客户数据 |
| 每个客户、区域或环境的入口地址 | URL 片段 | 复用地址结构，只在创建实例时填写变化部分 |
确认 MCP 实例何时生成
MCP 模板只保存创建连接所需的配置，本身不能直接供智能体调用。智能体模板保存对 MCP 模板的引用和参数映射；创建智能体实例时，AgentWorks 才用本次填写的参数替换模板中的可配置字段，并生成新的 MCP 实例。MCP 模板本身不会被改写。
同一份智能体模板可以用于创建 Agt-A、Agt-B 等多个智能体实例；每次创建时，平台分别生成与之配套的 MCP-A、MCP-B。生成后的 MCP 实例会持久保存，可以在 MCP 管理页面中单独检查和管理，彼此不会因为来自同一份 MCP 模板而自动联动。
创建 MCP 模板并保存共用连接设置
先填写名称以及各实例共用的连接设置。AgentWorks 在这里使用 Streamable HTTP；你需要决定的是 Server URL、超时、TLS 和 Header。操作账号需要有创建和管理 MCP 模板的权限。
打开新建 MCP 模板页面。
也可从左侧导航进入 MCP 管理，选择 MCP 模板，再选择 新建 MCP 模板。
填写 名称和 描述。
配置 超时时间:。
仅在受控测试环境按需启用 跳过 TLS 校验。
保持页面打开，再选择下面一种与实际需要相符的配置方法。
下面的 URL 和 Header 操作使用两份独立的示例 MCP 模板：第一份解释地址片段，第二份解释 Context7 凭证。不要把两个示例地址照搬到同一份模板中。只有实际 MCP Server 的地址和 Header 都会因实例而异时，才在同一份模板中同时使用两种方法。
让不同实例连接不同的 MCP 地址
当不同客户、区域或环境使用不同 MCP Server 入口时，把地址中确实会变化的 URL 片段设为可配置。模板继续保存固定的地址结构，创建智能体实例时只需填写本次连接使用的域名或路径。
以下地址专门用于说明 URL 配置方式，不能用于实际连接：
https://mcp.example.com/demo- 在 Server URL 中填写
https://mcp.example.com/demo。 - 在 URL 路径参数 中找到
demo。 - 只为
demo打开 可配置 开关。 - 确认域名
mcp.example.com保持固定，再选择 创建 MCP 模板。
注意
保存后为什么 Server URL 变了？
将 demo 设为可配置并保存后，重新进入编辑页面时，Server URL 显示为 https://mcp.example.com/$(param_1)，并已经把 demo 保存为 param_1 的默认值。这表示平台会在创建 MCP 实例时填入该参数，并不是连接地址被改坏了。未提供其他值时，生成的 MCP 实例仍使用 https://mcp.example.com/demo。
AgentWorks 会把 https:// 或 http:// 后面的域名和路径按 / 分段，并按位置为可配置的 URL 片段生成 param_0、param_1 等名称。在这个例子中：
mcp.example.com是第 0 段，保持固定。demo是第 1 段，因此生成名称是param_1。
保存 MCP 模板后，在详情页的 参数定义中确认名称为 param_1、Target 为 server_url.param_1、默认值为 demo。
提示
把 param_1 换成容易理解的参数名
将这个 MCP 模板添加到智能体模板时，可以把面向实例创建者显示的参数名改成 MCP_TENANT 等容易理解的名称。改名不会改变系统保存的目标路径；创建实例时填写的值仍会写入 server_url.param_1。
重要
只开放真正需要变化的字段
URL 可以被拆成多个字段，不表示每个字段都应该开放。固定使用 https://learn.microsoft.com/api/mcp 时，不需要把 learn.microsoft.com、api 和 mcp 都标记为可配置；直接使用一个 MCP 实例更简单。
让不同实例使用各自的凭证或 Header
当不同智能体实例连接同一个 MCP Server，但需要使用各自的 API Key、访问凭证、工作区或租户信息时，保持 Server URL 固定，只把相应 Header 的值设为可配置。这样可以维护一份连接规则，同时为每个智能体实例生成使用不同外部身份或工作区的 MCP 实例。
以下示例使用真实的 Context7 MCP Server：Server URL 固定为 https://mcp.context7.com/mcp，不同实例提供各自的 Context7 API Key。这样，同一份智能体模板可以交付给不同用户，而不必让所有人共用同一个外部凭证。
Context7 的标准 MCP 地址支持匿名访问；提供 API Key 可以获得更高限额，并在相应套餐中使用私有来源。
- 在 Server URL 中填写
https://mcp.context7.com/mcp，不要把 URL 片段标记为可配置。 - 在 Headers 中添加名称为
Authorization的 Header。 - 为
Authorization打开 可配置 开关。 - 将默认值留空，不要把真实的生产 API Key 保存为可供所有实例继承的默认值。
- 选择 创建 MCP 模板。
保存 MCP 模板后，在详情页的 参数定义中确认参数名称为 Authorization、Target 为 headers.Authorization，默认值为空。
注意
Context7 API Key 是否需要 Bearer
通过 /init 提供 Context7 API Key 时，建议将参数名改成 CONTEXT7_API_KEY，并直接填写原始 API Key。如果团队要求使用 Bearer ＜key＞ 格式，请在控制台创建智能体实例时填写。
平台仍会把这个参数的值写入 Authorization Header。Context7 同时接受原始 API Key 和 Bearer ＜key＞，但 /init 使用空格分隔参数，CONTEXT7_API_KEY=Bearer abc123 会被错误拆分；原始 API Key 不含空格，因此更不容易出错。
将 MCP 模板添加到智能体模板并命名参数
智能体模板是 MCP 模板参数与实例创建者之间的接口。在这里把 param_1 或 Authorization 等系统名称改成容易理解的参数名，创建智能体实例的用户和渠道用户才知道应该填写什么。
创建或编辑智能体模板，打开 插件配置。
单击 添加插件。
选择 MCP - 模板，再选择目标 MCP 模板。
在参数配置中检查 MCP 模板开放的每个字段。
把面向实例创建者显示的 参数名改成容易理解且在智能体模板中唯一的名称，例如
MCP_TENANT或CONTEXT7_API_KEY。重要
参数名也是实例创建接口的一部分
控制台创建智能体实例和渠道
/init都使用智能体模板中的参数名。如果保留param_1，用户看到的提示也会显示param_1。开放智能体模板前，把生成名称改成MCP_TENANT、REGION或CONTEXT7_API_KEY等有明确含义的名称。保留系统显示的 目标路径，例如 URL 示例中的
param_1或 Header 示例中的Authorization。名称用于解释输入，不会改变其目标路径。这里的目标路径保留 MCP 模板原来的参数名称，与 MCP 模板详情中的 Target 不是同一层字段。两者的关系参见核对参数名与目标路径的映射。
检查 参数值是否适合作为默认值。Context7 示例应保持为空，并要求创建实例时填写实际 Key，再保存智能体模板。
在智能体模板详情页的 插件 页签中确认 MCP 类型、名称和资源 ID。
核对参数名与目标路径的映射
需要确认实例创建者提供的值最终写入哪个 MCP 字段时，按下表核对各层名称：
| 界面位置和字段 | URL 示例 | Header 示例 | 实际作用 |
|---|---|---|---|
| 智能体模板：参数名 | MCP_TENANT | CONTEXT7_API_KEY | 创建智能体实例或执行 /init 时使用的清晰名称 |
| 智能体模板：参数值 | demo | 留空 | 没有覆盖参数时使用的默认值；凭证不应使用虚假占位值 |
| 智能体模板：目标路径 | param_1 | Authorization | 指向 MCP 模板原来生成的参数名称，保持不变 |
| MCP 模板详情：Target | server_url.param_1 | headers.Authorization | 表示平台最终把值写入 Server URL 还是 Header |
URL 片段使用以下映射：
MCP_TENANT=tenant-a
↓ 智能体模板中的目标路径
param_1=tenant-a
↓ MCP 模板中的 Target：server_url.param_1
https://mcp.example.com/tenant-aHeader 使用另一条映射：
CONTEXT7_API_KEY=ctx7sk-example
↓ 智能体模板中的目标路径
Authorization=ctx7sk-example
↓ MCP 模板中的 Target：headers.Authorization
请求发送到 https://mcp.context7.com/mcpctx7sk-example 只是格式示例，不是真实凭证。
为智能体实例提供 MCP 参数值
参数值可以由控制台中的实例创建者填写，也可以由模板绑定渠道的用户在首次 /init 时填写。两种入口都读取智能体模板中的参数名，再由 AgentWorks 映射到 MCP 模板字段。
在控制台创建智能体实例时填写
从智能体模板手动创建智能体实例时，在实例表单中检查所有可配置参数，并填写当前环境、客户或外部账号实际需要的值。创建完成后，平台同时生成该智能体实例使用的 MCP 实例。完整实例创建方法参见检查实例可配置参数。
实例创建表单显示智能体模板中定义的清晰参数名：
- URL 示例显示
MCP_TENANT，而不是param_1。 - Context7 示例显示
CONTEXT7_API_KEY，而不是只显示Authorization。
不同智能体实例可以在这里填写不同的值。对于访问凭证，优先由有权限的实例创建者在控制台中填写。
让模板绑定渠道的用户通过 /init 填写
渠道账号使用模板绑定时，渠道用户不直接操作 MCP 表单。飞书或 QQ 用户可以直接发送 /init；WebSocket 客户端把 /init 作为消息内容发送，并为同一用户保持稳定的 user_id，具体要求参见处理模板绑定。首次发送不带参数的 /init 后，AgentWorks 会返回当前智能体模板中所有可配置参数的名称、类型和默认值。例如，使用 URL 示例的智能体模板会返回：
用户：
/init
AgentWorks：
请提供以下参数后重新发送 /init：
- MCP_TENANT (string, 默认值: demo)
示例: /init MCP_TENANT=xxx下面两条命令分别对应本文的 URL 示例模板和 Context7 Header 示例模板，不表示同一个智能体模板必须同时要求这两个参数。
URL 参数示例：
/init MCP_TENANT=tenant-a这个示例只用于说明参数映射，不用于建立真实连接：
MCP_TENANT=tenant-a ───────→ param_1 ───────────────→ URL 中的 tenant-a
↓
生成 https://mcp.example.com/tenant-a 对应的 MCP 实例Header 参数示例：
/init CONTEXT7_API_KEY=ctx7sk-exampleCONTEXT7_API_KEY=ctx7sk-example ─────→ Authorization Header
↓
生成连接 https://mcp.context7.com/mcp 的 MCP 实例
↓
创建该渠道用户的智能体实例并保存用户绑定
↓
后续消息进入这个智能体实例ctx7sk-example 只是格式示例，不是真实凭证。如果有多个参数，只填写需要覆盖的 KEY=VALUE；其他参数使用智能体模板保存的默认值。参数名区分大小写，应以 /init 返回的名称为准。MCP_TENANT 和 CONTEXT7_API_KEY 都是模板创建者定义的示例名称，不是 AgentWorks 提供的配置值。
注意
通过 /init 提供实例参数值
/init 使用空格分隔 KEY=VALUE。值可以包含 =，但不能包含空格；需要填写含空格的完整 Header 值时，请改由有权限的实例创建者在控制台中填写。如果通过飞书、QQ 或 WebSocket 客户端传递生产密码、访问令牌或完整 Authorization Header，请保持谨慎：这些值会出现在发给 AgentWorks 的渠道消息正文中，并作为智能体实例参数保存。它们不会作为普通对话提示词发送给大语言模型；/init 由 AgentWorks 网关直接处理。
渠道用户身份用于消息路由和用户绑定，不会自动写入 MCP 参数，也不会自动换取外部 MCP Server 的个人凭据。生成了不同 MCP 实例，也不表示外部权限已经自动隔离。
模板绑定、用户绑定和实例生命周期的完整流程参见首次使用时创建专属实例。
提前从 MCP 模板生成实例
智能体模板直接引用 MCP 模板时，不需要预先手动创建 MCP 实例；平台会在创建智能体实例时自动生成。需要提前测试一组参数，或者希望先生成一个可供其他智能体模板复用的固定连接时，才在 MCP 管理 中从模板创建实例。
手动创建时，填写 实例名称和模板开放的 URL、Headers 参数。未开放的模板配置保持固定。实例生成后，打开实例详情并选择 测试连接；连接成功后，打开 工具页签，确认 工具列表显示该 MCP Server 实际提供的工具。连接失败或工具缺失时，先检查 Server URL、Header 值、平台网络和 TLS 配置。需要复用该连接时，在智能体模板中选择 MCP - 实例。
验证生成的 MCP 实例
创建智能体实例后，在 MCP 管理页面找到生成的 MCP 实例，并按本次配置检查对应结果：
- 配置了 URL 片段时，确认生成的 MCP 实例显示完整的实际地址，不再包含
$(param_1)等模板参数。 - 配置了 Header 时，确认 Server URL 保持固定，并显示预期的 Header 名称。Header 值默认隐藏。
实例详情还会保留其 来源 MCP 模板。先按测试工具发现确认连接和工具元数据，再按在智能体实例中验证工具执行一次真实调用。
不同工作区、区域或外部身份需要隔离时，至少使用两个不同参数值创建测试智能体实例，并分别核对生成的 MCP 实例及 MCP Server 实际收到的身份。名称不同或资源 ID 不同本身不能证明外部权限已经隔离。
管理 MCP 模板和生成的实例
根据模板生成的 MCP 实例会与直接创建的实例一起显示在 MCP 实例列表中。需要确认来源时，打开实例详情并查看 来源 MCP 模板。具体识别方法参见确认 MCP 实例的来源。
修改 MCP 模板后，编辑并保存由该模板准备连接的智能体实例，会按最新模板和实例参数重新应用 MCP 配置，并保留原 MCP 资源 ID。此前直接修改生成 MCP 实例的地址、Header 或其他配置可能被覆盖；需要长期保留的值应配置在来源模板或开放的实例参数中。
若智能体直接关联一个已有 MCP 实例，仍在该 MCP 实例上集中维护连接。变更后按维护 MCP 实例核对工具发现、外部身份和真实调用结果，不以保存成功代替验证。
删除 MCP 模板不会自动删除已经生成的 MCP 实例。删除前确认不再需要继续从该模板创建连接，并分别检查现有 MCP 实例、智能体模板和智能体实例引用。删除生成的 MCP 实例不会撤销外部凭证，也不会删除平台外运行的 MCP Server。
处理参数问题
/init显示param_1：智能体模板仍保留系统生成的参数名。编辑智能体模板，把 参数名改成有业务含义的名称；目标路径保持不变。- 渠道用户不知道应该填写什么：参数来自实际业务配置，例如工作区 ID、区域或客户编号，不是 AgentWorks 自动提供的值。开放渠道前，由模板创建者说明这些值的来源。
/init提示当前渠道不支持：渠道账号不是模板绑定。实例绑定渠道直接使用已经存在的智能体实例，不执行动态创建。- 不同用户生成的 MCP 实例仍具有相同权限：检查实际 Server URL、Header 和外部账号。不同实例如果使用相同凭证，MCP Server 仍会把它们视为同一身份。