连接 MCP Inspector 报错 Connection Error, is your MCP server running? 的原因与解决方案

最新推荐文章于 2025-07-24 15:40:39 发布

原创最新推荐文章于 2025-07-24 15:40:39 发布 · 3k 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能

人工智能专栏收录该内容

364 篇文章

订阅专栏

在实际开发中，npx @modelcontextprotocol/inspector 能够快速启动一套图形化调试环境：浏览器侧的 MCP Inspector 客户端默认监听 http://127.0.0.1:6274，而本地同进程自动拉起的 MCP Proxy 服务则默认占用 6277 端口，用来把浏览器发出的 WebSocket、SSE 或 HTTP 请求转发到真正的 MCP 服务器。只要目标 MCP 服务器可达、协议栈匹配，这两个端口就像一座桥，将可视化面板与后端推理代码连成一体。然而，一旦背后的 MCP 服务器未启动、端口冲突、传输方式配置不一致，Inspector 无法与 Proxy 完成握手，浏览器便会直白地抛出 Connection Error, is your MCP server running?。这行红字既提醒开发者去检查后端是否在线，也暗示着网络与协议链路中仍有某个环节失灵。下文通过通信原理拆解、常见故障排查、可运行示例与真实案例复盘，展示完整的定位与修复流程，帮助你彻底消除这条令人挠头的错误提示。

错误信息背后的通信链路

Inspector 与 Proxy 的分工

官方 README 指出，启动命令会同时生成两个进程：MCPI（端口 6274）负责提供浏览器 UI，MCPP（端口 6277）负责转发流量(npmjs.com, github.com)。
端口号来自电话号码 T9 键盘映射：MCPI → 6274，MCPP → 6277，便于记忆(npmjs.com)。
浏览器点击 Connect 时，前端会通过 WebSocket 或 SSE 先连到 MCPP，再由后者把消息路由到真正的 MCP 服务器(modelcontextprotocol.io, bootcamptoprod.com)。

报错产生的典型链路断点

MCP 服务器进程根本未启动：Inspector 只负责 UI 与代理，并不会帮你拉起自定义推理服务。如果 6277 后面接的是空气，自然握手失败。Stack Overflow 上不少帖子都验证了这一点(stackoverflow.com, stackoverflow.com)。
端口占用或冲突：若本机已有其他程序监听 6277，Proxy 启动会报 EADDRINUSE，但 UI 仍会起来，导致点击连接时抛错。Reddit 社区有用户多次复现该现象(reddit.com)。
网络防火墙 / 杀毒软件拦截 SSE 流：某些安全套件会阻断长连接流式响应，Kaspersky 论坛给出过拦截示例(forum.kaspersky.com)。
传输方式不匹配：Inspector 支持 stdio、SSE、WebSocket 等多种 Transport。如果后端仅实现了 stdio 而 UI 选了 SSE，就会看到上文报错(reddit.com)。
代理配置指向错误 URL：开源博客 BootcampToProd 与 Cloudflare Dev 文档均强调 UI 里需填写完整公网地址或 localhost，否则 Proxy 会报 404/502(bootcamptoprod.com, developers.cloudflare.com)。

快速自检与排错流程

步骤一：确认 MCP 服务端口

# 假设你在 Node.js 项目里
npx mcp dev server.js
# 也可在 Python 环境下
mcp dev server.py

终端应出现：

Starting MCP inspector…
⚙️  Proxy server listening on port 6277
MCP Inspector is up and running at http://127.0.0.1:6274

若缺少 Proxy server listening 行，则说明 6277 被占用或权限不足，可用 lsof -i:6277 查占用进程并释放(stackoverflow.com, reddit.com)。

步骤二：用 `curl` 验证代理可达

curl -N http://127.0.0.1:6277/healthz
# 预期返回 {"status":"ok"}

空白或连接拒绝即表明 Proxy 没起来。

步骤三：直连 MCP 服务器

若你的后端运行在 http://localhost:4000/mcp, 先跳过 Inspector，用 curl 或 Postman 直接 POST 一条 {"role":"user","content":"ping"}，观察返回。如果后端都不响应，问题与 Inspector 无关，需先修复业务服务器(github.com)。

步骤四：对照 transport 设置

Inspector UI 顶栏可选 stdio、SSE、WS。务必选中与你后端实现一致的选项。Stack Overflow 贴给出的示例，Python 开发者把 transport 切回 stdio 立刻恢复连接(stackoverflow.com)。

步骤五：鉴别防火墙拦截

若只在公司网络或装有防毒软件时失败，可暂时停用拦截服务，或自签证书改用 https://127.0.0.1，绕开明文 SSE 被拦截的风险(forum.kaspersky.com)。

可运行 Node.js 示例：从零到连通

以下工程能在 2 分钟内复现完整链路：

# 1\. 初始化
mkdir mcp-echo && cd mcp-echo
npm init -y
npm install @modelcontextprotocol/agent @modelcontextprotocol/inspector

# 2\. 编写 echo-server.js

// echo-server.js
import { createAgent, stdioTransport } from "@modelcontextprotocol/agent";

const agent = createAgent()
  .tool({
    name: "echo",
    description: "Return whatever the user says",
    run: async ({ input }) => ({ content: input })
  })
  .listen(stdioTransport());

console.log("Echo MCP server ready (stdio)");
// 按 Ctrl+C 可停止

# 3\. 启动 Inspector 并托管后端
npx @modelcontextprotocol/inspector -- node echo-server.js

-- 之后的参数将传给后端脚本；Inspector 会先起代理再调用 Node 进程(npmjs.com)。
浏览器打开 http://127.0.0.1:6274，Transport 选择 stdio，点击 Connect。工作区左侧出现工具 echo，在 Prompt 区输入 hello 应得到 hello 回应，证明链路打通。

若想改用 SSE 或 WebSocket，只需把 stdioTransport() 替换为 sseTransport({ port:5001 })，同时在 Inspector UI 把传输方式切换一致即可。

Python 快速示例

有时后端使用 Python 更便捷，可参考下述脚本：

# echo_server.py
from mcp.dev import tools, stdio

@tools.register
def echo(user: str) -> str:
    "`返回原文`"
    return user

if __name__ == "__main__":
    stdio.serve()

依赖安装：

pip install mcp-dev
npx @modelcontextprotocol/inspector -- python echo_server.py

Stack Overflow 记录表明，仅在 transport 与脚本不匹配时才会出现最初的报错(stackoverflow.com)。

真实案例复盘

n8n 自托管实例：社区用户在 Railway 上部署 n8n，并用 mcp client 拉流时遇到相同报错。最终发现 Railway 把 6277 端口映射到外网后，需要在 Inspector 里填写公网 URL，而非默认 localhost。
Kaspersky 阻断 SSE：安全软件误把长连接认定为恶意，导致 Inspector 前端持续重连并抛出同样错误。白名单放行后立即恢复连接。
端口残留进程：开发者两次重复启动 mcp dev，第一次进程未正确退出，6277 被占用；杀死旧进程后问题解决。

总结与最佳实践

确认三端在线：浏览器 6274 → Proxy 6277 → MCP Server，一环缺失即报错。
端口自定义：可用 -p 7000 -P 7003 修改 UI 与 Proxy 端口，避免占用。
Transport 对齐：stdio 通常最简；若需跨网络流式输出，SSE 更稳健。
监控日志：为 Proxy 启用 DEBUG=mcp:*，可看到每次握手的 request/response，诊断更直观(bootcamptoprod.com)。
自动化健康检查：在 CI/CD 中使用 curl 127.0.0.1:6277/healthz 保证 Proxy 启动成功；MCP 服务器可在启动脚本尾部打印 ready。
防火墙与代理：企业网络需允许 6274/6277 或自定义端口在本机环回接口上畅通。

只要遵循上述步骤，Connection Error, is your MCP server running? 将不再是难题，而是提醒我们回到链路本身进行系统化排查的友好助手。

参考资料

GitHub modelcontextprotocol/inspector 项目首页(github.com)
Stack Overflow 帖子《The Python MCP server with stdio transport throws an error》(stackoverflow.com)
官方文档《Inspector - Model Context Protocol》(modelcontextprotocol.io)
n8n Issues #14539 讨论(github.com)
npmjs 包说明 @modelcontextprotocol/inspector 0.13.0(npmjs.com)
Kaspersky 社区话题《SSE connection blocked》(forum.kaspersky.com)
Reddit 讨论《MCP SSE transport being deprecated?》(reddit.com)
Cloudflare Agents 文档《Test a Remote MCP Server》(developers.cloudflare.com)
Stack Overflow 问答《I meet the Error Connecting to MCP Inspector Proxy》(stackoverflow.com)
Reddit 帖子《Proxy Server PORT IS IN USE at port 6277 Error in MCP Inspector》(reddit.com)
BootcampToProd 博客《MCP Inspector: Debugging Your MCP Servers Made Easy》(bootcamptoprod.com)
Medium 文章《Getting Started with Model Context Protocol》(medium.com)
GitHub 文档 mcp-dust-server DEVELOPERS.md 中关于常见错误说明(github.com)
kgateway.dev 指南《MCP Gateway》《Proxy server listening on port 6277》(kgateway.dev)