前言¶

DSH 裏接 MCP，常見路徑是本地進程或無需登錄的 HTTP 端點：工具直接註冊，agent 即可調用。不少廠商把 MCP 掛在 OAuth 後面——要先發現授權服務器、走瀏覽器同意、保存 access token 與 refresh token，連接才能維持。

這條鏈路若全靠會話裏手填 URL、自己保管 token，很容易斷在刷新或工具命名衝突上。dsh-oauth-mcp 是維護者 lunnlew 發佈的 DSH 客戶端插件（社區分類 admin-security），在宿主內做 OAuth 2.1 客戶端：發現授權端、PKCE 授權碼流程、令牌寫入宿主憑據庫並續期，再把遠端 MCP 工具註冊爲宿主工具。

這是什麼¶

dsh-oauth-mcp 面向「需要 OAuth 才能連上的遠程 MCP 服務器」。裝上後你會多出三處入口：

• 設置頁「OAuth 授權管理」頁籤
• 會話命令 /oauth-mcp
• agent 工具 dsh_oauth_mcp_authorize、dsh_oauth_mcp_status

授權成功的遠端工具以 mcp_oauth__<serverId>__<tool> 出現在工具表裏，與宿主自帶的 mcp__<server>__<tool> 前綴分離。

代碼倉庫：github.com/lunnlew/dsh-oauth-mcp。插件目錄頁：skillhub.cn/plugins/lunnlew/dsh-oauth-mcp。目錄站是社區插件索引，與 DeepSeek / 幻方無官方從屬關係。

當前 npm 包版本爲 0.0.5（見倉庫 package.json），許可證 MIT。插件在 DSH 進程權限下運行，安裝前宜自行查看源碼與許可證；不要假定目錄頁的星標或簡介與倉庫 README 完全一致時，以 README 與包元數據爲準。

核心能力¶

插件側完成的工作可以概括爲四步：

1. 授權服務器發現：按遠程 MCP 與廠商元數據定位 OAuth 端點。
2. PKCE 授權碼：在瀏覽器完成廠商頁面上的同意；回調默認 http://127.0.0.1:39271/oauth-mcp/callback，頁面上不展示 token、code 或 state。
3. 憑據託管：令牌存入宿主 ctx.credentials，由插件維持有效；配置裏不保存 token。
4. 工具橋接：已授權服務器的 MCP 工具註冊爲宿主可調用工具。

設置面板內置 41 家經實測的遠程 MCP 廠商配置，選中後可自動填服務器地址、ID、默認 scope 與授權服務器地址；也可選手填「自定義」。

默認開啓 惰性工具（lazyTools: true）：未揭示前工具表只暴露入口 mcp_oauth，避免一次授權多臺服務器時把數十個遠端工具定義全部壓進模型上下文。揭示按會話隔離，不落盤。

安裝與啓用¶

前置條件：已安裝並至少運行過一次 DSH 桌面應用。package.json 要求 dsh >= 0.2.1-rc.5，Node >= 22。

從 npm 安裝（常用）¶

在 DSH 終端執行：

dsh plugin --profile desktop add dsh-oauth-mcp

根據返回值處理：

• application: applied —— 已生效，繼續下面步驟
• application: restart-required —— 重啓 DSH 後再試

打開「設置 → OAuth 授權管理」，確認該頁籤存在。若缺失，先覈對返回值並重啓；仍無效見倉庫 README「遇到問題怎麼辦」。

從源碼或打包文件¶

改代碼或本地調試時，可在插件目錄 pnpm install 後執行 dsh plugin add <本插件目錄的絕對路徑>；或 pnpm pack 得到 dsh-oauth-mcp-<版本號>.tgz 再 dsh plugin add ./dsh-oauth-mcp-<版本號>.tgz。profile 指向源碼目錄時，改代碼後重啓客戶端即可，無需重複裝載。

典型用法¶

1. 添加服務器¶

1. 打開 設置 → OAuth 授權管理，點「添加服務器」。
2. 在廠商下拉選擇內置條目，或選「自定義」手填；勾選 scope 後保存。
3. 行右側「已啓用」表示插件會嘗試自動連接；「已停用」則跳過。

也可在地址框直接輸入廠商 URL，插件僅自動補 ID。

2. 發起授權¶

在會話中：

/oauth-mcp authorize <serverId | 服務器地址>

命令返回授權卡片（可點鏈接與可複製 URL）。在瀏覽器完成廠商側同意後，插件處理回調。若端口被佔用而進入 manual-only，用：

/oauth-mcp complete <serverId> <回調 URL>

GitHub、Zendesk、Slack 等八家廠商需額外步驟，見倉庫 docs/vendors.md。

3. 查看狀態與工具列表¶

/oauth-mcp status
/oauth-mcp tools

status 彙報各服務器是否已授權、過期時間、是否有 refresh token、是否已連接、工具數量；不顯示令牌原文。

完整子命令：

/oauth-mcp status [serverId]
/oauth-mcp tools [serverId]
/oauth-mcp authorize <serverId | url>
/oauth-mcp complete <serverId> <url>
/oauth-mcp disconnect <serverId>
/oauth-mcp cancel <serverId>
/oauth-mcp help

4. 在 agent 裏調用遠端工具¶

授權 Linear 後，遠端 list_issues 在宿主名爲 mcp_oauth__linear__list_issues。可自然語言描述任務讓 agent 選工具，或從 /oauth-mcp tools 複製全名點名調用。

惰性工具開啓時，先讓 agent 調用 mcp_oauth（可選 {"server":"notion"} 指定服務器），當輪揭示後同名工具方可直接調用；未揭示就硬調會被攔截並提示先調用 mcp_oauth。

配置要點¶

面板可即時修改 servers、defaultScopes、autoConnect、lazyTools。以下項在面板只讀，需改宿主 profile 裏 dsh-oauth-mcp 的 config:（設置 → 通用設置 → 打開配置文件），保存後宿主會重啓本插件：

改配置不斷開已有令牌，但已建立的 MCP 會話會斷開並在下次連接時重建。字段全集見 docs/usage.md。

適用場景與注意¶

適合：在 DSH 桌面環境裏接 Salesforce、Notion、Linear 等要求 OAuth 的遠程 MCP；希望令牌進宿主憑據庫、由插件刷新，而不是把 token 寫在會話或零散腳本里。

注意：

• 插件代碼與網絡請求運行在 當前 DSH 進程權限 下；只安裝 npm 包或審查過源碼後再用於生產賬號。
• OAuth 同意發生在廠商網頁，插件不代點；回調成功頁也不應出現敏感參數。
• 八家廠商與 41 家內置配置的實測細節以倉庫文檔爲準，升級插件後重讀 docs/vendors.md 與 docs/usage.md 中的故障排查表。

常見現象如設置頁無「OAuth 授權管理」、面板列表爲空、credential_service_unavailable、端口 39271 佔用等，README 第 9 節有對照表。

結尾¶

dsh-oauth-mcp 把「遠程 OAuth MCP」收成一條可重複路徑：面板配服務器、命令行授權、令牌託管、工具以 mcp_oauth__* 進宿主，並可用惰性加載控制上下文體積。需要字段表、契約與驗收清單時，直接翻倉庫 docs/ 與 DESIGN.md。

• 目錄頁：https://www.skillhub.cn/plugins/lunnlew/dsh-oauth-mcp
• GitHub：https://github.com/lunnlew/dsh-oauth-mcp