Remote MCP：讓 claude.ai／任何 MCP 客戶端直連你的 DuDuClaw

duduclaw http-server 提供標準的 MCP Streamable HTTP 端點（POST /mcp）與完整的 OAuth 2.1 授權流程。這代表 claude.ai 的自訂連接器（Custom Connector）、Claude 行動版、MCP Inspector，或任何支援 remote MCP server 的應用，都可以直接連上你自架的 DuDuClaw，使用記憶、知識庫等工具面。

快速開始

# 1. 啟動 HTTP server（預設只綁 loopback）
duduclaw http-server --bind 127.0.0.1:8765

# 2. 需要對外時開一條通道（或用你自己的反向代理/網域）
duduclaw tunnel          # Cloudflare quick tunnel，畫面會給你 https 網址

拿到對外網址後，在 claude.ai「設定 → 連接器 → 新增自訂連接器」貼上：

https://<你的網址>/mcp

claude.ai 會自動走 OAuth 探索（RFC 9728 → RFC 8414 → 動態註冊），把你導到 DuDuClaw 的授權頁。頁面上貼一把內部 MCP API key（config.toml [mcp_keys] 中 is_external = false 的 key）按「同意連線」即完成。

從 ChatGPT 使用

ChatGPT 可以把 DuDuClaw 加成自訂連接器（開發者模式下的「應用程式」）。不會發布到任何商店，連接器只存在你自己的 ChatGPT 帳號裡。

讓 duduclaw http-server 有一個固定的 https 位址（反向代理或具名通道；ChatGPT 從 OpenAI 的伺服器連線，loopback 或區網位址不行）。
在 ChatGPT 開啟開發者模式（設定 → 應用程式與連接器 → 進階設定；哪些方案提供由 OpenAI 決定），以伺服器網址 https://<你的位址>/mcp、驗證方式 OAuth 建立連接器。
ChatGPT 會找到授權伺服器（RFC 9728 → RFC 8414）並自行註冊：透過動態用戶端註冊（POST /oauth/register），或用 Client ID Metadata Document（client_id 是 DuDuClaw 會去讀取的 https 網址；2026-10-08 起支援，見下方）。依第三方指南，它的轉回網址是 https://chatgpt.com/connector_platform_oauth_redirect；DuDuClaw 接受任何 https 轉回網址，不必另外設定。
DuDuClaw 的授權頁出現後，貼上一把內部 MCP API key 並同意。

ChatGPT 拿到的權限與所有 OAuth 用戶端相同（見下方「外部用戶端」等級）：基礎工具，加上最多 memory:read、memory:write、wiki:read、wiki:write、messaging:send。連接器、執行、人員名冊與 Admin 工具永遠不會經 OAuth 開放。

Client ID Metadata Document：client_id 是帶路徑的 https:// 網址且不是已註冊的 id 時，DuDuClaw 會去讀取它（只連公開位址、固定解析、不跟隨轉址、5 秒、5 KiB、快取一小時）。文件中的 client_id 必須與網址相同，redirect_uris 必須是 https（或 loopback http）網址且包含實際使用的那個，只接受公開用戶端（token_endpoint_auth_method 不存在或為 none）。授權伺服器中繼資料會宣告 client_id_metadata_document_supported: true。

未驗證：沒有用真的 ChatGPT 帳號測試。轉回網址與註冊方式取自第三方連接器指南（撰寫時無法取得 OpenAI 自己的頁面）；流程只用本機請求測試過。

授權模型（重要）

OAuth 簽發的存取權杖永遠是「外部客戶端」等級，與對外工具面的 scope 政策共用同一條規則，沒有第二套：

基礎工具面（7 個基礎工具）恆可用。
連接器請求的 scope 會被收斂到可對外授與的白名單（memory:read / memory:write / wiki:read / wiki:write / messaging:send）；連接器類（Odoo/Google/Notion）、執行類、人員名冊與 Admin 永不透過 OAuth 開放，就算客戶端聲稱要求也一樣。
同意頁貼的必須是內部 key（外部 key 不能自我升級）。

權杖細節：存取權杖 1 小時、refresh token 30 天且每次使用即輪替；授權碼單次有效 10 分鐘；PKCE S256 必須。所有權杖落盤只存 SHA-256 雜湊（~/.duduclaw/mcp_oauth_issued.json，0600）。

端點總覽

路徑	用途
`POST /mcp`	標準 MCP 端點：`server/discover`／`tools/list`／`tools/call`／`subscriptions/listen`（2026-07-28），`initialize`／`ping`（舊世代）。見協定版本
`GET /.well-known/oauth-protected-resource`	RFC 9728 資源中繼資料（401 的 `WWW-Authenticate` 會指向這裡）
`GET /.well-known/oauth-authorization-server`	RFC 8414 授權伺服器中繼資料
`POST /oauth/register`	RFC 7591 動態客戶端註冊（public client）
`GET /oauth/authorize` → `POST /oauth/decision`	授權碼流程＋操作者同意頁
`POST /oauth/token`	換發／刷新權杖
`POST /mcp/v1/call`、`GET /mcp/v1/stream`	既有的 DuDuClaw REST/SSE 面（不變）

靜態 Bearer key（ddc_…）與 OAuth 權杖（ddc_oauth_…）走同一個 Authorization: Bearer 表面；腳本／自家整合繼續用靜態 key 即可，OAuth 是給「只會說 OAuth」的客戶端（claude.ai）用的。

協定版本

POST /mcp 與 stdio 的 duduclaw mcp-server 都同時支援 MCP 的兩個世代：

新世代 2026-07-28：沒有 initialize，每個請求在 params._meta 帶版本與用戶端能力（io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientCapabilities）。支援 server/discover、tools/list、tools/call、subscriptions/listen。走 HTTP 時每個請求還要帶 MCP-Protocol-Version 與 Mcp-Method 標頭，tools/call 另外要 Mcp-Name；標頭缺漏或與內容不符回 400 加 -32020，不支援的版本回 -32022 並列出支援的版本。
舊世代 2024-11-05 到 2025-11-25：用 initialize 協商，要哪個版本就回哪個，不認得的版本回 2025-11-25。ping 照常回應。

工具清單變動時：stdio 的舊世代用戶端照舊收到 notifications/tools/list_changed；新世代用戶端要開 subscriptions/listen 並帶 toolsListChanged: true 才會收到。HTTP 端點沒有狀態，無從得知呼叫者的工具變了，所以收到訂閱時回確認但不承諾任何通知類型，接著直接結束訂閱；HTTP 用戶端在 tools/list 的 ttlMs（5 秒）到期後重新讀取即可。

2026-10-16 用官方 TypeScript 用戶端 @modelcontextprotocol/client 2.3.1 實測：固定 2026-07-28、自動、舊世代三種模式，stdio 與 HTTP 都通過。

安全備註

瀏覽器來源（Origin 標頭）比對 loopback＋config.toml [gateway] allowed_origins 白名單（錨定比對），其餘一律 403；非瀏覽器客戶端不受影響。
quick tunnel 的網址每次啟動會變——正式對外請用固定網域（反向代理或 Cloudflare named tunnel），OAuth 流程的 issuer 由請求的 Host／X-Forwarded-Proto 導出。
要撤銷所有已簽發的連線，刪除 ~/.duduclaw/mcp_oauth_issued.json 即可（下次請求立即失效）。