---

name: troubleshoot-mcp-connection locale: wenyan-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-05-03" description: > Diagnose and fix MCP server connection issues between Claude Code, Claude Desktop, and MCP servers. Covers Windows argument parsing, authentication failures, transport issues, and platform-specific debugging. Use when Claude Code or Claude Desktop fails to connect to an MCP server, when MCP tools don't appear in sessions, on "cannot attach the server" errors, when a working connection has stopped, or when setting up MCP on a new machine. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: mcp-integration complexity: intermediate language: multi tags: mcp, troubleshooting, debugging, connection, windows

排MCP

診MCP接敗、解之。

用

• Claude Code/Desktop 接 MCP 敗→用
• 會中無 MCP 工→用
• 「Cannot attach the server」→用
• 前通今絕→用
• 新機設 MCP→用

入

• 必：誤訊或徵
• 必：何客（Code、Desktop、二者）
• 必：何 MCP（mcptools、HF、自製）
• 可：近設或環之變

行

一：辨客與配

Claude Code（WSL）：

# View MCP configuration
claude mcp list
claude mcp get server-name

# Configuration stored in
cat ~/.claude.json | python3 -m json.tool

Claude Desktop（Windows）：

# Configuration file location
cat "/mnt/c/Users/$USER/AppData/Roaming/Claude/claude_desktop_config.json"

得：配檔可讀，示 MCP 條目（command、args、env）。

敗：配檔不存或空→未嘗設。從 configure-mcp-server 始。

二：獨試器

R mcptools：

# Test if R can start the server
"/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe" -e "mcptools::mcp_server()"

若敗：

• 察 R 路：ls "/mnt/c/Program Files/R/"
• 察 mcptools 已裝：Rscript -e "library(mcptools)"
• 察 ellmer 依：Rscript -e "library(ellmer)"

HF MCP：

# Test mcp-remote directly
mcp-remote https://huggingface.co/mcp

# Check if mcp-remote is installed
which mcp-remote
npm list -g mcp-remote

得：器啟，吐初訊（JSON-RPC 握手或「listening」），無誤。

敗：mcptools 敗→驗 R 版路、mcptools 入庫。mcp-remote 敗→npm install -g mcp-remote 重裝、驗於 PATH。

三：診常誤

「Cannot attach the server」（Desktop）

本：Windows 參析。

修：用環變代 --header：

{
  "hf-mcp-server": {
    "command": "mcp-remote",
    "args": ["https://huggingface.co/mcp"],
    "env": { "HF_TOKEN": "your_token" }
  }
}

且驗 mcp-remote 全裝（npm install -g mcp-remote），勿賴 npx。

「Connection refused」

• 器未行或港誤
• 防火牆阻
• 傳型誤（stdio vs HTTP）

「Command not found」

• 缺執全路
• PATH 未設於行境
• Windows：含空之路用 C:\\PROGRA~1\\...

工不見而無誤

• 器啟而工未註
• 察器 stdout 初訊
• 驗器用正 MCP 協版

得：誤合一類（不能附、拒接、命未尋、默敗）。

敗：無類合→錄全誤、察器側日。於 GitHub 議搜原訊。

四：察網與認

# Test Hugging Face API connectivity
curl -I "https://huggingface.co/mcp"

# Verify token validity
curl -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/whoami

得：HTTP 返 200，whoami 返 HF 用名，網與認皆通。

敗：curl 報接誤→察 DNS 與代理。令拒（401）→於 huggingface.co/settings/tokens 重生、更配。

五：驗 JSON 配

# Validate JSON (common issue: trailing commas, missing quotes)
python3 -m json.tool /path/to/config.json

得：JSON 析無誤，配檔法正。

敗：常誤為末逗、缺引、括不對。修報之誤、再驗。

六：分台診

Windows（Desktop）：

• 參析異於 Unix
• 路含空則命敗
• 用 8.3 短路：C:\PROGRA~1\R\R-45~1.0\bin\x64\Rscript.exe
• 環變較命列頭可靠

WSL（Code）：

• Unix 引法正
• 含空之全路（須引）可
• npm/npx 經 NVM：驗 NVM 載於行境

得：分台問題已辨（Windows 參、WSL 路、NVM 境）。

敗：Windows 因→由命列換環變認。WSL 因→驗 Windows 執路經 /mnt/c/... 可達。

七：重設

末計：

# Remove and re-add the server (Claude Code)
claude mcp remove server-name
claude mcp add server-name stdio "/full/path/to/executable" -- args

# Restart Claude Desktop after config changes
# (close and reopen the application)

得：移而重添後，claude mcp list 示器配正、新接成。

敗：重添敗→驗執路、命直行可。Desktop→確全閉（察系托盤）乃重啟。

八：察日

Claude Code：啟會時察終端 MCP 誤。

Claude Desktop：察應用日（位依 OS）。

器側：加日捕入請與誤。

得：日揭敗點（啟、握手、認、工註）。

敗：無日→重導 stderr 入檔、復現。Desktop→察 %APPDATA%\Claude\logs\。

驗

• 器獨啟無誤
• JSON 配正
• 客接成
• MCP 工現於會
• 工召成
• 接續多請

忌

• 改誤配：Code（~/.claude.json）vs Desktop（%APPDATA%\Claude\claude_desktop_config.json）
• 改後不重啟：Desktop 須重啟；Code 新會自承新配
• 限境用 npx：npx 行時下包。網或權限受限→全裝
• 令過期：HF 令可過。認忽敗→重生
• 版不合：MCP 協版客器須相容

參

• configure-mcp-server - 初設
• build-custom-mcp-server - 自製器之診境
• setup-wsl-dev-environment - WSL 前置