HTTP MCP Server

VUILab 提供 Streamable HTTP 风格的 MCP endpoint，开发者可以通过 MCP 客户端或直接使用 JSON-RPC 请求调用开放平台能力。

Endpoint

• 接口路径：/mcp
• 示例 Base URL：https://api.vuilabs.cn/mcp
• 生产环境：将示例中的主机与端口替换为生产环境 VUILab 域名，例如 https://api.vuilabs.cn/mcp
• 请求方式：POST
• Content-Type：application/json

/mcp 无需登录。调用具体 tool 时，请通过 params.arguments.apiKey 传入开放平台 API Key。

支持的 MCP 方法

当前 HTTP MCP server 支持以下 JSON-RPC 方法：

方法	说明
initialize	初始化 MCP 会话，返回支持的能力与协议版本
notifications/initialized	客户端完成初始化后的通知
tools/list	查询当前可用 tools
tools/call	调用指定 tool

当前 Tools

Tool 名称	对应能力
text_to_speech_generate	同步文本转语音
text_to_speech_stream	流式文本转语音
diarize	说话人日志识别
voice_save	保存或更新自定义音色
voice_list	查询自定义音色列表
voice_delete	删除自定义音色

AI 语音通话接口当前不在 MCP tools 中，不能通过 /mcp 调用。请继续使用 AI 语音通话接口文档中的 HTTP API。

快速调用示例

下面示例可直接复制运行。建议先设置环境变量：

export MCP_URL="https://api.vuilabs.cn/mcp"
export API_KEY="your-secret-key-here"

initialize

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      }
    }
  }'

notifications/initialized

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }'

tools/list

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

text_to_speech_generate

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "text_to_speech_generate",
      "arguments": {
        "apiKey": "'"$API_KEY"'",
        "body": {
          "voice_id": "jingcheng",
          "generate_text": "你好，欢迎使用 VUI Labs MCP Server。",
          "model_id": "lunatts-0813",
          "language": "zh",
          "text_normalization": true,
          "emotion_class": "default",
          "speed": 1.0,
          "audio_format": "wav"
        }
      }
    }
  }'

text_to_speech_generate 和 text_to_speech_stream 的音频结果使用 MCP audio content 返回，data 是 base64，mimeType 是实际音频类型：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "audio",
        "data": "UklGRiQAAABXQVZFZm10IBAAAAABAAEA...",
        "mimeType": "audio/wav"
      }
    ],
    "isError": false
  }
}

保存音频时只需 base64 解码 result.content[0].data，不要把整个 JSON 响应直接保存为 WAV。

voice_list

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "voice_list",
      "arguments": {
        "apiKey": "'"$API_KEY"'"
      }
    }
  }'

voice_delete

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "voice_delete",
      "arguments": {
        "apiKey": "'"$API_KEY"'",
        "voice_id": "my-voice"
      }
    }
  }'

未知 tool 错误示例

curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "not_exists",
      "arguments": {
        "apiKey": "'"$API_KEY"'"
      }
    }
  }'

请求会返回 JSON-RPC 错误，错误码通常为 -32602，错误信息包含 unknown tool。

使用 jq 构造 JSON

curl 的 -d 内容必须是合法 JSON，JSON 不允许尾逗号。例如下面写法会触发解析错误：

{
  "jsonrpc": "2.0",
  "id": 1,
}

推荐使用 jq -nc 构造 JSON，避免手写引号、换行和尾逗号问题：

jq -nc --arg apiKey "$API_KEY" '{
  jsonrpc: "2.0",
  id: 7,
  method: "tools/call",
  params: {
    name: "voice_list",
    arguments: {
      apiKey: $apiKey
    }
  }
}' | curl -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -d @-

常见错误

错误	说明与处理方式
-32700 parse error	请求体不是合法 JSON。检查引号、括号、逗号，尤其是 JSON 尾逗号。
-32602 unknown tool	tools/call 中的 params.name 不在当前 tools 列表内。先调用 tools/list 确认名称。
接口未授权或无权限	检查 arguments.apiKey 是否传入、是否有效、账户是否有该接口权限，以及账户余额或套餐状态。
TTS 参数提示 is not allowed	先调用 tools/list 获取当前 schema；TTS 请求字段必须放在 arguments.body 中。
音频无法播放	确认读取的是 type: "audio" content，并对 data 做 base64 解码；不要把整个 JSON 响应保存为音频文件。