MCP 连接与配置
云擎数智 MCP 服务的连接方式与客户端配置
本文说明 云擎数智 MCP 服务的连接与配置。
前置条件
- 拥有有效的 API Key（
sk-xxx） - 网关已部署并暴露
/mcp端点 - 客户端支持 MCP Streamable HTTP
客户端配置
在 MCP 配置中添加：
{
"mcpServers": {
"yunsell": {
"url": "https://www.yunsell.com/mcp",
"headers": {
"Authorization": "Bearer sk-xxx"
}
}
}
}
| 字段 | 说明 |
|---|---|
mcpServers.yunsell | 服务键名，建议使用 yunsell |
url | 网关地址 + /mcp，须与 API Base URL 同源 |
headers.Authorization | Bearer + 你的 API Key |
将 sk-xxx 替换为你的 API Key。
会话管理
MCP Streamable HTTP 使用会话机制：
| 项 | 说明 |
|---|---|
| 首次请求 | 服务端在响应头返回 Mcp-Session-Id |
| 后续请求 | 客户端须在请求头携带同一 Mcp-Session-Id |
| 结束会话 | DELETE /mcp |
客户端 SDK 通常会自动管理会话。
鉴权说明
- 鉴权方式与 V1 API 完全一致
- 共享同一 API Key 的计费、限额、模型限制
- 管理员可在 Key 后追加
-{channelId}指定渠道（如sk-xxx-6）
鉴权失败返回 HTTP 401 / 403。
验证连接
配置完成后，通过 MCP 协议验证：
- 调用
tools/list，确认返回list_models、generate_image等 Tool - 调用
list_models，确认返回模型含supported_endpoint_types
若 Tool 列表为空或缺少预期 Tool，检查：
- API Key 是否有效、余额是否充足
- Token 是否限制了可用模型
- 模型是否支持对应
supported_endpoint_types
故障排查
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 连接失败 | URL 错误或网关未启动 | 检查 Base URL 与 /mcp 可达性 |
| 401 / 403 | Key 无效或 IP 不在白名单 | 检查令牌设置 |
| Tool 列表缺少图像/视频 | 无对应模型权限 | 调用 list_models 确认 supported_endpoint_types |
| 视频一直 queued | 上游排队 | 按 next_poll_after_sec 间隔轮询，避免频繁请求 |
| TTS 返回错误 | voice 无效 | 先调用 list_audio_voices 获取正确 code |