接入指南
MCP 接入指南
远程 MCP Server（Streamable HTTP）：Cursor / Claude Code 等 agent 零本地运行时直连，一段配置即用
MCP 接入指南
HAiNA 提供远程 MCP Server（Streamable HTTP 协议）——Cursor、Claude Code、Cherry Studio 等 agent 客户端只需一段配置即可调用平台全部能力，你的机器不需要安装 node 或任何运行时。
快速接入
在 agent 客户端的 MCP 配置中加入（以 Cursor / Claude Code 为例）：
{
"mcpServers": {
"haina": {
"url": "https://mcp.haina.io/mcp",
"headers": { "Authorization": "Bearer vg_live_xxxxxxxx" }
}
}
}Authorization里的 token 就是控制台「API Keys」页创建的 API Token（vg_live_开头，明文只显示一次）。- 全部工具经这一个端点披露；每次调用独立鉴权，无会话状态。
限流与审计：MCP 流量与你的 API 流量共用同一 token 配额（60 次/分钟）。建议为 MCP 单独签发一个 token——配额与审计日志可以分开。
工具清单
坐席 / 视频库 / 发布记录
| 工具 | 作用 |
|---|---|
seats_list | 坐席列表（拿各操作的 accountId） |
videos_upload_from_url | 从公网 URL 拉流上传视频（素材在自家 OSS 时免本地下载） |
videos_list / videos_get / videos_delete | 视频库查询 / 详情 / 删除 |
publish_records_list | 发布记录分页 |
TikTok 发布
| 工具 | 作用 |
|---|---|
tiktok_publish_video | TikTok 发布（videoUrl 直发） |
tiktok_refresh_publish_status | TikTok 发布状态轮询 |
tiktok_get_video_stats | TikTok 视频数据回收（播放/点赞/评论/转发）。⚠️ 底层端点将要废弃（1.6.x），届时本工具将改走 video/list 面 |
TikTok 评论管理
| 工具 | 作用 |
|---|---|
tiktok_list_comments / tiktok_list_comment_replies | 评论列表 / 评论的回复列表 |
tiktok_create_comment / tiktok_reply_comment | 发顶层评论 / 回复评论 |
tiktok_like_comment | 评论点赞/取消（LIKE/UNLIKE） |
tiktok_hide_comment | 隐藏/恢复评论（HIDE/UNHIDE） |
tiktok_delete_comment | 删除评论（仅限自己账号发出的） |
TikTok Shop 挂车
| 工具 | 作用 |
|---|---|
tts_publish_shoppable_video | TikTok Shop 挂车发布 |
tts_refresh_publish_status | TikTok Shop 发布状态轮询 |
tts_precheck_submit / tts_precheck_get_result | TikTok Shop 预审（可选工具）提交 / 查结果 |
tts_products_query | TikTok Shop 商品拉取（拿 productId） |
tts_music_search | TikTok Shop 电商授权音乐搜索（BGM） |
tts_upload_photo_from_url | 从公网 URL 上传封面图（拿 photoUri） |
事件推送
| 工具 | 作用 |
|---|---|
webhook_endpoint_create / webhook_endpoints_list / webhook_endpoint_delete | webhook 端点管理（secret 仅创建时返回一次） |
events_list | 事件流拉取（push 的对账兜底） |
event_redeliver | 事件重投（Stripe 式 resend） |
能力边界：私信收发与数据洞察面暂未在 MCP 披露——这两组能力请走 CLI（
haina tt message */haina tt insight *）或 REST API。
工具 description 里写清了编排顺序，agent 会自行规划多步调用：
- TikTok 发布：
videos_upload_from_url(library=tt) → 拿videoUrl→tiktok_publish_video→tiktok_refresh_publish_status轮询终态 - TikTok Shop 挂车：
videos_upload_from_url(library=tts + accountId) → 拿fileId（一次性消耗）→ 可选tts_precheck_submit→tts_publish_shoppable_video→tts_refresh_publish_status轮询终态
错误语义
工具调用失败时返回 isError: true 与 <错误码> <文案> 文本（如 1003 no active subscription），错误码与 REST API 完全一致——agent 看到 2002 知道该等 Retry-After，看到 2005 知道视频已过期要重新上传。
MCP vs CLI：怎么选
| 场景 | 用哪个 |
|---|---|
| 素材在自家 OSS / 可公网寻址，agent 直接编排 | MCP（零本地运行时） |
| 手持本地文件、需要脚本化批处理、CI 流水线 | CLI（haina videos upload 本地上传；见 CLI 使用指南） |
| 想让 coding agent 学会完整流程与错误处置 | CLI + Agent Skill（见 Agent Skill 接入） |
三者能力等价（都打在同一个 REST API 面上），按素材位置与运行环境选即可。
安全说明
- 公网必须 HTTPS 访问；token 只在创建时可见，泄露后到控制台吊销重建即可。
- URL 取流有 SSRF 防护：仅允许 http/https 公网地址（内网/环回/云元数据地址会被拒绝，错误码 2001）。