跳到內容
PushGo

Model Context Protocol (MCP)

PushGo Gateway 可以作為 MCP HTTP Server，讓支援 MCP 的 AI 助理在授權 Channel 範圍內傳送 Message、管理 Event、更新 Thing。建議使用 OAuth2 授權模式，讓使用者在瀏覽器中繫結 Channel，而不是把 Channel 密碼交給模型。

適合什麼場景

Section titled “適合什麼場景”
  • 請 AI 助理在任務完成後主動傳送 PushGo 通知。
  • 讓 AI 助理把長期任務同步為 Event。
  • 請 AI 助理更新某個服務、裝置或任務對應的 Thing。
  • 給第三方 MCP 用戶端提供受控的 Channel 存取範圍。

MCP 不應該取代使用者確認。涉及高影響操作時，用戶端或上層工作流程仍應保留確認步驟。

Endpoint

Section titled “Endpoint”
https://your-gateway-domain/mcp

公共 Gateway 如果啟用了 MCP/OAuth，可以直接使用對應區域的 /mcp 端點。私人部署必須設定外部可存取的 PUSHGO_PUBLIC_BASE_URL。

啟用私人 Gateway MCP

Section titled “啟用私人 Gateway MCP”
Terminal window
PUSHGO_MCP_ENABLED=true
PUSHGO_PUBLIC_BASE_URL=https://gateway.example.com

常用配置：

環境變數預設值說明
PUSHGO_MCP_DCR_ENABLEDtrue是否允許 Dynamic Client Registration。
PUSHGO_MCP_PREDEFINED_CLIENTS無預置 OAuth 用戶端，格式為 client_id:client_secret。
PUSHGO_MCP_ACCESS_TOKEN_TTL_SECS900access token 有效期限。
PUSHGO_MCP_REFRESH_TOKEN_ABSOLUTE_TTL_SECS2592000refresh token 絕對有效期限。
PUSHGO_MCP_REFRESH_TOKEN_IDLE_TTL_SECS604800refresh token 空閒效期。
PUSHGO_MCP_BIND_SESSION_TTL_SECS600Channel 繫結頁面會話有效期限。

如果用戶端不支援 DCR，請關閉或忽略 DCR，並透過 PUSHGO_MCP_PREDEFINED_CLIENTS 設定固定用戶端。

授權模式

Section titled “授權模式”
模式Channel 密碼適用於風險
OAuth2 授權模式工具呼叫中不傳 passwordAI 助理、第三方用戶端、生產環境由 scope 和 Channel 授權範圍限制。
Legacy 模式每次工具呼叫傳 password個人指令碼、受信任環境呼叫方直接持有 Channel 密碼。

生產環境優先使用 OAuth2 授權模式。

使用者繫結流程

Section titled “使用者繫結流程”
  1. MCP 用戶端連線 /mcp。
  2. 用戶端透過 OAuth2 或 DCR 取得用戶端身分。
  3. 助手呼叫 pushgo.channel.bind.start。
  4. 使用者開啟返回的 bind_url。
  5. 使用者輸入 Channel ID 和密碼，並確認授權範圍。
  6. 助手輪詢 pushgo.channel.bind.status。
  7. 授權完成後，助手可以在已授權 Channel 範圍內呼叫工具。

繫結會話預設有效期由 PUSHGO_MCP_BIND_SESSION_TTL_SECS 控制。

工具能力

Section titled “工具能力”

Message

Section titled “Message”
工具作用
pushgo.message.send傳送一次性 Message。支援 title、body、url、images、severity、ttl、metadata、thing_id 等欄位。

Event

Section titled “Event”
工具作用
pushgo.event.create建立生命週期事件，回傳 event_id。
pushgo.event.update更新已有事件。
pushgo.event.close關閉已有事件。

Thing

Section titled “Thing”
工具作用
pushgo.thing.create建立長期實體，回傳 thing_id。
pushgo.thing.update更新實體屬性。
pushgo.thing.archive歸檔實體。
pushgo.thing.delete刪除或退役實體。

Channel

Section titled “Channel”
工具或資源作用
pushgo.channel.bind.start建立繫結或撤銷會話，回傳 bind_url。
pushgo.channel.bind.status查詢繫結會話狀態。
pushgo.channel.list列出目前授權的 Channel。
pushgo.channel.unbind撤銷某個 Channel 授權。
pushgo://channels已授權 Channel 資源清單。
pushgo://channels/{channel_id}單一 Channel 的基礎資訊。

用戶端設定要點

Section titled “用戶端設定要點”
  • MCP endpoint 使用 https://your-gateway-domain/mcp。
  • 反向代理必須把 Host 和 X-Forwarded-Proto 正確傳給 Gateway。
  • 私人部署必須設定 PUSHGO_PUBLIC_BASE_URL，並確保它是外部可存取的 HTTPS 根位址。
  • 如果 OAuth issuer 或繫結連結出現內部網路位址，優先檢查 PUSHGO_PUBLIC_BASE_URL。
  • 如果用戶端不支援 DCR，使用預置用戶端配置。

維運注意事項

Section titled “維運注意事項”
  • MCP 授權狀態會持久化；不要把資料庫或儲存目錄當臨時快取清空。
  • Access token 較短，refresh token 較長；根據用戶端風險調整 TTL。
  • 定期輪換預置用戶端 secret。
  • 高風險 Channel 可以單獨建立，避免把所有自動化授權到同一 Channel。
  • 維運稽核與執行階段問題應結合 Gateway 結構化日誌與統計指標排查。

常見問題

Section titled “常見問題”
現象檢查專案
用戶端無法發現 OAuth 元資料PUSHGO_PUBLIC_BASE_URL 是否設定為 HTTPS 外部位址；反向代理是否轉送 well-known 路由。
繫結連結打不開公網 DNS、HTTPS 憑證、反向代理路徑和 PUSHGO_MCP_BIND_SESSION_TTL_SECS。
DCR 失敗用戶端是否支援 DCR；PUSHGO_MCP_DCR_ENABLED 是否開啟。
工具呼叫要求 password目前可能是 Legacy 模式，或 OAuth 授權未完成。
已授權但看不到 Channel繫結會話是否完成；scope 是否足夠；Channel 是否被撤銷授權。