Platform MCP
Platform MCP 是好事道提供的遠端 MCP 伺服器。外部 AI 客戶端（Claude、ChatGPT、Cursor、Claude Code、Codex 等）經使用者授權後，可在授權範圍內讀取工作區資料、建立草稿與任務。
端點
| 項目 | 值 |
|---|---|
| MCP 端點 | https://mcp.guppycubed.com/mcp |
| 傳輸 | Streamable HTTP |
| 授權 | OAuth 2.1 Authorization Code + PKCE（S256） |
| Client 註冊 | 支援 Dynamic Client Registration（DCR） |
| Protected resource metadata | /.well-known/oauth-protected-resource/mcp |
| Authorization server metadata | /.well-known/oauth-authorization-server/api/platform-mcp/oauth |
端點不會轉址；請直接連到上表網址。
連線流程
- 在 MCP 客戶端新增 remote MCP server，網址填入上方端點。
- 客戶端透過 DCR 自動註冊，並開啟授權頁。
- 以好事道帳號登入，選擇要授權的工作區與權限範圍，確認授權。
- 客戶端取得 access token 後即可呼叫工具。
已授權的連線可在 設定 → 連線（/portal/settings/connections）檢視與撤銷。權限範圍變更後，需要重新連線才會生效。
權限範圍（Scopes）
授權時依需求逐項勾選，客戶端只能使用已授權範圍內的工具。
| 類別 | 範圍 |
|---|---|
| 工作區 | workspace:read、members:read |
| 專案與活動 | projects:read、activities:read |
| 任務 | tasks:read、tasks:write、tasks:assign |
| 問卷 | questionnaires:read、questionnaires:analysis:read、questionnaires:responses:read、questionnaires:publish |
| 知識庫 | knowledge:read、knowledge:write |
| 網站 | websites:read |
| 草稿 | drafts:write |
| 通知 | notifications:send |
| Skill 方法 | skills:read |
| 數位員工 | employees:read、employees:memory:read |
授權頁只會顯示目前開放的項目。
工具
工具依授權範圍動態提供，常用工具包括：
| 工具 | 所需範圍 |
|---|---|
get_connection_context | 有效授權連線即可，不需額外指定範圍；只顯示此連線已授權的工作區與權限 |
search、fetch、list_knowledge_sources | knowledge:read |
save_knowledge_link | knowledge:write |
list_projects、get_project | projects:read |
list_activities | activities:read |
list_tasks | tasks:read |
create_task、assign_task | tasks:assign |
update_task_status | tasks:write |
list_questionnaires、get_questionnaire | questionnaires:read |
get_questionnaire_analysis、get_questionnaire_results | questionnaires:analysis:read |
list_websites、get_website | websites:read |
create_website_draft、update_website_draft | drafts:write |
list_skills、get_skill | skills:read |
list_employees、get_employee_context | employees:read |
呼叫 tools/list 可取得目前授權下可用的工具與參數說明。工具仍受工作區政策與服務設定限制；已授權範圍不代表工具一定可用。
若工具未出現，先呼叫 get_connection_context，檢查目標工作區的 permissions：missing_scopes 表示需要重新連線並授予缺少的範圍；policy_blocked_scopes 需要工作區管理員處理；server_disabled_scopes 需要服務端調整設定。完成調整後重新呼叫 tools/list，不要反覆擴大授權範圍來處理政策或服務限制。
安全與審批
- 所有讀寫都限制在使用者授權的工作區與範圍內。
- 建立草稿不會直接發布；發布問卷、傳送通知、發布貼文等對外動作需先
prepare_*，經使用者在好事道內核准後才會執行。 - 列表類工具每次最多回傳 50 筆，並提供分頁；單次回傳內容有大小上限。
- 工作區成員查詢預設只回傳姓名與使用者 ID，Email 僅工作區擁有者或管理員可查。
- 問卷逐筆填答（
questionnaires:responses:read）可能包含填答者自行填寫的個資，但不提供帳號、IP 或裝置紀錄。
疑難排解
| 狀況 | 處理 |
|---|---|
| 授權後仍看不到某工具 | 依上方流程檢查 get_connection_context 的權限診斷，再更新 tools/list。 |
| 網路連線失敗或連線被拒 | 檢查端點主機名稱、網路與服務可用性。 |
| 收到 HTTP 轉址回應 | 直接使用上方 HTTPS MCP 端點，並檢查代理是否改寫或轉址請求。 |
| 需要撤銷存取 | 於 設定 → 連線 移除該客戶端。 |