接入 AI Agent（MCP / Skill）

让 Claude、Cursor 等 AI Agent 直接操作事半AI：一行配置接入 MCP，用自然语言推线索、查数据、导出、改配置。

除了写代码调用接口，你也可以把事半AI直接接到自己的 AI Agent 上（Claude Desktop、Claude Code、Cursor 等支持 MCP 的客户端）。接好之后，对 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

Agent 能做什么

工具分两类：

内置工具（26 个）：直接对应接口文档里的能力——推送 / 上传 / 查询 / 撤销线索，创建项目、关联数字员工、启停、拨打配置，读写话术 / 音色 / 抽取配置，Webhook，线路与音色列表，项目统计等。

平台助手工具：和微信助手花花同一套能力，启动时从平台自动加载，平台上新增能力后 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 次