> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trae.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文档记录在 TRAE CN 中使用 MCP Server 时可能遇到的问题并提供解决方法。
## TRAE 未读取到 MCP Server 中的工具 {#36958122}
使用添加了 MCP Server 的内置 “Agent” 智能体或者自定义智能体时，即使在对话中明确要求模型调用某个 MCP Server 中的工具，模型依然无法调用或识别该工具。
**原因：**
受模型上下文窗口大小的限制，TRAE 仅会预留一部分固定的上下文空间，用于向模型传递 MCP Server 及其工具的描述信息。目前存在以下限制：

*  所有 MCP Server 描述信息的字符数上限：8,000
*  所有 MCP Server 工具的数量上限：40

当 MCP Server 的配置达到任一上限时，TRAE 会按工具维度丢弃无法容纳的工具描述信息。
**解法**：

* 在智能体配置面板中，取消勾选当前任务不需要的 MCP Server 和工具。这将释放部分上下文窗口，确保核心 MCP Server 的工具能被完整读取。
* 修改 MCP Server 和工具的 `description` 字段，使用更简练的描述，避免冗长。
* 仅使用当前场景必需的工具。如果一个 MCP Server 包含大量工具（接近或超过 40 个），建议将其拆分为多个功能更专注的小型 MCP Server，并按需启用。

## 模型无法完整读取 MCP Server 的响应内容 {#faf1fa7a}
MCP Server 执行成功，但在下一轮对话中，模型要么无法读取 MCP Server 的任何响应内容，要么只能读取部分内容。
**原因**：
受模型上下文窗口大小的限制，TRAE 会对 MCP Server 的响应内容进行动态裁剪，以确保整体上下文能够被模型正常处理。该裁剪机制受以下因素影响：

* **模型上下文窗口大小的不同**
   不同模型支持的上下文窗口存在差异，目前主流模型的上下文窗口通常在 45K 左右。但 MCP Server 的响应内容无法独占全部上下文空间。
* **当前对话的上下文占用情况**
   MCP Server 响应内容可用的上下文受当前对话中已引入上下文内容的影响，例如 `#File`、`#Doc`、`#Folder` 等引用内容。
* **工具调用历史的累积影响**
   随着 MCP Server 工具调用次数增加，历史工具响应会持续占用上下文空间。当可用空间不足时，TRAE 会优先裁剪较早的工具调用响应内容。

**解法**：

* 新建对话，这是最直接且有效的释放上下文窗口的方法。
* 减少非必要的上下文引用，仅引用当前任务绝对必需的代码片段、文件、文件夹等。
* 如果你是该 MCP Server 的开发者，可以尝试优化工具的返回数据结构，例如精简输出和结构化摘要。

## 错误：您必须提供一个命令 {#cdf64a98}
![Image=500x197](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/55746594358d4db5b7b249388b59c3d8~tplv-goo7wpa0wc-image.image)
当 MCP Server 通过 `npx` 启动时，系统的 Node.js 版本需为 20 及以上。升级 Node.js 后重启 TRAE，即可解决相关问题。
## npm 相关报错 {#da6edfc6}
如果报错信息中出现以下内容，通常与 npm 的本地缓存异常有关。

* `cannot find module 'xxx' `
* `Error: EACCES: permission denied, mkdir 'xxx'`
* `/Users/xxx/.npm/_npx/__cache/...`
* `/Users/xxx/.npm/_npx/<一串 16 进制数字>/node_modules/...`

按顺序尝试以下命令，每执行一条命令后，重启一次 TRAE，并检查问题是否已解决。
```Bash
npm cache clean --force

sudo npm cache clean --force

rm -rf ~/.npm/_npx

sudo rm -rf ~/.npm/_npx
```

如果该错误依然存在，则需进一步检查 npm 版本：

1. 在错误日志中查找类似下图所示的信息。
   ![Image=600x50](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/472c858e0bd6459f80968eb979e7f3fb~tplv-goo7wpa0wc-image.image)
2. 确认当前 npm 版本是否过旧。
3. 若 npm 的版本为 6.x 或更低，升级 npm。
4. 升级完成后，重新启动 TRAE 并再次尝试。

## WSL 环境下无法使用 npx 命令 {#c35ffa3f}
在 WSL 环境中，`node` 命令可以正常执行，但 `npm` 或 `npx` 命令无法使用。
**原因**：
WSL 默认预装的 Node.js 往往是精简版本（通常位于 /usr/bin/node ），不包含 `npm` 包管理工具。由于 `npx` 是 `npm` 的一部分，因此也无法运行。
**解法**：
在终端执行以下命令，安装缺失的 `npm` 工具：
```Bash
sudo apt install npm
```