工具与技能

Cappy Agent 使用工具读取上下文、查询数据和生成分析结果。需要访问其他系统时，可以添加 MCP 服务器；需要复用分析方法时，可以编写技能。

你也可以启用 Cappy MCP，让其他助手使用项目中的数据与上下文，或连接 Slack，让团队直接在频道中提问。

内置工具复制锚点链接

Agent 会根据问题选择工具，通常无需在提问中指定工具名。对话中的工具调用会展示它读取了什么、执行了哪些查询，以及返回了什么结果。

search 查找的是项目文件。Python、沙箱、语义层等工具是否可用，取决于项目配置和实例提供的运行环境，见项目能力。查询、结果和图表的使用见对话，报表操作见报表。

MCP 服务器复制锚点链接

MCP（Model Context Protocol）服务器可以把 Metabase、内部 API 或其他系统的工具提供给 Cappy。服务器定义保存在项目的 agent/mcps/ 中，每个 JSON 文件声明一个服务器；项目管理员在设置中连接服务器，并选择允许 Agent 使用的工具。

配置服务器复制锚点链接

下面以接入一个提供 Metabase 工具的远程 MCP 服务为例。示例地址代表团队实际运行的 MCP 端点，不是 Metabase 网页地址。

{
  "transport": "streamable-http",
  "url": "https://mcp.example.com/metabase",
  "headers": {
    "Authorization": "Bearer ${METABASE_MCP_TOKEN}"
  }
}

{
  "command": "/absolute/path/to/mcp-server",
  "args": [],
  "env": {
    "METABASE_URL": "https://metabase.example.com",
    "METABASE_API_KEY": "${METABASE_API_KEY}"
  }
}

Cappy 如何加载 MCP 工具复制锚点链接

连接时，Cappy 从服务器取得工具列表，为每个启用的工具生成一份 OpenAPI JSON 描述。下面的 my-project 表示你的项目文件夹，tool-name.json 表示按实际工具名称生成的文件：

my-project/
└── agent/
    └── mcps/
        ├── metabase.json
        └── metabase/
            └── tool-name.json

Agent 按需使用 list、read 和 grep 查找工具，读取 agent/mcps/metabase/ 中的描述，再通过 mcp_call 传入服务器名、工具名和参数。工具描述在连接时生成，无需手工编写；项目中需要维护的是 metabase.json 等服务器配置文件。

例如，上面的提问需要先找到报表列表或搜索工具，读取其参数定义，再把“销售分析”等条件传给该工具。并非每次对话都把所有服务器的完整工具定义加载进去。

个人授权复制锚点链接

远程服务要求 OAuth 时，每位使用者连接自己的账号，后续调用使用该账号在外部系统中的权限。在对话中首次需要这个服务时，Cappy 会显示连接操作；完成浏览器授权后继续处理问题。

项目管理员完成自己的授权，不会替其他成员授权。静态认证头则使用配置中的共同凭据，不是个人 OAuth；应根据外部服务的认证要求选择。

管理服务器与工具复制锚点链接

设置页显示连接状态、已启用工具数量，以及工具描述文件的位置。已连接表示最近一次连接成功；已缓存表示已有工具描述，但本次尚未重新连接；需要 OAuth 时还会显示授权状态。修改服务或认证配置后，重新连接以取得当前工具列表。

管理员可以关闭整个服务器，也可以展开后按只读、写入、删除或未知分类管理工具。这些分类根据工具名称推断，选择前仍应查看工具说明。被关闭的工具不会提供给 Agent，调用时也会检查禁用状态。

配置无法读取时，检查 JSON 与字段；连接失败时查看显示的错误，核对端点、网络与认证。服务器名称已出现但没有发现工具时，尚不能据此判断工具可以使用。

技能复制锚点链接

技能用于复用一套分析方法。每个技能在 agent/skills/ 下有自己的目录，其中的 SKILL.md 以 YAML frontmatter 开头，提供 name 和 description，后面写具体步骤。

例如，创建 agent/skills/top-customers/SKILL.md，用于查找付款总额最高的五位客户：

---
name: top-customers
description: 按付款总额查找前五位客户，并展示金额与占比。
---

# 查找付款总额最高的客户

1. 按 RULES.md 中的指引，找到客户、付款及付款金额的已有定义。
2. 确认分析时间范围、币种和有效付款状态；缺少必要条件时先向用户提问。
3. 按客户汇总付款总额，按金额降序取前五位。
4. 在同一时间范围、币种与有效付款条件下，计算每位客户占全部付款总额的比例；总额为零时说明占比无法计算。
5. 展示客户名称、付款总额、占比与查询 SQL，并说明使用的时间范围和筛选条件。

name 用于标识技能，description 帮助 Agent 和使用者判断何时使用。正文引用已有指标与规则，不必在技能中重复维护一份业务定义。每个技能使用独立目录，入口文件名必须是 SKILL.md；附加说明和脚本可放在同一目录中。

按更新上下文发布文件后，在新对话输入框键入 /，选择 top-customers，再补充本次要求：

查找今年第一季度付款总额最高的五位客户，按人民币统计。

Agent 会结合技能步骤与当前问题查阅定义、执行查询并展示结果。即使没有手动选择技能，Agent 也可以根据名称和描述查阅适合当前问题的技能。希望本次使用某项技能时，在输入框中明确选择它。

技能不会更改项目、工具或数据库账号的访问权限。看不到新增技能时，检查文件是否位于当前运行项目的 agent/skills/ 中，以及修改是否已经发布。

Cappy MCP复制锚点链接

Cappy 也可以作为 MCP 服务器，让其他助手调用你的分析项目。这一节配置的是外部客户端如何访问 Cappy；前面的 MCP 服务器配置用于 Cappy 访问外部工具。

选择模式复制锚点链接

在项目设置 → MCP 服务器 → Cappy MCP中启用 MCP 端点，再选择一种模式或同时开启两种：

希望沿用 Cappy 的完整分析流程时，选择子智能体模式；希望外部助手自行组织查询时，选择上下文层模式。任一模式开启后，也会提供图表、地图及报表管理工具，实际可用范围仍取决于项目配置和调用者权限。

连接客户端复制锚点链接

取得当前项目的端点复制锚点链接

在 Cappy MCP → 连接指南中复制端点 URL。它包含项目 ID，例如：

复制代码

https://cappy.example.com/mcp/<projectId>

使用页面给出的完整地址，替换示例域名与项目 ID。多项目账号需要通过该地址明确选择项目。

配置客户端并授权复制锚点链接

在连接指南中选择使用的客户端，按对应说明填写配置。支持 OAuth 的客户端可以使用端点 URL，并在浏览器中登录 Cappy、完成授权。例如，使用 mcpServers 结构的 HTTP 客户端配置为：

复制代码

{
  "mcpServers": {
    "cappy": {
      "type": "http",
      "url": "https://cappy.example.com/mcp/<projectId>"
    }
  }
}

具体配置结构以该客户端为准。需要静态 Bearer 认证时，连接指南可以填入当前登录会话的 Token；它不是单独签发的 MCP API 密钥，也不能用个人 API 密钥替代。会话失效后需要重新取得有效凭据，复制的配置也应按凭据保管，不提交到仓库。

如果外部工具要求预先登记 OAuth Client ID 和 Client Secret，项目管理员可以在已连接的应用中添加客户端，填写重定向 URI 并选择机密客户端。Client Secret 仅在创建后显示一次。

提问并查看结果复制锚点链接

连接后，在外部助手中提出一个小范围分析问题，例如：

请通过 Cappy 查询上个月各地区的销售额，并说明统计时间范围。

子智能体模式下，检查返回的回答与 Cappy 对话链接；上下文层模式下，检查客户端调用的上下文读取、SQL 和返回数据。项目管理员也可以在 Cappy MCP 页面的最近的 MCP 调用中查看调用与错误。

调用以授权账号的身份进行，该账号需要当前项目的访问权限。连接成功但调用被拒绝时，检查授权身份与目标项目。

Slack复制锚点链接

Slack 机器人使用项目中的上下文和能力回答问题，结果在线程中展示，并提供完整 Web 对话的链接。每个项目维护自己的 Slack 配置。

配置 Slack 应用复制锚点链接

项目管理员打开项目设置 → IM 集成 → Slack。根据网络条件选择连接方式：

创建应用复制锚点链接

选择传输方式，填写机器人提及名称，点击创建 Slack 应用。Cappy 会生成对应的 Slack App manifest，包含消息事件、所需权限、交互配置及 /new 命令。

Webhook 模式需要确认生成的回调地址可以被 Slack 访问。Socket Mode 不需要公开的入站地址，但仍需要 Cappy 能连接 Slack。

安装到工作区复制锚点链接

在 Slack 应用设置中打开 Install App，选择 Install to Workspace 并授予权限。

在 OAuth & Permissions 中复制 Bot User OAuth Token，通常以 xoxb- 开头。

填写凭据并保存复制锚点链接

将 Bot Token 填回 Cappy，根据所选模式补充另一项凭据：

• Webhook：从 Slack 应用的 Basic Information 中取得 Signing Secret。
• Socket Mode：确认 Slack 应用已启用 Socket Mode，在 Basic Information 中创建具有 connections:write 权限的 App-Level Token，通常以 xapp- 开头。

保存后，页面会显示已配置的应用与传输方式；在设置中选择机器人回答问题所用的模型。

加入频道并提问复制锚点链接

在 Slack 频道中邀请机器人，例如：

复制代码

/invite @cappy

然后提问：

复制代码

@cappy 上个月销售额最高的五种产品是什么？

在它的回复线程中继续问：

复制代码

再按地区拆分。

检查回复中的结果与完整对话链接，确认分析使用了预期项目的数据。

账号与回复方式复制锚点链接

发送者的 Slack 邮箱需要匹配一个有项目访问权限的 Cappy 账号。项目管理员可以在从 Slack 自动创建用户中启用自动创建，并填写允许的邮箱域名；符合条件的新成员首次使用时会取得项目访问权限，新账号会收到登录信息。保持关闭时，需要提前准备账号和项目授权。

默认情况下，在频道中首次 @ 机器人后，它会继续回复该活跃线程中的后续消息。开启仅在被 @ 时回复后，需要明确提及机器人。即使只在被提及时回复，机器人也会读取线程中的相关人类消息作为上下文，因此可以先讨论，再请它查询数据。

也可以直接向机器人发送私聊消息，无需每次 @。需要重新开始时，在私聊中发送 /new；发送 /new 你的问题 可以为新问题创建独立线程。后一种形式也可用于私有频道。

没有回复时，先检查机器人是否已加入频道，再查看连接方式与凭据、发送者邮箱是否匹配，以及是否有项目访问权限。需要调整 Slack 回答方式时，可以配置系统提示词。