MCP让Claude连上外部世界，我踩了5个坑才跑通

这周一终于下定决心要给Claude Code接个数据库server。想着挺简单，不就是把几个工具串起来嘛，抄几行配置的事。结果折腾了两天。现在回头看，MCP本身不难，难的全是他妈的细节。参数放哪边、路径怎么写、日志往哪打------每个单独拎出来都不复杂，但凑一块儿就容易把人绕进去。分享一下我踩过的坑，希望你能少走那两天的弯路。

第一个坑：JSON-RPC parse error------最诡异的连接失败

连接失败这事我预到了，毕竟第一次配。但报错信息让我有点懵：

vbscript 复制代码

Error: Server process exited unexpectedly with code 1
Connection to MCP server lost

换个server试试，问题依旧。我先怀疑是网络，又怀疑包没装好，删了重装好几遍，npx把那个包反复下载，进度条来回跑------就是连不上。在终端里裸跑了一下server脚本，发现第一行输出是：

vbscript 复制代码

MCP server starting...

哦豁。在MCP的stdio传输模式下，stdout是唯一的协议通道。你的print、console.log、甚至是启动时的Banner艺术字，都会被客户端当成JSON报文去解析。读到一串普通字符串，解析器直接原地爆炸。所以所有非协议的日志输出，必须走stderr。

Node.js：

javascript 复制代码

// 错误写法
console.log("Server starting...")

// 正确写法
console.error("Server starting...")

// 或者用专门的日志库，确保输出到stderr

Python：

python 复制代码

import sys

# 错误写法
print("Server starting...")

# 正确写法
print("Server starting...", file=sys.stderr)

这个问题占MCP连接失败的43%，网上搜到的报错经常只说"connection closed"，不会告诉你根因在哪。如果你也遇到莫名奇妙的连接失败，先在终端里跑一下server，看第一行输出是不是 { 开头。

第二个坑：命令行参数放错位置------最无语的坑

当时从某个仓库的README里抄了条命令：

sql 复制代码

claude mcp add db -- npx server --transport stdio

敲下去，连不上。我对着终端的报错折腾了快一个小时。官方文档写得明明白白，但那个README写得含糊，我就按直觉摆了。正确的语法是：所有选项必须在服务器名字「之前」，-- 之后跟的才是启动server的命令 。上面那条命令里 --transport stdio 跑到了 -- 后面，被当成了传给server的参数，自然不认。再加上，stdio 是MCP的默认传输类型，根本不用写。所以这条命令的正确答案就是：

sql 复制代码

claude mcp add db -- npx server

秒连。但如果我要指定环境变量呢？

css 复制代码

claude mcp add db --transport stdio --env DATABASE_URL=xxx -- npx @modelcontextprotocol/server-sqlite

选项在名字之前，-- 之后是启动命令，--env 作为选项传入。记住这个顺序就不会错。

第三个坑：spawn ENOENT------路径问题

这个问题比较隐蔽，有时候能连上，有时候又不行，换个终端就不行了。报错通常是：

javascript 复制代码

Error: spawn xxx ENOENT

说明找不到命令。可能的原因：

命令不在PATH里
包没装好
用了相对路径

最稳妥的解法是用绝对路径。Mac/Linux：

bash 复制代码

# 找到命令的绝对路径
which node

# 然后在配置里写绝对路径
claude mcp add db -- /usr/local/bin/node /path/to/server.js

还有个偷懒的办法------全局安装后直接调用包名：

bash 复制代码

# 先全局安装
npm install -g @modelcontextprotocol/server-filesystem

# 然后配置里直接写包名，不用npx
{
  "command": "server-filesystem",
  "args": ["/path/to/dir"]
}

npx每次都要临时下载，还容易被网络问题卡住，全局安装反而更快。

第四个坑：Windows的cmd包装------最平台的坑

如果你在Windows上跑，千万别直接写npx：

json 复制代码

// 错误写法（Windows不认）
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem"]
}

// 正确写法
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem"]
}

Windows不能直接执行npx，必须用cmd.exe包装一下。另外Windows的路径要转义：

json 复制代码

// 反斜杠要写成双反斜杠
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\Users\xxx\project"]
}

第五个坑：认证信息没传进去

连上之后，调用工具时报认证错误：

vbnet 复制代码

authentication_error: Invalid API key

检查了一下，API key明明配了。问题出在环境变量没传进去。 stdio模式下，MCP server是Claude Code的子进程，不会自动继承你shell里的环境变量。需要在配置里显式传入：

perl 复制代码

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
  }
}

用命令行的话：

bash 复制代码

claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=xxx -- npx -y @modelcontextprotocol/server-github

本地调试的时候，可以用 claude --mcp-debug 开启调试模式，看更详细的错误日志。

总结

配MCP的坑大致分这几类：

协议层问题------stdout污染导致parse error
配置层问题------参数位置、路径写法
平台差异------Windows需要额外包装
认证问题------环境变量要显式传入

每个坑单独看都不复杂，但第一次配容易在细节上翻车。记住几个关键点：日志往stderr打、选项在名字之前、windows用cmd包装、环境变量要显式传入。

配置好之后，Claude Code确实能连接外部世界了。我的数据库server已经跑起来了，下一步打算试试接个Jira和Slack。