报错会直接阻断ai调用工具链，需先通过output面板mcp日志定位错误类型：connection refused说明服务未启动，request timeout说明服务卡死，tools[0]: missing field function则属openai协议不兼容。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Cursor配置MCP后报错会直接阻断AI调用工具链，对话框卡在“Waiting for extension host”或弹出红色Error标志，此时必须逐层定位是环境、配置、服务还是协议层面的问题。
先确认报错类型和可观测信号
打开 Cursor → Output 面板 → 切换到 MCP 标签页，完整查看日志输出。重点关注三类关键线索：【Connection refused】 表示TCP连接被拒绝，说明服务根本没起来；【Request timeout after 15000ms】 表示连接成功但无响应，大概率是服务启动了但卡死或未就绪；如果日志里出现 tools[0]: missing field function，则属于OpenAI新版Tool Calling协议不兼容，必须改JSON结构。
不要跳过这一步——不同错误类型对应完全不同的修复路径，混用方案只会延长故障时间。
检查Node.js与Python环境版本
方法一：Windows下验证Node.js版本是否达标
在PowerShell中执行 node -v，若返回 v14.17.0 或更低，立即卸载并重装Node.js 18.x LTS版本。安装时务必勾选 【Add to PATH】 和 【Automatically install the necessary tools】，否则npx命令在Cursor沙箱中不可见。
方法二：Python环境清理与重装
执行 pip show mcp，若显示 v0.8.3 或 v0.9.x，说明版本过旧。运行 pip uninstall mcp pymysql uv -y 彻底清除残留，再执行 pip install "mcp[cli]==1.2.0" pymysql==1.1.0 uv==0.1.1。旧版FastMCP类已被移除，代码中所有 from mcp.server.fastmcp import FastMCP 必须改为 from mcp import FastMCP。
修正MCP服务端点配置
第一步：统一使用 http://127.0.0.1:8080 而非 localhost 或 https
macOS和部分代理环境下，localhost 会被解析为IPv6地址 ::1，导致连接失败。直接写死 127.0.0.1 可绕过DNS解析环节。
第二步：验证端点是否真实可通
在终端运行 curl -I http://127.0.0.1:8080/health。如果返回 HTTP/1.1 200 OK，说明服务已就绪；若提示 Failed to connect，说明服务进程未启动或端口被占用。
第三步：检查配置中 command 字段的可执行性
Windows用户需在 npx 前加 cmd /c 前缀，例如："command": "cmd /c npx"。否则Cursor在Windows子系统下调用会静默失败，且不报任何错误信息。
处理多MCP并存冲突
若同时配置了Figma、MySQL、Playwright等多个MCP服务，发现只有第一个能用，其余显示Error或无响应——大概率是端口冲突或环境变量覆盖。【LSP默认端口8081被重复绑定】 是最常见原因。解决方案：为每个服务手动指定唯一端口，在其配置的 args 中加入 --port 8082、--port 8083 等参数。
另一个隐藏陷阱是 MCP_CONFIG_PATH 环境变量被后加载插件覆盖。临时解决办法：在每个MCP配置的 env 字段中显式声明该变量，指向各自独立的YAML路径，例如 "MCP_CONFIG_PATH": "/Users/xxx/mcp-figma/config.yaml"。
强制恢复Extension Host响应
当对话框持续显示“Taking longer than expected…”且无法输入时，说明Extension Host已被拖垮。
按下 Cmd + Shift + P（macOS）或 Ctrl + Shift + P（Windows），输入并执行 Developer: Reload Window。
若软重启无效，立刻打开活动监视器（macOS）或任务管理器（Windows），搜索并强制结束所有名为 Cursor Helper (Plugin) 和 node 的进程。结束后再启动Cursor，进入设置→MCP，先禁用全部服务，再逐个启用排查。
