博客

MCP故障通常出现在五层：启动命令、运行环境、协议传输、网络地址和身份认证。按层排查比反复重装客户端更有效。

第一步：确认配置是否被加载

• 检查配置文件位置和JSON、TOML格式。
• 使用客户端的MCP列表命令查看服务器是否存在。
• 保存配置后完全重启客户端或新建任务。

Connection closed

这通常表示本地服务器进程启动后立即退出。

• 在普通终端中单独运行服务器启动命令。
• 确认Node.js、NPX、Python或UVX存在。
• 检查包名、参数、路径和环境变量。
• Windows下尝试客户端官方建议的cmd /c包装。
• 确保服务器日志写入stderr，不要把调试文字写进stdio协议输出。

启动超时

• 首次运行需要下载依赖，手动执行一次安装命令。
• 检查代理、DNS和包管理器镜像。
• 确认安全软件没有阻止子进程。
• 在客户端支持时适当增加启动超时，但先找出真正原因。

远程服务器返回404

404通常表示URL不正确。MCP地址往往以/mcp结尾，不能直接填写网站首页、管理后台或普通API根地址。检查是否使用了服务商给出的完整端点。

401与403

• 401：令牌缺失、错误、过期或环境变量未加载。
• 403：账号已识别，但没有调用对应资源或工具的权限。
• Bearer Token不要重复添加Bearer前缀。
• 修改用户环境变量后重新打开终端并重启客户端。
• OAuth服务通过客户端提供的登录入口完成认证。

工具没有显示

• 服务器可能连接成功但没有声明Tools。
• 客户端可能禁用了该服务器或部分工具。
• 服务器初始化失败时查看客户端日志。
• 工具数量较多时，客户端可能使用按需发现机制。

最小排错记录

反馈问题时应提供客户端名称与版本、操作系统、服务器名称、传输方式、已脱敏配置、完整错误信息和复现步骤。不要公开API Key、Cookie或Authorization请求头。

官方资料

MCP调试指南

Windows上的本地MCP Server通常依赖Node.js、NPX、Python或UVX。远程HTTP服务器一般不需要在本机安装运行时，但可能需要环境变量保存令牌。

先识别服务器类型

• 命令以npx开头：安装Node.js与npm。
• 命令以uvx开头：安装uv，部分项目还需要Python。
• 命令是python或python.exe：安装项目要求的Python版本。
• 配置只提供https://.../mcp：通常属于远程服务器。

检查Node.js和NPX

node --version
npm --version
npx --version
where.exe node
where.exe npx

任一命令提示找不到时，重新安装运行时并确认安装目录已经加入PATH。修改PATH后重新打开PowerShell和MCP客户端。

检查Python与UVX

python --version
py --version
uv --version
uvx --version
where.exe python
where.exe uvx

不要同时混用多个来源不明的Python环境。优先按照MCP项目官方说明选择运行方式。

设置用户环境变量

[Environment]::SetEnvironmentVariable("EXAMPLE_API_KEY", "你的密钥", "User")
$env:EXAMPLE_API_KEY = "你的密钥"

第一行保存到当前Windows用户，第二行让当前PowerShell会话立即可用。设置完成后仍应重启Codex、Claude或Cursor。

Windows路径写法

在JSON中，Windows反斜杠需要转义：

{
  "args": ["C:UsersusernameDocuments"]
}

原生Windows的NPX包装

部分客户端在原生Windows中不能直接启动NPX，可以使用：

cmd /c npx -y example-mcp-server

是否需要包装取决于客户端和版本，应以客户端官方说明为准。

安装前检查

• 确认项目官方仓库和包名。
• 确认运行时最低版本。
• 确认MCP需要访问的目录和网络。
• 不要复制来源不明的一键脚本。

Claude Desktop可以通过桌面扩展安装MCP，也可以使用配置文件连接自定义本地服务器。普通用户优先使用扩展目录，开发者和需要自定义命令的用户再编辑配置文件。

方法一：安装桌面扩展

1. 打开Claude Desktop设置。
2. 进入Extensions。
3. 选择Browse extensions。
4. 找到需要的扩展并点击Install。
5. 按界面提示填写必要配置或完成登录。

扩展会自动出现在可用工具中。安装后没有显示时，完全退出并重新打开Claude Desktop。

方法二：安装自定义DXT

1. 进入Settings → Extensions。
2. 打开Advanced settings。
3. 在Extension Developer区域选择Install Extension。
4. 选择可信来源提供的.dxt文件。

DXT可能包含本地可执行代码，安装前应确认开发者、签名、权限和下载来源。

方法三：编辑本地MCP配置

在Settings的Developer区域选择Edit Config。常见配置文件位置：

• Windows：%APPDATA%Claudeclaude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

NPX服务器示例：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"]
    }
  }
}

重新启动并验证

保存JSON后要完全退出Claude Desktop再重新启动。打开对话输入框旁的工具入口，检查服务器和工具是否出现。

常见问题

• JSON解析失败：检查逗号、引号和括号。
• 找不到NPX：确认Node.js和npm已安装并位于PATH。
• 路径错误：Windows JSON路径中的反斜杠需要写成。
• 工具调用失败：检查扩展设置、服务器日志和目录权限。

官方资料

Anthropic桌面扩展说明 · MCP本地服务器连接教程

Cursor可以连接本地stdio服务器，也支持SSE和Streamable HTTP远程服务器。你可以通过设置界面添加，也可以使用mcp.json保存配置。

配置文件位置

• 项目级：.cursor/mcp.json
• 全局：~/.cursor/mcp.json

项目级配置只对当前项目生效，适合代码库专用工具；全局配置适合经常使用的个人工具。

配置本地NPX服务器

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"],
      "env": {
        "EXAMPLE_API_KEY": "通过安全方式提供的值"
      }
    }
  }
}

实际使用时不要把真实密钥提交到版本控制。团队共享配置时，应只保留变量名称和安装说明。

配置远程服务器

{
  "mcpServers": {
    "example-remote": {
      "url": "https://example.com/mcp"
    }
  }
}

需要OAuth的服务器可以按Cursor界面提示完成登录。需要自定义认证头时，应以该服务器和当前Cursor版本给出的配置格式为准。

在Cursor中使用工具

配置成功后，MCP工具会出现在Agent可用工具列表中。你可以按名称指定工具，也可以直接描述任务。Cursor默认会在调用工具前要求确认；只有在理解权限和副作用后才考虑自动运行。

常见排错

• 工具不出现：检查JSON格式、文件位置并重启Cursor。
• 本地服务器启动失败：在终端单独运行命令，确认依赖和PATH。
• 远程服务器无法连接：检查URL、认证状态和网络代理。
• 项目配置不生效：确认文件位于当前项目的.cursor目录。

官方资料

Cursor MCP文档

Codex支持本地stdio服务器和远程Streamable HTTP服务器。桌面应用、Codex CLI和IDE扩展会共享同一套MCP配置，因此通常只需要配置一次。

方法一：通过Codex CLI添加

添加本地stdio服务器

codex mcp add <服务器名称> -- <启动命令> [参数]

例如使用NPX启动一个服务器：

codex mcp add example -- npx -y example-mcp-server

添加远程HTTP服务器

codex mcp add example --url https://example.com/mcp

服务器需要Bearer Token时，建议把令牌保存在环境变量中：

[Environment]::SetEnvironmentVariable("EXAMPLE_MCP_TOKEN", "你的令牌", "User")
codex mcp add example --url https://example.com/mcp --bearer-token-env-var EXAMPLE_MCP_TOKEN

完成后重启Codex，使新的用户环境变量和MCP配置生效。

方法二：通过桌面应用添加

1. 打开Codex设置。
2. 进入MCP servers。
3. 选择Add server。
4. 填写名称，并选择STDIO或Streamable HTTP。
5. 填写启动命令或服务器地址。
6. 保存后重启Codex。

方法三：编辑config.toml

全局配置通常位于~/.codex/config.toml。本地服务器示例：

[mcp_servers.example]
command = "npx"
args = ["-y", "example-mcp-server"]

远程服务器示例：

[mcp_servers.example_remote]
url = "https://example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN"

密钥不要直接写进配置文件，更不要提交到Git仓库。

管理MCP服务器

codex mcp list
codex mcp get example
codex mcp remove example
codex mcp login example

login适用于支持OAuth的远程服务器。在Codex交互界面中也可以输入/mcp查看当前服务器。

验证连接

先运行codex mcp list确认服务器已启用，再新建任务并要求Codex列出该服务器的工具。如果无法初始化，优先检查启动命令、URL、环境变量和客户端重启状态。

官方资料

OpenAI Codex MCP文档

Claude Code可以通过命令行连接本地stdio、远程HTTP和SSE类型的MCP Server。开始前请确认Claude Code已安装并完成登录。

添加本地stdio服务器

claude mcp add <服务器名称> -- <启动命令> [参数]

NPX示例：

claude mcp add example -- npx -y example-mcp-server

--用于分隔Claude Code自己的参数和服务器启动命令。

添加远程HTTP服务器

claude mcp add --transport http example https://example.com/mcp

添加SSE服务器

claude mcp add --transport sse example https://example.com/sse

新项目优先查看服务器是否支持Streamable HTTP。SSE常见于较早部署或特定服务。

选择配置范围

• local：默认，仅当前项目和当前用户使用，适合私有凭据与实验。
• project：写入项目的.mcp.json，适合团队共享不含密钥的配置。
• user：当前用户所有项目可用。

claude mcp add example --scope user -- npx -y example-mcp-server

Windows注意事项

在原生Windows中，本地NPX服务器可能需要通过cmd /c启动：

claude mcp add example -- cmd /c npx -y example-mcp-server

如果仍提示Connection closed，检查Node.js、NPX、PATH和服务器包名。

管理服务器

claude mcp list
claude mcp get example
claude mcp remove example

在Claude Code会话内输入/mcp可以查看状态，并为支持OAuth的远程服务器完成登录。

安全提示

不要把API Key直接提交到.mcp.json。项目级配置适合共享命令和变量名称，真实凭据应放在环境变量或安全存储中。

官方资料

Claude Code MCP文档

MCP全称Model Context Protocol，是一套让AI应用连接外部工具、数据和工作流的开放协议。它不负责训练模型，也不是一个具体的AI产品，更像一套统一的连接规范。

MCP解决什么问题

没有MCP时，每个AI客户端都需要单独适配GitHub、数据库、浏览器、文件系统或企业服务。MCP把常见的连接、能力发现和调用过程标准化，让同一个MCP Server可以被多个兼容客户端使用。

三个核心角色

• 主机：用户直接使用的AI应用，例如Codex、Claude Code或Cursor。
• 客户端：主机内部负责与某个MCP Server保持连接的组件。
• 服务器：向AI应用暴露工具、资源或提示模板的程序。

服务器可以提供什么

• Tools：可以执行动作的函数，例如查询数据库、创建Issue或控制浏览器。
• Resources：供客户端读取的上下文数据，例如文件、文档和数据库记录。
• Prompts：服务器提供的可复用任务模板。

两种常见连接方式

stdio

客户端在本机启动一个命令行进程，并通过标准输入输出通信。它适合访问本地文件、开发工具或需要低延迟的个人环境。

npx -y example-mcp-server

Streamable HTTP

客户端连接到一个HTTP地址。服务器可以由厂商或团队统一托管，适合OAuth、多人使用和持续在线的服务。

https://example.com/mcp

一次完整连接会发生什么

1. 客户端启动本地进程或访问远程地址。
2. 双方协商协议版本和支持能力。
3. 客户端读取服务器提供的工具、资源和说明。
4. 用户提出任务，模型选择合适的工具。
5. 客户端按权限策略确认并执行调用。
6. 服务器返回结果，模型继续完成任务。

新手如何选择

如果工具需要访问本地目录、IDE或命令行，通常选择stdio；如果服务由厂商托管、需要登录或希望多设备使用，通常选择Streamable HTTP。安装前应先确认项目来源、运行命令、权限范围和认证方式。

官方资料

MCP架构说明 · MCP服务器概念