工作區 MCP 整合指南 — 以 JoggAI 數字人為例

2026-10-31 全鏈實測通過。這份文件記錄「把外部 SaaS 的 MCP server 接進 gowinlink 工作區」的完整方法 — 以 JoggAI（AI 數字人影片平台）為實例，方法可重用於任何支援 MCP (Streamable HTTP / SSE) 的服務。

一、三種接法怎麼選

路線	計費	成本	適合
REST API key（x-api-key）	API 額度（獨立購買，較貴）	高	不走 MCP 的系統整合
MCP 桌面授權（OAuth） ✅ 推薦	走網頁帳號的 Space 額度（你平常買的方案）	低	gowinlink 工作區任務卡
產品級直連（webhook 產線）	同上＋產品定價	需開發	大量自動化時升級

關鍵事實：MCP 桌面授權的 token = 你網頁帳號的權限，消費走你已有的網頁方案額度，不用另購 API 額度。

二、gowinlink 端：任務卡用法（接線完成後）

1. 工作區擁有者到 /u 帳戶設定 → MCP 管理，新增 server：
   • 名稱：joggai（不可含空白）
   • Transport：http（JoggAI 是 Streamable HTTP）
   • Endpoint：https://api-services-intl.jogg.ai/mcp
   • Secret token：貼上 OAuth access token（見下節）
   • Allowed tools：白名單（建議只開需要的 — 會扣款費的工具刻意排除可防誤扣）
2. 之後在任務卡描述加三行結構化欄，按 🔧 執行（0 AI 點）：

產出說明文字
mcp_tool:server=joggai
mcp_tool:tool=jogg_get_user_remaining_quota
mcp_tool:arguments={}

3. 執行結果落任務卡回執（✅/⏱ 耗時＋摘要）。實測：查額度 1.4 秒回 remaining_quota。

三、OAuth 授權怎麼拿 token（手動 PKCE 流程）

適用任何支援 MCP OAuth 的服務；全程不需要 REST API key，token 由你的網頁帳號登入換來。

1. 動態註冊 client（一次即可）：POST {服務}/oauth2/register，body 帶 redirect_uris（用 http://localhost:18888/callback）、grant_types: ["authorization_code","refresh_token"]、token_endpoint_auth_method: "none"（公開客戶端＋PKCE）
2. 產生授權連結：{web 授權端點}/oauth2/authorize?response_type=code&client_id=...&code_challenge=...&code_challenge_method=S256&scope=...&resource={MCP endpoint} — PKCE code_verifier 留在自己機器（绝不上傳）
3. 用瀏覽器開連結 → 登入網頁帳號 → 按同意授權
4. 瀏覽器跳到 localhost 回呼頁「無法連上」— 這是正常的；把網址列整串（含 ?code=...）複製回來
5. 用 code＋code_verifier 換 token：POST {服務}/oauth2/token（grant_type=authorization_code）→ 得 access_token（約 24h）＋refresh_token

安全設計：code 一次性＋幾分鐘過期，且沒有保管在我方機器的 PKCE verifier 換不到 token — 過程貼對話無風險。token 本體只存伺服器隔離檔（600 權限、git 外），gowinlink 資料庫也只存它，API 回應永遠只給 SHA256 指紋不回原值。

四、Token 續期（24 小時到期）

• access token 24h 過期；refresh token 可無限續（不用重新登入）
• 續期腳本：/opt/data/scripts/joggai_mcp_token_refresh.py — 換新 token 後自動同步回 gowinlink 工作區設定
• 建議：Hermes cron 每日跑一次（排程前先徵詢 user 拍板）；token 檔過期警告內建在呼叫器 joggai_mcp_call.py

五、JoggAI 工具盤點（40 個）與白名單策略

類別	工具	API 定價表	實測（web 授權）
數字人生成	jogg_post_create_video_from_avatar（講稿/音檔→數字人開口影片）	250 credits/15 秒，30 秒起（500/支）	22 秒影片只扣 1 單位（web Space 計量，與 API 額度是兩套帳）
影片狀態	jogg_get_avatar_video_id	免費
AI 腳本	jogg_post_ai_scripts → jogg_get_ai_scripts_results_task_id	40/次
素材上傳	jogg_post_upload_asset	免費
數字人/聲音清單	jogg_get_avatars_custom / _photo_avatars / _public、jogg_get_voices	免費
影片翻譯	jogg_post_video_translate（40+ 語言）	125/15 秒
額度查詢	jogg_get_user_remaining_quota、jogg_get_user_whoami	免費
第三方影片模型	Google/Kling/MiniMax/Runway/Wan 等 9 個閘道	刻意排除在白名單外（防誤扣）

白名單哲學：唯讀工具全開；會產生付費任務的工具逐個評估再開（都帶 Billing warning 標示）。

六、實測紀錄（2026-10-31）

• 授權→接線→任務卡查額度：全鏈通，0 AI 點，1.4 秒
• 首支影片：既有數字人「曾蘋果」×「宝岛女声」×霧銀工房品牌講稿，直式 30 秒（500 credits）
• 接線位置：每日驗證工作區（id=8 設定列）；要搬正式工作區 = /u 設定頁複製一份即可

gowinlink v0.9.248 · rendered %(stamp)s