自建应用接入 Skill 与 MCP
创建自己的能力,通过自建应用配置授权、绑定账号,并验证实际调用。
这条流程分为五步:准备能力 → 加入自建应用 → 配置授权 → 为能力选择账号 → 实际调用。连接成功只表示账号凭据已保存,不能代替最后两步。
1. 准备能力
Skill
在目标工作空间的资源库中,选择一个属于该工作空间且有编辑权限的库,使用 新建 → 技能。可以手动填写 SKILL.md,也可以从 Git 导入。
需要读取账号凭据的 Skill,应在 SKILL.md 开头声明 requires_credential: true,并说明它读取的环境变量。以调用 CNB CLI 的技能为例:
---
name: cnb-issue-reader
requires_credential: true
credential_hint: 使用具有目标仓库读取权限的 CNB Token,通过 CNB_TOKEN 注入
commands:
- cnb
network:
- api.cnb.cool
---
使用 cnb 命令读取用户指定的 Issue,凭据从 CNB_TOKEN 环境变量读取。commands 声明的是运行环境中需要存在的命令,不会替你安装 CLI。运行该示例前,需要确认沙箱已安装 cnb,并支持从 CNB_TOKEN 读取凭据。技能信息中的“需要配置”只是提示,不能替代上述声明。
创建后打开技能详情,确认首个版本已创建、扫描通过、默认版本正确,并启用技能。Git 导入成功或扫描通过不代表技能已经启用。后续版本仍在同一份技能详情中维护。
自建应用只能添加同一工作空间的能力。组织个人资源库或其他工作空间中的技能不一定满足此条件;创建时先选对所属库。
MCP
MCP 通过独立入口管理,不显示在普通资源目录中。在 应用中心 → 自建应用 → 应用能力 → 添加能力 中选择 MCP,再点击 注册新的 MCP 服务,填写名称、HTTPS 地址和所属资源库;也可以选择已有 MCP。
需要账号的服务选择“每人用自己的账号”或“团队共用”。注册表单只保存服务信息,账号凭据通过后续的“连接账号”填写。注册时可能因尚未绑定账号而拉取工具失败,完成第 3、4 步后再刷新工具清单。
如果服务已注册但添加能力失败,在当前表单再次保存只会重试添加;关闭表单后也能从已有 MCP 中继续选择,无需重复注册。
2. 加入自建应用
由工作空间管理员在 应用中心 创建或打开自建应用,进入 应用能力 → 添加能力。
- Skill:选择所属资源库,再选择技能;无需复制资产 ID。
- MCP:从当前工作空间已有服务中选择,或在此注册新服务。
应用已包含的能力不会再次出现在添加列表。要修改它,请使用能力行的编辑入口。添加后还需安装、启用应用,并勾选要供当前工作空间使用的能力;添加记录本身不会完成这些步骤。
3. 配置授权
自建应用的 编辑应用 中需要启用访问令牌或 OAuth。尚未开启时,添加能力表单提供 配置应用授权 入口。
| 授权方式 | 需要准备 |
|---|---|
| 访问令牌 | 外部平台签发、权限范围符合任务的 Token;在“连接账号”中保存 |
| OAuth | 正确的授权端点、Token 端点及权限范围;在应用的“自带授权应用”中配置可用的客户端,然后连接账号 |
Skill 还需要填写环境变量配置。例如,技能读取 CNB_TOKEN 时填写:
{"token_env":"CNB_TOKEN","static_env":{}}这里只声明变量名,不填写令牌值。MCP 使用服务所需的认证方式,由应用的连接提供凭据;服务要求自定义认证头时,还需在应用配置中设置匹配域名和认证头规则。
4. 为每项能力选择账号
打开应用的账号页签,点击 连接账号。完成后返回 应用能力,在需要授权的能力旁选择这条账号。
| 模式 | 谁配置账号 | 运行时使用谁的权限 |
|---|---|---|
| 每人用自己的账号 | 每位使用者分别授权并绑定 | 当前使用者所绑定账号的权限 |
| 团队共用 | 工作空间管理员选择共享账号 | 被选中的共享账号权限 |
即使只有一个账号,也要明确绑定。账号出现在“我的连接”里、用于某个数据源,均不代表它已经绑定到应用能力。
绑定后,能力行会回显当前账号。连接过期时保留原绑定的展示,并提示原因;使用 处理连接 进入账号页重新连接,或选择另一条有效账号。共享连接失效时由管理员处理。
MCP 完成绑定后,点击能力名称打开详情,刷新工具清单,检查服务状态、工具及其运行权限。
5. 验证实际调用
在同一工作空间的新一轮普通对话中,明确指定应用名称、能力以及一项可核对的读取任务。例如,要求使用刚配置的应用读取一个自己有权限访问的 Issue,并返回标题与链接。检查执行记录中是否出现了对应工具,是否成功返回指定资源;仅有模型生成的回答不能证明调用成功。
当前不同入口的支持范围如下:
| 能力或入口 | 使用条件 |
|---|---|
| 普通对话中的 MCP | 应用与能力启用、账号可用、服务就绪,且目标工具允许自动运行 |
| 普通对话中的 CLI 型 Skill | 技能启用且有默认版本,声明 commands 或 requires.bins,运行环境安装对应 CLI,账号和环境变量配置正确,能力允许自动运行 |
| 普通对话中的纯说明型 Skill | 不会仅因加入应用就自动成为可调用工具 |
| 当前智能体运行入口 | 尚未接入自建应用的动态 Skill / MCP;不能用“已添加应用”作为运行已支持的依据 |
需要审批或已禁用的能力不会出现在当前普通对话的自动工具目录中。不要为了排查而直接放开所有工具,应根据具体任务配置运行权限。
应用内如何管理 Skill
| 操作 | 入口与影响 |
|---|---|
| 添加、移除 | 应用能力列表;移除解除应用引用及相关绑定,不删除技能资产 |
| 启停应用中的能力 | 能力行开关;影响该应用或当前工作空间对它的使用 |
| 查看内容、修改信息 | 点击能力名称,打开原技能详情;编辑受技能本身的权限控制 |
| 新建版本、切换默认版本、比较版本、Git 同步 | 原技能详情的版本管理;应用引用同一资产,不另存一套版本 |
| 启停或删除技能资产 | 原技能详情;影响所有引用它的地方,与移除应用中的能力不同 |
更新技能的默认版本后,需要重新确认声明、账号配置及实际调用结果;一次成功调用不能证明后续版本也可用。
遇到问题
| 现象 | 处理 |
|---|---|
| 找不到刚创建的能力 | 核对工作空间和资源库;已加入应用的能力直接在列表中编辑 |
| 无法打开或编辑能力详情 | 核对资产是否存在及其查看、编辑权限;工作空间管理员身份不替代资产权限 |
| 应用未配置授权 | 在添加能力表单点击“配置应用授权” |
| 账号已连接,能力仍提示未授权 | 返回能力行选择账号,完成绑定;共享模式由管理员选择 |
| 连接失效或授权范围不足 | 点击“处理连接”,修复原连接或重新授权所需范围,再检查绑定 |
| MCP 拉取工具失败 | 先确认应用安装、能力勾选和账号绑定,再刷新工具;按详情中的具体错误排查地址与权限 |
| 对话中找不到 CLI 技能 | 检查默认版本、启用状态、命令声明、运行权限及沙箱是否安装对应命令 |
| 能力可调用但外部请求被拒绝 | 核对所绑定账号、Token 范围以及目标资源的外部权限 |