Back to Details

troubleshoot-mcp-connection

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Troubleshoot MCP Connection

MCP连接故障排查

Diagnose and resolve MCP server connection failures.
诊断并解决MCP服务器连接失败问题。

When to Use

适用场景

  • Claude Code or Claude Desktop fails to connect to an MCP server
  • MCP tools don't appear in sessions
  • "Cannot attach the server" errors
  • Connection was working but stopped
  • Setting up MCP on a new machine
  • Claude Code或Claude Desktop无法连接MCP服务器
  • 会话中未显示MCP工具
  • 出现“无法连接服务器”错误
  • 原本正常的连接突然中断
  • 在新机器上配置MCP

Inputs

输入信息

  • Required: Error message or symptom description
  • Required: Which client (Claude Code, Claude Desktop, or both)
  • Required: Which MCP server (mcptools, Hugging Face, custom)
  • Optional: Recent changes to configuration or environment
  • 必填：错误信息或症状描述
  • 必填：客户端类型（Claude Code、Claude Desktop或两者皆是）
  • 必填：MCP服务器类型（mcptools、Hugging Face、自定义）
  • 可选：近期配置或环境变更情况

Procedure

排查步骤

Step 1: Identify the Client and Configuration

步骤1：确认客户端与配置

Claude Code (WSL):
bash
undefined
Claude Code（WSL环境）：
bash
undefined

View MCP configuration

查看MCP配置

claude mcp list claude mcp get server-name
claude mcp list claude mcp get server-name

Configuration stored in

配置文件存储位置

cat ~/.claude.json | python3 -m json.tool

**Claude Desktop** (Windows):

```bash
cat ~/.claude.json | python3 -m json.tool

**Claude Desktop**（Windows环境）：

```bash

Configuration file location

配置文件位置

cat "/mnt/c/Users/$USER/AppData/Roaming/Claude/claude_desktop_config.json"

**Expected:** Configuration file is located and readable, showing the MCP server entries with command, args, and env fields.

**On failure:** If the config file does not exist or is empty, the server was never configured. Follow the `configure-mcp-server` skill to set it up from scratch.
cat "/mnt/c/Users/$USER/AppData/Roaming/Claude/claude_desktop_config.json"

**预期结果**：配置文件可找到且可读，文件中包含带command、args和env字段的MCP服务器条目。

**若失败**：若配置文件不存在或为空，说明服务器从未配置过。请遵循`configure-mcp-server`技能从头开始配置。

Step 2: Test Server Independently

步骤2：独立测试服务器

R mcptools:
bash
undefined
R mcptools：
bash
undefined

Test if R can start the server

测试R能否启动服务器

"/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe" -e "mcptools::mcp_server()"

If this fails:
- Check R path exists: `ls "/mnt/c/Program Files/R/"`
- Check mcptools is installed: `Rscript -e "library(mcptools)"`
- Check ellmer dependency: `Rscript -e "library(ellmer)"`

**Hugging Face MCP**:

```bash
"/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)"`

**Hugging Face MCP**：

```bash

Test mcp-remote directly

直接测试mcp-remote

mcp-remote https://huggingface.co/mcp
mcp-remote https://huggingface.co/mcp

Check if mcp-remote is installed

检查mcp-remote是否已安装

which mcp-remote npm list -g mcp-remote

**Expected:** The server process starts and produces initialization output (JSON-RPC handshake or "listening" message) without errors.

**On failure:** If R mcptools fails, check that the R version path is correct and that mcptools is installed in the R library. If mcp-remote fails, reinstall globally with `npm install -g mcp-remote` and verify it is on the PATH.
which mcp-remote npm list -g mcp-remote

**预期结果**：服务器进程启动并输出初始化信息（JSON-RPC握手或“监听中”消息），无错误。

**若失败**：若R mcptools失败，检查R版本路径是否正确，且mcptools已安装在R库中。若mcp-remote失败，使用`npm install -g mcp-remote`全局重装，并验证其已加入PATH。

Step 3: Diagnose Common Error Patterns

步骤3：诊断常见错误模式

"Cannot attach the server" (Claude Desktop)
Root cause: Windows command argument parsing.
Fix: Use environment variables instead of 
--header
arguments:
json
{
  "hf-mcp-server": {
    "command": "mcp-remote",
    "args": ["https://huggingface.co/mcp"],
    "env": { "HF_TOKEN": "your_token" }
  }
}
Also ensure 
mcp-remote
is globally installed (
npm install -g mcp-remote
), not relying on 
npx
.
"Connection refused"
  • Server isn't running or port is wrong
  • Firewall blocking the connection
  • Wrong transport type (stdio vs HTTP)
"Command not found"
  • Missing full path to executable
  • PATH not configured in the execution context
  • On Windows: use 
    C:\\PROGRA~1\\...
    for paths with spaces
MCP tools don't appear but no error
  • Server starts but tools aren't registered
  • Check server stdout for initialization messages
  • Verify the server uses the correct MCP protocol version
Expected: Error pattern matched to one of the documented categories (cannot attach, connection refused, command not found, or silent failure).
On failure: If the error does not match any known pattern, capture the full error output and check server-side logs. Search for the exact error message in the MCP server's GitHub issues.
“无法连接服务器”（Claude Desktop）
根本原因：Windows命令参数解析问题。
修复方案：使用环境变量替代
--header
参数：
json
{
  "hf-mcp-server": {
    "command": "mcp-remote",
    "args": ["https://huggingface.co/mcp"],
    "env": { "HF_TOKEN": "your_token" }
  }
}
同时确保
mcp-remote
已全局安装（
npm install -g mcp-remote
），不要依赖
npx
。
“连接被拒绝”
  • 服务器未运行或端口错误
  • 防火墙阻止连接
  • 传输类型错误（stdio vs HTTP）
“命令未找到”
  • 缺少可执行文件的完整路径
  • 执行环境中未配置PATH
  • Windows环境：对含空格的路径使用
    C:\\PROGRA~1\\...
    格式
MCP工具未显示但无错误
  • 服务器启动但未注册工具
  • 检查服务器标准输出的初始化消息
  • 验证服务器使用正确的MCP协议版本
预期结果：错误模式匹配文档中记录的类别之一（无法连接、连接被拒绝、命令未找到或静默失败）。
若失败：若错误不匹配任何已知模式，捕获完整错误输出并检查服务器端日志。在MCP服务器的GitHub issues中搜索确切错误信息。

Step 4: Check Network and Authentication

步骤4：检查网络与认证

bash
undefined
bash
undefined

Test Hugging Face API connectivity

测试Hugging Face API连通性

curl -I "https://huggingface.co/mcp"
curl -I "https://huggingface.co/mcp"

Verify token validity

验证令牌有效性

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

**Expected:** HTTP endpoint returns 200 status and the whoami call returns your Hugging Face username, confirming network connectivity and valid authentication.

**On failure:** If curl returns a connection error, check DNS resolution and proxy settings. If the token is rejected (401), regenerate the token at huggingface.co/settings/tokens and update the configuration.
curl -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/whoami

**预期结果**：HTTP端点返回200状态码，whoami请求返回你的Hugging Face用户名，确认网络连通性和认证有效性。

**若失败**：若curl返回连接错误，检查DNS解析和代理设置。若令牌被拒绝（401），在huggingface.co/settings/tokens重新生成令牌并更新配置。

Step 5: Verify JSON Configuration Syntax

步骤5：验证JSON配置语法

bash
undefined
bash
undefined

Validate JSON (common issue: trailing commas, missing quotes)

验证JSON（常见问题： trailing逗号、缺失引号）

python3 -m json.tool /path/to/config.json

**Expected:** JSON parses without errors, confirming the configuration file has valid syntax.

**On failure:** The most common JSON issues are trailing commas after the last entry in an object or array, missing quotes around string values, and mismatched braces. Fix the syntax error reported by the parser and re-validate.
python3 -m json.tool /path/to/config.json

**预期结果**：JSON解析无错误，确认配置文件语法有效。

**若失败**：最常见的JSON问题是对象或数组最后一个条目后的trailing逗号、字符串值缺失引号、括号不匹配。根据解析器报告修复语法错误并重新验证。

Step 6: Platform-Specific Debugging

步骤6：特定平台调试

Windows (Claude Desktop):
  • Argument parsing differs from Unix
  • Spaces in paths break command execution
  • Use 8.3 short paths: 
    C:\PROGRA~1\R\R-45~1.0\bin\x64\Rscript.exe
  • Environment variables work more reliably than command-line headers
WSL (Claude Code):
  • Unix-style quoting works correctly
  • Can use full paths with spaces (quoted)
  • npm/npx via NVM: ensure NVM is loaded in the execution context
Expected: Platform-specific issue identified (e.g., Windows argument parsing, WSL path resolution, or NVM context loading).
On failure: If the issue is Windows-specific, switch from command-line arguments to environment variables for authentication. If WSL-specific, verify that the Windows executable path is accessible from WSL using the full 
/mnt/c/...
path.
Windows（Claude Desktop）：
  • 参数解析与Unix不同
  • 路径中的空格会导致命令执行失败
  • 使用8.3短路径：
    C:\PROGRA~1\R\R-45~1.0\bin\x64\Rscript.exe
  • 环境变量比命令行头参数更可靠
WSL（Claude Code）：
  • Unix风格引号可正常工作
  • 可使用带空格的完整路径（需加引号）
  • 通过NVM使用npm/npx：确保执行环境中已加载NVM
预期结果：识别出特定平台问题（如Windows参数解析、WSL路径解析或NVM上下文加载）。
若失败：若为Windows特定问题，将命令行参数替换为环境变量进行认证。若为WSL特定问题，使用完整
/mnt/c/...
路径验证Windows可执行文件路径是否能从WSL访问。

Step 7: Reset and Reconfigure

步骤7：重置与重新配置

If all else fails:
bash
undefined
若所有方法均失败：
bash
undefined

Remove and re-add the server (Claude Code)

移除并重新添加服务器（Claude Code）

claude mcp remove server-name claude mcp add server-name stdio "/full/path/to/executable" -- args
claude mcp remove server-name claude mcp add server-name stdio "/full/path/to/executable" -- args

Restart Claude Desktop after config changes

配置变更后重启Claude Desktop

(close and reopen the application)

（关闭并重新打开应用）


**Expected:** After removing and re-adding the server, `claude mcp list` shows the server with the correct configuration and a fresh connection attempt succeeds.

**On failure:** If re-adding fails, check that the executable path is correct and the command works when run directly in the terminal. For Claude Desktop, ensure the application is fully closed (check system tray) before restarting.

**预期结果**：移除并重新添加服务器后，`claude mcp list`显示服务器配置正确，且新的连接尝试成功。

**若失败**：若重新添加失败，检查可执行文件路径是否正确，且命令在终端中直接运行可正常工作。对于Claude Desktop，确保应用已完全关闭（检查系统托盘）后再重启。

Step 8: Check Logs

步骤8：检查日志

Claude Code: Look for MCP errors in the terminal output when starting a session.
Claude Desktop: Check application logs (location varies by OS).
Server-side: Add logging to the MCP server to capture incoming requests and errors.
Expected: Log entries reveal the specific point of failure (server startup, handshake, authentication, or tool registration).
On failure: If no logs are available, add 
stderr
capture to the server command (e.g., redirect to a log file) and reproduce the failure. For Claude Desktop, check 
%APPDATA%\Claude\logs\
for application-level logs.
Claude Code：启动会话时在终端输出中查找MCP错误。
Claude Desktop：检查应用日志（位置因操作系统而异）。
服务器端：为MCP服务器添加日志以捕获传入请求和错误。
预期结果：日志条目揭示具体失败点（服务器启动、握手、认证或工具注册）。
若失败：若无可用日志，为服务器命令添加
stderr
捕获（如重定向到日志文件）并重现故障。对于Claude Desktop，检查
%APPDATA%\Claude\logs\
获取应用级日志。

Validation

验证清单

  • Server starts independently without errors
  • Configuration JSON is valid
  • Client connects successfully
  • MCP tools appear in the session
  • Tools execute correctly when called
  • Connection persists across multiple requests
  • 服务器可独立启动无错误
  • 配置JSON语法有效
  • 客户端连接成功
  • 会话中显示MCP工具
  • 调用工具可正常执行
  • 连接可在多次请求间保持稳定

Common Pitfalls

常见陷阱

  • Editing the wrong config file: Claude Code (
    ~/.claude.json
    ) vs Claude Desktop (
    %APPDATA%\Claude\claude_desktop_config.json
    )
  • Not restarting after config changes: Claude Desktop requires restart; Claude Code picks up changes on new session
  • npx in restricted environments: npx downloads packages at runtime. If network or permissions are restricted, install globally.
  • Token expiration: Hugging Face tokens can expire. Regenerate if auth failures appear suddenly.
  • Version mismatches: MCP protocol versions must be compatible between client and server
  • 编辑错误的配置文件：Claude Code（
    ~/.claude.json
    ）与Claude Desktop（
    %APPDATA%\Claude\claude_desktop_config.json
    ）的配置文件不同
  • 配置变更后未重启：Claude Desktop需要重启；Claude Code在新会话中会自动加载变更
  • 受限环境中使用npx：npx会在运行时下载包。若网络或权限受限，请全局安装
  • 令牌过期：Hugging Face令牌可能过期。若突然出现认证失败，请重新生成令牌
  • 版本不匹配：客户端与服务器的MCP协议版本必须兼容

Related Skills

相关技能

  • configure-mcp-server
    - initial MCP setup
  • build-custom-mcp-server
    - custom server debugging context
  • setup-wsl-dev-environment
    - WSL prerequisite setup
  • configure-mcp-server
    - MCP初始配置
  • build-custom-mcp-server
    - 自定义服务器调试上下文
  • setup-wsl-dev-environment
    - WSL前置环境配置