
這篇教學涵蓋 claude mcp add 指令與範圍觀念、Claude Desktop 的設定方式、以 AFFiNE 工作區為例的完整串接流程,以及「接不上」時的檢查清單。如果還在概念階段,建議先讀 MCP 是什麼。
遠端(HTTP)伺服器——連上託管服務最常見的方式:
claude mcp add --transport http <名稱> <伺服器 URL> \
--header "Authorization: Bearer <權杖>"
本機(stdio)伺服器——由 Claude Code 在你的電腦上直接啟動程式:
claude mcp add <名稱> -- <啟動伺服器的指令>
日常管理三個子指令就夠:claude mcp list 看清單、claude mcp get <名稱> 看細節、claude mcp remove <名稱> 刪除。如果產品直接給你一段 JSON 設定,claude mcp add-json <名稱> '
不是每個託管伺服器都發權杖:Notion、Sentry 這類走 OAuth 的伺服器,加入時不必帶 --header,第一次使用前在工作階段輸入 /mcp,照著瀏覽器完成登入即可;不想開工作階段,也可以在終端機執行 claude mcp login <名稱>。登入後權杖會安全儲存並自動更新。完整旗標與進階選項,見 Claude Code 官方 MCP 文件。
設定寫在哪裡,決定誰看得到:
同名伺服器出現在多個範圍時,local 蓋過 project、project 蓋過 user。原則很單純:憑證放個人範圍,用 project 分享的只有伺服器定義。.mcp.json 支援環境變數展開——把標頭值寫成 Bearer ${AFFINE_TOKEN} 這種形式,權杖就由每個成員在自己的環境變數提供,永遠不會進版本控制。
同一個伺服器在 Claude Code 和 Claude Desktop 都能用,但兩邊設定各自獨立——每個會用到的應用程式都要設定一次。已經在 Desktop 設好一批本機伺服器的話,執行 claude mcp add-from-claude-desktop 可以勾選、批次匯入 Claude Code(macOS 與 WSL 適用),不必重打一遍。
以 AFFiNE 內建的 MCP 伺服器為例,完整走一遍。接好之後,工作區的文件與白板就能被任何 MCP 用戶端搜尋。
claude mcp add --transport http affine \
"https://app.affine.pro/api/workspaces/<工作區 ID>/mcp" \
--header "Authorization: Bearer <權杖>"
不另外收費:AFFiNE Cloud 和開啟 AI 功能的自架環境都一樣能用。
Cursor 讀 ~/.cursor/mcp.json(專案層級則是 .cursor/mcp.json)。AFFiNE 的 Copy JSON 輸出與 Cursor 格式完全一致:貼上、重新啟動,結束。
ChatGPT 用連接器接上遠端 MCP 伺服器;自訂伺服器需要開發者模式(設定 → 連接器 → 進階)。同一個端點、同一個標頭,原樣可用。一個伺服器,所有助理共用——這正是 MCP 的價值。
由上往下逐項檢查,多數情況在這份清單內就能解決:
claude mcp add。託管型加上 --transport http、伺服器 URL 與認證標頭;本機型則給啟動指令。用 claude mcp list 確認清單,工作階段中用 /mcp 即時查看狀態。
支援。遠端伺服器從「設定 → Connectors」以自訂連接器加入;本機伺服器寫進 claude_desktop_config.json 的 mcpServers 後重新啟動。唯一要注意的是它與 Claude Code 的設定分開管理。
可以。執行 claude mcp add-from-claude-desktop,它會讀取 Desktop 的設定檔,列出其中的本機伺服器讓你勾選匯入(macOS 與 WSL 適用);遠端伺服器則在 Claude Code 用 claude mcp add --transport http 重新加一次就好。匯入後兩邊仍是各自維護。
local 只在單一專案對你生效;project 會把共用的 .mcp.json 寫進儲存庫給全團隊;user 則在這台電腦的所有專案對你生效。憑證留在個人範圍,透過 project 分享的只有伺服器定義。
能。Streamable HTTP 的遠端伺服器加上 --transport http 與認證標頭即可,屬正式支援。像 AFFiNE 工作區端點這種託管型,完全不需要在本機跑任何程式。
加入時不要帶 --header,直接執行 claude mcp add --transport http <名稱>
先用 /mcp 看狀態,再檢查幾個常見原因:遠端伺服器少了 --transport http、Authorization 標頭格式錯誤、憑證過期,或範圍弄錯(local 只存在於加入它的那個專案)。這四項能解釋絕大多數情況。
MCP 支援本身包含在 Claude Code 與 Claude Desktop 內,不另外收費,協定本身是開源標準。各伺服器條件不同;以 AFFiNE 內建伺服器為例,在 Cloud 或開啟 AI 功能的自架環境都免費。
接好第一個伺服器,第二個就是肌肉記憶——流程對每個伺服器都一樣。從你整天在裡面找答案的地方開始最划算:你自己的工作區。