Claude Code 接 MCP server 中文設定教學（2026）：指令、.mcp.json 與遠端 OAuth
目錄
Claude Code 接 MCP server 只要一行指令：本機程式用 claude mcp add 名稱 -- 指令，遠端服務用 claude mcp add --transport http 名稱 網址，加完跑 claude mcp list 看到 ✔ Connected 就能用。要跟團隊共用就把設定寫進專案根目錄的 .mcp.json，要登入的遠端服務在 Claude Code 裡打 /mcp 走瀏覽器授權。
這篇標明「實測」的指令和輸出，是我們 2026 年 11 月 8 日在一台 Windows 10 電腦上（Git Bash、Claude Code 2.1.285）實際跑過的；其餘照 Claude Code 官方文件寫，文中會標出來。還沒裝 Claude Code 的話，先看 Claude Code 實戰教學把環境弄好再回來。
利益揭露：範例用的 mindthread-mcp 是我們自己產品 MindThread 的 MCP 套件。選它是因為不用金鑰就能列出工具，你可以換成任何 stdio 伺服器，步驟一樣。
為什麼要接 MCP？
當你發現自己一直把別的工具裡的資料複製貼上給 Claude，就是該接 MCP 的時候。MCP（Model Context Protocol）是讓 AI 連接外部工具的開源標準，接上之後 Claude 可以直接讀取、操作那個系統，不用再靠你貼。
對台灣的中小企業和個人開發者，MCP 的用處是把 Claude 接到你已經在用的系統。官方文件舉的例子有從 issue tracker 拿需求直接實作、查 Sentry 的監控資料、查 PostgreSQL 資料庫、開瀏覽器測網站。你不用自己寫串接程式，找到對方提供的 MCP server 接上就好。
三種接法
Claude Code 接 MCP server 有三種做法：claude mcp add 指令、專案根目錄的 .mcp.json、需要 OAuth 登入的遠端伺服器。
接法一：`claude mcp add` 一行指令
最快的做法是在終端機（不是在 Claude Code 對話裡）跑 claude mcp add。本機程式型的伺服器叫 stdio，Claude Code 會把它當子程序啟動：
claude mcp add mindthread -- npx -y mindthread-mcp
-- 很重要。官方文件說明，-- 前面是 Claude Code 自己的參數（--transport、--env、--scope），後面整段原封不動交給伺服器。需要金鑰的伺服器用 --env KEY=value 傳。
遠端伺服器用 HTTP 傳輸，這是官方建議的遠端接法：
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
管理指令只有三個要記：claude mcp list 列出全部並檢查連線、claude mcp get 名稱 看單一伺服器的細節、claude mcp remove 名稱 移除。
接法二：專案根目錄的 `.mcp.json`
團隊共用 MCP 設定時，把伺服器寫進專案根目錄的 .mcp.json 並放進版控，clone 下來的人就拿得到同一組工具。你可以手寫，也可以用 --scope project 讓指令幫你寫。格式長這樣：
{
"mcpServers": {
"claude-code-docs": {
"type": "http",
"url": "https://code.claude.com/docs/mcp"
},
"mindthread": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mindthread-mcp"],
"env": { "MINDTHREAD_API_KEY": "${MINDTHREAD_API_KEY}" }
}
}
}
金鑰不要直接寫進 .mcp.json，用 ${變數名} 引用環境變數。官方文件支援 ${VAR} 和帶預設值的 ${VAR:-default}，可以用在 command、args、env、url、headers。
官方文件寫明 Claude Code 在 session 開始時讀 .mcp.json，改完要離開再重開 session。第一次看到專案裡的伺服器時，它會先問你要不要核准，官方說明這是為了不讓你 clone 下來的 repo 在你電腦上自己開程式。接陌生的伺服器之前，先讀過它會給 Claude 哪些工具。如果是你自己寫的伺服器，工具描述會直接進入 Claude 的 context（超過長度上限的部分會被截掉），可以用我們開源的 UltraProbe 貼上工具描述做靜態檢查。它只看你貼的文字，不會連線掃伺服器本身。
接法三：需要 OAuth 登入的遠端伺服器
Sentry、Notion、Linear 這類雲端服務的 MCP server 要先登入才能用，流程是加網址、再到 Claude Code 裡授權。先加：
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
這時 claude mcp list 會顯示 ! Needs authentication，這是正常的。接著開 Claude Code，打 /mcp，選這個伺服器，選 Authenticate，瀏覽器會開到對方的登入頁，同意後狀態就變成已連線。
用固定 token 而不是 OAuth 的服務，在加的時候帶 --header "Authorization: Bearer 你的token"。
實測三段
我們在 Windows 10、Claude Code 2.1.285 上實測了三件事：加 stdio 伺服器、三種 scope 的寫法，以及遠端伺服器的登入狀態。實測用的是另開的暫存設定目錄，沒有動到平常在用的設定。
實測一：加一個 stdio 伺服器
claude mcp add 回 Added 只代表設定寫進去了，要再跑 claude mcp list 才知道程式啟動得起來。我們的輸出（路徑已改寫）：
$ claude mcp add mindthread -- npx -y mindthread-mcp
Added stdio MCP server mindthread with command: npx -y mindthread-mcp to local config
File modified: <設定目錄>\.claude.json [project: <專案路徑>]
$ claude mcp list
mindthread: npx -y mindthread-mcp - ✔ Connected
我們另外直接用 MCP 協定問這個伺服器有哪些工具，沒帶金鑰時列出 43 個，工具定義加起來約 4.7 萬字元。工具數由伺服器決定，之後會變。在我們的環境（Windows 10、Git Bash、Claude Code 2.1.285），npx 直接寫就連得上，不必再套一層 cmd /c；PowerShell 和命令提示字元下我們沒測。
實測二：`.mcp.json` 與三種 scope
Claude Code 的 MCP scope 有 local、project、user 三種，決定一個伺服器在哪些專案出現、會不會跟團隊共用。官方文件的整理：
| scope | 在哪裡生效 | 會不會共用 | 存在哪 |
|---|---|---|---|
| local（預設） | 只有目前專案 | 不會 | ~/.claude.json，記在這個專案底下 |
| project | 只有目前專案 | 會，透過版控 | 專案根目錄 .mcp.json |
| user | 你所有專案 | 不會 | ~/.claude.json，最上層 mcpServers |
我們三種各加一個，claude mcp list 的結果：
mt-everywhere: npx -y mindthread-mcp - ✔ Connected
mt-shared: npx -y mindthread-mcp - ⏸ Pending approval (run `claude` to approve)
mindthread: npx -y mindthread-mcp - ✔ Connected
project scope 的 mt-shared 停在待核准，要在這個資料夾開一次 claude 按同意才會連線。claude mcp get 會寫出伺服器屬於哪個 scope，搞不清楚設定從哪來的時候先跑它。
實測三：遠端伺服器的登入狀態與 `/mcp` 重新授權
/mcp 是 Claude Code 對話裡的內建指令，用來看每個伺服器的狀態、工具數量，並在同一個面板裡重新連線或登入。我們加了兩個遠端伺服器，claude mcp list 的結果：
sentry: https://mcp.sentry.dev/mcp (HTTP) - ! Needs authentication
claude-code-docs: https://code.claude.com/docs/mcp (HTTP) - ✔ Connected
我們沒有實際登入 Sentry，下面的重新授權流程照官方文件寫。登入過的伺服器拒絕舊 token 時，Claude Code 有 refresh token 就自動換新、重試一次；連 refresh token 也被拒，會跳出提示叫你開 /mcp，選伺服器、選 Re-authenticate 重新登入。對話中途過期時，錯誤訊息長這樣：
MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)
常見錯誤 6 條
1. 指令加了卻連不上（實測）。 加的時候忘了 --，npx 的 -y 會被當成 Claude Code 自己的參數，我們實測直接報 error: unknown option '-y'。反過來，指令名稱打錯時 claude mcp add 照樣成功，要到 claude mcp list 才顯示 ✘ Failed to connect，claude mcp get 的 Issue 欄寫 CONNECTION_CLOSED: Connection closed。官方建議直接在終端機跑那段指令看錯誤。另外 npx 第一次下載套件比較慢，可能超過預設 30 秒的啟動時限，用 MCP_TIMEOUT=60000 claude 放寬。
2. 一直跳權限提示（照官方文件）。 Claude 第一次呼叫某個 MCP 工具時會問你，這是正常的保護。常用的伺服器可以在設定檔放行，例如專案的 .claude/settings.json 或你自己的 ~/.claude/settings.json：
{
"permissions": {
"allow": ["mcp__mindthread__*"]
}
}
mcp__mindthread__* 放行整台伺服器的工具，mcp__mindthread__list_accounts 只放行一個。萬用字元只能接在 mcp__伺服器名__ 後面，單寫 mcp__* 的 allow 規則會被略過。之前在核准提示按了拒絕、現在想重來，跑 claude mcp reset-project-choices。
3. 工具太多塞 context（照官方文件）。 每個接上的伺服器都會佔一點 context，因為工具名稱和伺服器說明每次都會載入。Claude Code 在 Opus 4、Sonnet 4、Haiku 4.5 以後的模型預設開啟 tool search，完整工具定義要用到才載入，所以依文件，實測那 43 個工具不會一開始全進 context（我們沒量實際用量）。關掉 tool search 或用更舊的模型時，工具會一次全部載入。工具回傳超過 10,000 token 會警告，預設上限 25,000 token，超過的內容會存成檔案讓 Claude 需要時再讀。
4. OAuth 過期（照官方文件）。 看到 needs you to sign in again 就開 /mcp 重新登入。要注意 claude -p 這種非互動執行沒有 /mcp 面板，跑不了 OAuth 流程，要先在互動 session 裡登入，或在終端機跑 claude mcp login 名稱。如果你是用 --header 自己帶 token，被拒時 Claude Code 會回報連線失敗，不會叫你登入，要去換 token。
我們 11 月 8 日自己碰過一次 claude.ai 連接器的狀況（在 claude.ai 帳號裡授權、同步進 Claude Code 的服務）：換了 Claude Code 的登入帳號之後，Gmail 連接器一直顯示過期，在 /mcp 重新認證沒有恢復，重開 session 才好。這看起來像官方文件描述的「session token rejected」：被拒的是你的 Claude Code 登入，重新授權連接器沒用，官方的處理順序是先 /login，再從 /mcp 重新連線。我們當時沒先試 /login，也沒核對面板上的確切字樣。
5. Windows 路徑（實測）。 ~/.claude.json 在 Windows 是 %USERPROFILE%\.claude.json。在 .mcp.json 裡寫 Windows 路徑，反斜線要寫兩個（C:\\Program Files\\...），我們故意只寫一個，claude mcp list 回報 MCP config is not a valid JSON，整個專案設定都沒載入。Windows 10 預設主控台會把 ✔、✘ 顯示成 √、×，官方文件有寫，不是壞掉。
6. 專案與全域範圍衝突（實測）。 同一個名字在 local 和 user 各有一份時，Claude Code 只用優先序最高的，順序是 local、project、user，欄位不合併。我們實測兩份指令不同時，claude mcp list 會出現 [Conflicting scopes] 警告，直接打 claude mcp remove mindthread 會被擋下，要指定 -s local 或 -s user 才刪得掉。官方文件也提醒，OAuth 登入是照端點分開存的，兩份設定指向不同端點，就要各登入一次。
我們自己怎麼用
我們的產品 MindThread 有一套 MCP server，套件 mindthread-mcp 在 npm 上，也登記在官方 MCP Registry（名稱 io.github.ppcvote/mindthread）。它是把 stdio 轉接到 MindThread 線上 API 的橋，所以工具清單跟著伺服器更新，不用重裝套件。接上之後實際怎麼用，可以看用 MindThread MCP 拉出最佳貼文再起草那篇。
我們自己的 Claude Code 工作視窗常常一開好幾個小時，上面接著幾個 MCP server，人不在電腦前就用手機看進度，做法在 Claude Code Remote Control 教學。照這篇做卡住時，依序跑 claude mcp list 看狀態、claude mcp get 名稱 看細節，再把那段指令單獨在終端機跑一次。
常見問題
Claude Code 的 MCP 設定檔存在哪裡？
看 scope。local 和 user 都存在家目錄的 ~/.claude.json（Windows 是 %USERPROFILE%\.claude.json），local 記在目前專案底下，user 記在最上層的 mcpServers；project 存在專案根目錄的 .mcp.json。Claude Code 不讀 ~/.claude/mcp.json 這類路徑，手動改錯檔案是設定沒生效的常見原因。
local、project、user 三種 scope 要怎麼選？
只有你自己、只在這個專案用，選 local（預設）；要讓整個團隊 clone 下來就有，選 project，設定寫進 .mcp.json 進版控；你自己在每個專案都要用，選 user。同一個名字在多個 scope 都有時，Claude Code 只用優先序最高的那份，順序是 local、project、user，欄位不會合併。
SSE 傳輸還能用嗎？
還能用，但官方文件已標為棄用，建議改用 HTTP。只提供 SSE 端點的服務，一樣用 claude mcp add --transport http 加，Claude Code 2.1.265 以後會先試 HTTP、對方不接受再自動改用 SSE；更舊的版本才需要寫 --transport sse。
接很多 MCP server 會不會把 context 吃光？
在較新的模型上影響不大。Claude Code 在 Claude Opus 4、Sonnet 4、Haiku 4.5 以後的模型預設開啟 tool search，session 開始時只載入工具名稱和伺服器說明，完整的工具定義要用到時才載入；用更舊的模型、設了 ENABLE_TOOL_SEARCH=false 或部分企業環境，工具會一次全部載入。工具回傳的內容另有上限：超過 10,000 token 會警告，預設上限 25,000 token，可用 MAX_MCP_OUTPUT_TOKENS 調整。用不到的伺服器還是建議移除。