Wixzel Voice

wixzel-voice-mcp

面向 AI Agent 的 Wixzel Voice。 一个 Model Context Protocol 服务，让 Claude Code、claude.ai、Claude Desktop、Cursor 及其他 MCP 客户端能够创建语音 Agent、连接运营商、拨打电话、运行营销活动并查看费用，使用的是 Wixzel Voice API。

Wixzel Voice：面向 AI 语音 Agent 的 API。一个 API 密钥，一个余额，适用于所有语音引擎。

每个 API 操作对应一个工具，共 56 个，每个工具都带有注释，方便客户端了解哪些工具是只读的、哪些会删除数据，以及哪些会花钱或让真实电话响起。三个提示词（quickstart、diagnose_call、spend_report）封装了常见工作流。

该项目曾以 wixzel-phone-mcp 的名称发布至 0.3.0，当时产品短暂命名为 Wixzel Phone。这些版本仍可正常使用：api.phone.wixzel.com 和 mcp.phone.wixzel.com 仍在提供服务。

有两种运行方式：

	位置	身份验证
托管，https://mcp.voice.wixzel.com/mcp	Wixzel 的服务器	从客户端通过 OAuth 登录，或使用 Bearer 密钥
本地，npx -y wixzel-voice-mcp	你的计算机，stdio	环境中的 WIXZEL_API_KEY

控制台的 AI 客户端页面 voice.wixzel.com/connect 会生成下面所有命令，并自动填入密钥。

Claude Code

# hosted: sign in with your Wixzel account when Claude Code asks (/mcp → Authenticate)
claude mcp add --transport http wixzel-voice https://mcp.voice.wixzel.com/mcp

# local: a scoped key from the console
claude mcp add wixzel-voice -e WIXZEL_API_KEY=wv_live_... -- npx -y wixzel-voice-mcp

或者提交 .mcp.json，让每位协作者都能使用：

{
  "mcpServers": {
    "wixzel-voice": {
      "command": "npx",
      "args": ["-y", "wixzel-voice-mcp"],
      "env": { "WIXZEL_API_KEY": "${WIXZEL_API_KEY}" }
    }
  }
}

然后：

/mcp__wixzel-voice__quickstart

claude.ai 和 Claude Desktop

设置 → 连接器 → 添加自定义连接器 → https://mcp.voice.wixzel.com/mcp → 连接。登录控制台，勾选允许客户端执行的操作，客户端随后会获得自己的受限密钥。你可以随时在控制台的“AI 客户端”页面断开连接。

Cursor、Windsurf、VS Code 等

配置方式与上面的 .mcp.json 相同：命令为 npx，参数为 ["-y", "wixzel-voice-mcp"]，环境变量为 WIXZEL_API_KEY。通过 HTTP 连接但不支持 OAuth 的客户端，可通过 Authorization: Bearer wv_live_... 发送密钥。

Agent 能做什么

类别	工具
引擎	list_engines
Agent	list_agents get_agent create_agent update_agent delete_agent
通话	place_call list_calls get_call get_call_transcript hangup_call delete_call
呼叫方	list_callers get_caller update_caller
会议	connect_meeting_integration get_meeting_integration delete_meeting_integration join_meeting list_meetings get_meeting leave_meeting
SIP 中继	list_sip_trunks get_sip_trunk create_sip_trunk update_sip_trunk delete_sip_trunk check_sip_trunk_status test_sip_trunk get_sip_trunk_logs
电话号码	list_phone_numbers get_phone_number create_phone_number update_phone_number delete_phone_number
潜在客户	list_leads get_lead create_lead update_lead delete_lead import_leads
活动	list_campaigns get_campaign create_campaign start_campaign pause_campaign delete_campaign
知识库	list_knowledge_bases get_knowledge_base create_knowledge_base import_knowledge_base import_knowledge_file update_knowledge_base delete_knowledge_base list_knowledge_files add_knowledge_file get_knowledge_file delete_knowledge_file
MCP 服务	list_mcp_servers get_mcp_server create_mcp_server update_mcp_server delete_mcp_server refresh_mcp_server connect_mcp_server_oauth
工具	list_tools get_tool create_tool update_tool delete_tool test_tool
语音	list_voices get_voice preview_voice create_voice_clone update_voice delete_voice
预约	list_appointments get_appointment create_appointment update_appointment delete_appointment
账单与用量	get_balance list_ledger_entries create_topup get_usage_summary list_usage_events
API 密钥	list_api_keys create_api_key rotate_api_key revoke_api_key

提示词：quickstart（连接运营商、注册号码、构建 Agent、拨打首通电话）、diagnose_call（通话 X 为什么失败）和 spend_report（本月花费是多少，花在了哪里）。

资源：wixzel://guide（服务也会作为指令发送的操作指南）和 wixzel://connection（基础 URL，以及密钥是正式密钥还是测试密钥；绝不会包含密钥本身）。

如何确保 Agent 行为可靠

• 费用明确。 place_call、start_campaign、create_topup 和 create_voice_clone 均标注了 openWorldHint: true，其说明会告知模型先向用户确认。会根据注释进行拦截的客户端会在执行前征求确认。
• 自动实现幂等。 两种涉及费用的操作都需要 Idempotency-Key；服务会为每次调用生成一个密钥，并接受显式传入的 idempotency_key 以便有意重试，因此网络超时绝不会导致重复拨打。
• 错误信息可供处理。 每次失败都会返回 API 的机器可读 code、request_id，以及说明应采取何种操作的提示：缺少哪个权限范围、余额不足，或游标格式错误。
• 自动处理速率限制。 遇到 429 时，会根据 Retry-After 最多重试两次，然后才将错误返回给模型。这些请求不会产生费用。
• 权限范围负责控制访问。 密钥决定哪些操作可用。没有管理员权限范围，而且密钥无法创建权限范围比自身更广的密钥。
• 密钥始终安全。 SIP 密码只能写入，不能读取；API 密钥的密钥值只会在工具结果中显示一次，不会出现在其他地方。此服务使用的密钥绝不会通过任何工具或资源暴露。

自行运行托管模式

npx wixzel-voice-mcp --http 3939

变量	用途
MCP_PORT	端口。默认为 3939；--http <port> 会覆盖此设置。
MCP_BIND	网络接口。默认为 127.0.0.1；请在前置位置终止 TLS，而不要绑定到更广的地址。
MCP_PUBLIC_URL	客户端使用的 URL，例如 https://mcp.voice.wixzel.com/mcp。此 URL 会作为 OAuth 资源公布。
WIXZEL_API_BASE_URL	API，同时也是 OAuth 授权服务器。默认为 https://api.voice.wixzel.com。
WIXZEL_API_VERSION	可选的 Wixzel-Version 日期固定值。
WIXZEL_API_KEY	Stdio 模式：密钥。HTTP 模式：不带 bearer 的请求所用的回退密钥，仅当 MCP_PUBLIC_URL 是环回地址时才接受。

每个请求的 bearer 都会成为一个全新的一次性 MCP 服务的 API 密钥；请求之间不会共享任何内容。不带 bearer 的请求会收到带有 WWW-Authenticate: Bearer resource_metadata="…" 的 401 响应，而 /.well-known/oauth-protected-resource 会将 API 指定为授权服务器，连接器可据此自行发现登录方式。GET /healthz 会报告服务是否正常运行。

开发

源代码镜像位于 wixzel-voice-sdks；项目在包含 API 的私有单体仓库中开发，因此端点变更会与对应的工具变更一同提交。

npm install                # at the repo root
npm test -w apps/mcp       # offline: a fake API behind in-memory and HTTP transports, plus a spec-coverage check
npm run build -w apps/mcp
npm run inspect -w apps/mcp   # MCP Inspector against the built server

工具架构由手写的 zod 定义。规格覆盖测试会双向比对这些架构与 API 的 OpenAPI 文档（docs/openapi.json），因此，若 API 新增了端点，在为该端点添加工具之前，此处的构建就会失败。

不适用于应用代码

此服务面向 AI Agent。应用代码应使用 SDK： npm 上的 wixzel-voice 和 pub.dev 上的 wixzel_voice。

许可证

MIT。Wixzel Voice 本身是一项托管服务；条款请参阅 voice.wixzel.com。