所有文章
AFFiNE
Toeverything·發布於 2026年8月20日 · 更新於 2026年8月21日
終端機視窗經由 MCP 連接埠連上 AI 助理面板的示意圖

在 Claude Code 加入 MCP 伺服器:設定步驟與疑難排解

重點整理

  • Claude Code 原生支援 MCP:遠端伺服器只要一行 claude mcp add 指令,幾分鐘就能接上。
  • 設定存放位置分三種範圍(local、project、user)。要跟團隊共用選 project,憑證一律放個人範圍。
  • Claude Desktop 有兩條路:Connectors(遠端)與設定檔(本機),而且它的設定和 Claude Code 互相獨立。
  • 伺服器沒出現時,先在工作階段輸入 /mcp 看連線狀態——這永遠是最快的一步。

這篇教學涵蓋 claude mcp add 指令與範圍觀念、Claude Desktop 的設定方式、以 AFFiNE 工作區為例的完整串接流程,以及「接不上」時的檢查清單。如果還在概念階段,建議先讀 MCP 是什麼。

在 Claude Code 加入 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 <名稱> '' 可以原樣吃下。工作階段中,/mcp 指令會顯示連線狀態與可用工具——有異狀時第一個看這裡。

不是每個託管伺服器都發權杖:Notion、Sentry 這類走 OAuth 的伺服器,加入時不必帶 --header,第一次使用前在工作階段輸入 /mcp,照著瀏覽器完成登入即可;不想開工作階段,也可以在終端機執行 claude mcp login <名稱>。登入後權杖會安全儲存並自動更新。完整旗標與進階選項,見 Claude Code 官方 MCP 文件。

三種範圍:local、project、user

設定寫在哪裡,決定誰看得到:

  • local(預設):這個專案、這台電腦、只有你。適合實驗和個人憑證。
  • project:寫進儲存庫根目錄的 .mcp.json,隨版本控制分享給整個團隊。適合當團隊標準的伺服器(例如知識庫);成員第一次使用時會跳出核准提示。
  • user(--scope user):在這台電腦的所有專案對你生效。適合到處都用的個人伺服器。

同名伺服器出現在多個範圍時,local 蓋過 project、project 蓋過 user。原則很單純:憑證放個人範圍,用 project 分享的只有伺服器定義。.mcp.json 支援環境變數展開——把標頭值寫成 Bearer ${AFFINE_TOKEN} 這種形式,權杖就由每個成員在自己的環境變數提供,永遠不會進版本控制。

在 Claude Desktop 加入

  • 遠端伺服器:「設定 → Connectors → 新增自訂連接器」,貼上 URL 並授權。這條路不需要終端機,AFFiNE、Notion 這類託管伺服器走這裡就夠。
  • 本機伺服器:編輯 claude_desktop_config.json(設定 → 開發者 → 編輯設定),在 mcpServers 加入伺服器後重新啟動應用程式。

同一個伺服器在 Claude Code 和 Claude Desktop 都能用,但兩邊設定各自獨立——每個會用到的應用程式都要設定一次。已經在 Desktop 設好一批本機伺服器的話,執行 claude mcp add-from-claude-desktop 可以勾選、批次匯入 Claude Code(macOS 與 WSL 適用),不必重打一遍。

從頭到尾:接上自己的知識庫

以 AFFiNE 內建的 MCP 伺服器為例,完整走一遍。接好之後,工作區的文件與白板就能被任何 MCP 用戶端搜尋。

  1. 建立憑證:在 AFFiNE 打開「設定 → Integrations → MCP Server → Create credential」。標籤填用戶端名稱(例如「Claude Code」;一個用戶端一組憑證,撤銷時最省事),存取權限維持預設的唯讀,並設定有效期限。
  2. 複製設定:權杖只顯示一次,旁邊的 Copy JSON 按鈕會產生完整設定——端點 URL 和認證標頭都在裡面。端點會是 https://app.affine.pro/api/workspaces/<工作區 ID>/mcp 這樣的格式;自架環境則換成你自己伺服器的位址。
  3. 加入:
claude mcp add --transport http affine \
  "https://app.affine.pro/api/workspaces/<工作區 ID>/mcp" \
  --header "Authorization: Bearer <權杖>"
  1. 使用:開一個工作階段,問一個只有你的筆記能回答的問題:「找出付款重試機制的設計文件,整理還沒解決的問題」。Claude Code 會呼叫搜尋工具(關鍵字加語意檢索,白板上的文字也在搜尋範圍內),在你的權限內以 Markdown 讀取文件全文,用你實際寫過的內容回答。

不另外收費:AFFiNE Cloud 和開啟 AI 功能的自架環境都一樣能用。

用戶端選擇本機或遠端傳輸,再以權限範圍受限的憑證連到 MCP 伺服器
傳輸方式決定伺服器在哪裡執行;憑證權限決定用戶端能存取哪些工具與資料。

同一份設定,Cursor 和 ChatGPT 也能用

Cursor 讀 ~/.cursor/mcp.json(專案層級則是 .cursor/mcp.json)。AFFiNE 的 Copy JSON 輸出與 Cursor 格式完全一致:貼上、重新啟動,結束。

ChatGPT 用連接器接上遠端 MCP 伺服器;自訂伺服器需要開發者模式(設定 → 連接器 → 進階)。同一個端點、同一個標頭,原樣可用。一個伺服器,所有助理共用——這正是 MCP 的價值。

疑難排解:伺服器沒出現

由上往下逐項檢查,多數情況在這份清單內就能解決:

  • 先看 /mcp:是已連線、認證失敗,還是根本沒啟動,這裡一目了然。先讀錯誤訊息,永遠比亂猜快。
  • 傳輸方式弄錯:託管伺服器必須加 --transport http,漏掉的話 Claude Code 會把 URL 當成本機指令。移除後帶旗標重新加入。另外,舊教學常見的 --transport sse 已被官方列為棄用,能走 http 就走 http。
  • 標頭打錯:格式是 Authorization: Bearer <權杖>。少了 Bearer 或多一個空格,換來的就是一個毫無線索的 401。不要手打,從 Copy JSON 貼上最保險。
  • 憑證過期或被撤銷:有期限的權杖總有一天會到期。重新發一組憑證再註冊一次。
  • 範圍搞混:用 local 範圍加入的伺服器,在其他專案不存在。到你預期它出現的目錄執行 claude mcp list,真相立刻揭曉。
  • 專案伺服器被你拒絕過:.mcp.json 裡的伺服器第一次載入會請你核准,當時按了拒絕,它就從此隱身。執行 claude mcp reset-project-choices 重設,下次啟動會再問一次。
  • 本機伺服器缺相依套件:stdio 伺服器要執行指令,缺少執行環境就會當場失敗。先手動執行那個指令,看看真正的錯誤是什麼。
  • 本機伺服器啟動太慢:npx 這類指令第一次執行要先下載套件,可能撞上啟動逾時。用 MCP_TIMEOUT=10000 claude 把逾時放寬到 10 秒再試。
  • 接上了卻不被使用:前幾次先在提示裡點名來源(「在我的 AFFiNE 工作區找⋯⋯」)。模式建立之後,Claude 就會自己挑對工具。

該守住的資安預設

  • 用不到寫入之前維持唯讀:知識庫連線幾乎不需要寫入;AFFiNE 憑證預設唯讀,寫入功能正逐步推出。
  • 一個用戶端一組憑證:撤銷筆電那組,不影響桌機。搭配有效期限,輪換就只是例行公事。
  • 核准提示別順手就按:Claude 使用新工具前會先確認;project 範圍的共用伺服器,每個人第一次用也要核准。凡是能改動資料的工具,這道確認不要關。完整清單見我們的 MCP 資安指南(英文)。

常見問題

在 Claude Code 加入 MCP 伺服器的指令是什麼?

claude mcp add。託管型加上 --transport http、伺服器 URL 與認證標頭;本機型則給啟動指令。用 claude mcp list 確認清單,工作階段中用 /mcp 即時查看狀態。

Claude Desktop 支援 MCP 伺服器嗎?

支援。遠端伺服器從「設定 → Connectors」以自訂連接器加入;本機伺服器寫進 claude_desktop_config.json 的 mcpServers 後重新啟動。唯一要注意的是它與 Claude Code 的設定分開管理。

Claude Desktop 的 MCP 設定可以搬進 Claude Code 嗎?

可以。執行 claude mcp add-from-claude-desktop,它會讀取 Desktop 的設定檔,列出其中的本機伺服器讓你勾選匯入(macOS 與 WSL 適用);遠端伺服器則在 Claude Code 用 claude mcp add --transport http 重新加一次就好。匯入後兩邊仍是各自維護。

local、project、user 三種範圍差在哪?

local 只在單一專案對你生效;project 會把共用的 .mcp.json 寫進儲存庫給全團隊;user 則在這台電腦的所有專案對你生效。憑證留在個人範圍,透過 project 分享的只有伺服器定義。

Claude Code 能連遠端 MCP 伺服器嗎?

能。Streamable HTTP 的遠端伺服器加上 --transport http 與認證標頭即可,屬正式支援。像 AFFiNE 工作區端點這種託管型,完全不需要在本機跑任何程式。

MCP 伺服器要求 OAuth 登入怎麼辦?

加入時不要帶 --header,直接執行 claude mcp add --transport http <名稱> ;第一次使用前在工作階段輸入 /mcp 選擇該伺服器,瀏覽器會開啟授權頁完成登入,或改在終端機執行 claude mcp login <名稱>。權杖會安全儲存並自動更新。

為什麼我的伺服器沒出現在清單裡?

先用 /mcp 看狀態,再檢查幾個常見原因:遠端伺服器少了 --transport http、Authorization 標頭格式錯誤、憑證過期,或範圍弄錯(local 只存在於加入它的那個專案)。這四項能解釋絕大多數情況。

在 Claude 使用 MCP 要花錢嗎?

MCP 支援本身包含在 Claude Code 與 Claude Desktop 內,不另外收費,協定本身是開源標準。各伺服器條件不同;以 AFFiNE 內建伺服器為例,在 Cloud 或開啟 AI 功能的自架環境都免費。

結語

接好第一個伺服器,第二個就是肌肉記憶——流程對每個伺服器都一樣。從你整天在裡面找答案的地方開始最划算:你自己的工作區。