MCP Server 启动报错 Connection Refused 127.0.0.1 通常是因为客户端尝试通过 HTTP 或 TCP 连接本地端口，但服务器进程未监听该端口或传输模式配置不匹配。优先检查服务器是否成功启动以及客户端配置的传输协议（stdio 还是 http/sse）是否一致，注意不要随意将监听地址改为 0.0.0.0 以免暴露服务。
先说结论：该错误表明本地网络请求被拒绝，核心原因是服务器未在指定端口监听或传输协议配置错误。
- 先确认：MCP Server 进程是否存活且监听模式为 HTTP/SSE 而非 stdio。
- 先处理：核对客户端配置中的端口号与服务器启动参数是否一致。
- 再验证：使用 curl 命令测试本地端口连通性并查看服务器日志。
命令速用版
以下命令用于快速检查端口占用情况和服务连通性，适用于 Linux 和 macOS 环境，Windows 用户可使用等效的 netstat 或 PowerShell 命令。
# 检查指定端口是否被监听（将 8080 替换为实际端口）
netstat -an | grep 8080
# 测试本地连接是否通畅
curl -v http://127.0.0.1:8080
# 查看进程是否运行（根据启动命令关键词搜索）
ps -ef | grep mcp为什么会这样
Connection Refused 错误意味着目标主机 actively 拒绝了连接请求，通常是因为没有进程在目标端口监听。在 MCP 架构中，这往往源于传输层配置不一致，例如客户端配置为 HTTP 连接而服务器实际运行在 stdio 模式，或者服务器启动失败导致端口未绑定。
MCP 支持多种传输方式，本地调试常用 stdio（标准输入输出），远程或特定客户端可能要求 SSE 或 HTTP。如果客户端强制发起 TCP 连接而服务器未开启 HTTP 监听器，操作系统会直接返回 Connection Refused。
分步处理
按照以下顺序排查，每一步完成后观察错误是否消失，避免同时修改多个配置导致无法定位问题。
步骤 1：确认服务器进程状态
检查 MCP Server 进程是否在运行，且没有因为异常退出而停止。查看终端输出或日志文件，确认没有报错退出。
步骤 2：核对传输协议配置
检查客户端配置文件（如 IDE 插件配置或代码中的 Client 初始化参数）。确认 transport 类型是 http 还是 stdio。如果配置为 http，服务器必须启动 HTTP 服务；如果配置为 stdio，客户端不应尝试连接 127.0.0.1 端口。
步骤 3：检查端口绑定地址
确认服务器绑定的地址是 127.0.0.1 还是 localhost。某些环境下 localhost 可能解析为 IPv6 地址 ::1，而客户端请求的是 IPv4 127.0.0.1。尝试在服务器启动参数中明确指定 host 为 127.0.0.1。
步骤 4：排查防火墙或安全软件
虽然本地回环流量通常不受限制，但部分安全软件可能拦截本地特定端口的连接。临时关闭防火墙测试，若问题解决则需添加本地回环放行规则。
怎么验证是否生效
执行 curl 命令后，如果返回 HTTP 状态码（如 200 OK 或 404 Not Found）而非 Connection Refused，说明网络层连通性已恢复。随后在 MCP 客户端中重新触发工具调用，观察是否能正常接收服务器响应。
查看服务器日志，确认没有新的连接拒绝报错，且能看到来自 127.0.0.1 的请求记录。
常见坑
- 传输模式混淆：很多本地 MCP 示例默认使用 stdio，直接配置 HTTP 端口会导致连接失败。
- 端口冲突：指定端口被其他程序占用，导致 MCP Server 启动时绑定失败但未明显报错。
- IPv6 优先：系统默认优先解析 localhost 为 IPv6，而服务器仅监听 IPv4，导致地址不匹配。
常见问题
为什么本地 MCP 推荐用 stdio 而不是 HTTP？
Stdio 模式无需占用网络端口，启动更快且安全性更高，适合本地进程间通信。
修改端口后仍然报错怎么办？
确认客户端配置同步修改了新端口，并检查是否有防火墙规则阻止了新端口的本地通信。
服务器日志没有显示任何连接请求？
说明请求在到达应用层之前被拒绝，重点检查端口监听状态和 IP 版本匹配问题。