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

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

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

 复制代码Error: Server process exited unexpectedly with code 1
Connection to MCP server lost

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

 复制代码MCP server starting...

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

Node.js：

 复制代码// 错误写法
console.log("Server starting...")// 正确写法
console.error("Server starting...")// 或者用专门的日志库，确保输出到stderr

Python：

 复制代码import sys# 错误写法
print("Server starting...")# 正确写法
print("Server starting...", file=sys.stderr)

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

---

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

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

 复制代码claude mcp add db -- npx server --transport stdio

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

 复制代码claude mcp add db -- npx server

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

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

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

---

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

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

 复制代码Error: spawn xxx ENOENT

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

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

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

 复制代码# 找到命令的绝对路径
which node# 然后在配置里写绝对路径
claude mcp add db -- /usr/local/bin/node /path/to/server.js

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

 复制代码# 先全局安装
npm install -g @modelcontextprotocol/server-filesystem# 然后配置里直接写包名，不用npx
{
  "command": "server-filesystem",
  "args": ["/path/to/dir"]
}

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

---

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

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

 复制代码// 错误写法（Windows不认）
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem"]
}// 正确写法
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem"]
}

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

 复制代码// 反斜杠要写成双反斜杠
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:Usersxxxproject"]
}

---

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

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

 复制代码authentication_error: Invalid API key

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

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

用命令行的话：

 复制代码claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=xxx -- npx -y @modelcontextprotocol/server-github

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

---

总结

配MCP的坑大致分这几类：

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

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

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