---
title: MCP server 用 stdio 装进 agent 后没有工具出现
summary: stdio MCP 最常见的三个原因：往 stdout 打了日志、命令用了相对路径、Windows 下要 shell 包装。用 npx 或绝对路径 + 日志全走 stderr。
tags:
  - agent
  - claude-desktop
  - mcp
date: 2026-11-22T17:01:41.978Z
---
## 现象

配置文件里加好了 mcpServers，重启 agent 后工具列表里没有，或者直接连不上。

## 原因

stdio 传输把 **stdout 当成 JSON-RPC 通道**。只要有一行 `console.log`，协议就解析失败，握手断掉。
另外，GUI 启动的进程不继承你的 shell PATH，`command: "node"` 常常找不到。

## 解决

1. 所有日志改到 stderr：

```js
console.error('[aha] listening')   // 不要 console.log
```

2. 用绝对路径：

```json
{ "mcpServers": { "aha": {
  "command": "node",
  "args": ["C:/Users/weidows/source/repos/Weidows/web/aha/packages/mcp/dist/index.js"],
  "env": { "AHA_BASE_URL": "http://localhost:2420", "AHA_API_KEY": "aha_..." }
} } }
```

3. 手工验证协议能不能跑起来：

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | node packages/mcp/dist/index.js
```

能打回 `{"result":{"serverInfo":...}}` 就说明 server 没问题，问题在客户端的配置路径。

## 注意

- Windows 上有些客户端需要 `"command": "cmd", "args": ["/c", "node", "..."]`。
- 改完配置必须**完全退出**客户端再启动，只关窗口不一定重启 MCP 子进程。