接入 AI Agent（MCP / Skill）

Claude、Cursor 等 AI Agent 通过 MCP 接入事半AI，以自然语言推送线索、查询数据、导出与修改配置。

除通过代码调用接口外，也可将事半AI直接接入 AI Agent（Claude Desktop、Claude Code、Cursor 等支持 MCP 的客户端）。接入后，向 Agent 发出"把昨天没接通的再打一遍""导出今天有意向的客户，带录音"等指令，Agent 将自动调用对应工具完成操作。

该能力由开源的 Agent Toolkit（npm 包 smartcall-agent-toolkit）提供，源码见 GitHub。

准备 API Key

在后台 API Key 管理 创建 Key，并按需勾选权限范围。Agent 的可执行范围由以下两项共同决定：

• Key 的创建人：Agent 以创建人身份操作，权限与其在网页端完全一致，包括可见的部门项目、企业是否开通协作项目、是否为只读角色等（见下方权限说明）
• Key 的权限范围：仅在创建人权限的基础上进一步收窄，不会扩大。例如仅勾选只读时，即使创建人为企业主，Agent 也只能查询、不能修改

配置 MCP

Claude Desktop：编辑 claude_desktop_config.json；Claude Code：编辑项目中的 .mcp.json 或 ~/.claude/mcp.json。两者内容相同：

{
  "mcpServers": {
    "smartcall": {
      "command": "npx",
      "args": ["-y", "smartcall-agent-toolkit"],
      "env": {
        "SMARTCALL_API_KEY": "sk_xxx"
      }
    }
  }
}

重启客户端后，让 Agent 执行一次 verify_auth，返回 Key 所属企业与权限范围即表示接入成功。

API 地址默认为 https://api.halfcall.cn，通常无需修改。

可选：安装 Claude Code Skill

Skill 是供 Claude 参考的使用说明（平台概念、常用流程与注意事项），安装后 Claude 调用工具更加准确。工具本身仍由上述 MCP 提供，因此需先完成 MCP 配置：

git clone https://github.com/halfcall/agent-toolkit.git ~/.claude/skills/smartcall

工具能力

工具分为两类：

内置工具（30 个）：与接口文档中的能力一一对应，包括推送 / 上传 / 查询 / 撤销线索，创建项目、关联数字员工、启停、拨打配置，读写话术 / 音色 / 抽取配置，Webhook，AI 呼入（开关、接听号码、来电预查），线路与音色列表，项目统计等。

平台助手工具：与微信助手花花能力一致，启动时从平台自动加载。平台新增能力后，Agent 下次启动即可使用，无需升级 Toolkit：

与内置工具重名的平台工具添加 platform_ 前缀（如 platform_list_voices）。平台助手工具的说明与返回内容为中文。

权限怎么算

与网页端一致：

• 企业：固定为 API Key 所属企业，Agent 不能切换至其他企业
• 项目范围：非企业主 / 管理员仅可操作本部门项目及未分配部门的项目
• 修改提示词 / 开场白 / 音色 / 数字员工功能 / 项目配置：企业需开通「协作项目」
• 更换线路 / 修改线路并发：企业需开通「协作线路」
• 角色限制：如外勤不能导出数据、财务仅可充值、只读管理员仅可查看

权限不足时，工具将返回具体原因（缺少的权限及开通方式），Agent 会直接转告用户。

直接调用（不使用 MCP）

如系统不使用 MCP，也可直接调用以下两个接口，所需权限因工具而异：

# 列出当前 Key 可用的工具（名称、说明、参数 JSON Schema、所需权限）
curl https://api.halfcall.cn/api/v1/external/mcp/tools \
  -H "Authorization: Bearer sk_xxx"

# 调用工具
curl -X POST https://api.halfcall.cn/api/v1/external/mcp/call \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "query_status", "arguments": {}, "sessionId": "my-session-1"}'

• sessionId：用于串联多步流程（如创建项目：new_project → confirm_step），同一流程请使用相同的值，24 小时内有效
• 返回的 data.message 为面向用户的结果说明；导出类工具另返回 downloadUrl
• 每个 API Key 每分钟最多调用 60 次