官方 FAQ｜MCP 工具

帮助与支持
1

什么是 MCP

Model Context Protocol (MCP) 是一种协议，它允许大型语言模型（LLMs）访问自定义的工具和服务。TRAE 中的智能体作为 MCP 客户端可以选择向 MCP Server 发起请求，以使用它们提供的工具。你可以自行添加 MCP Server，并添加到自定义的智能体中来使用。更多信息参阅 MCP 官方文档。

在 TRAE 中，MCP Server 支持三种传输类型：stdio 传输、SSE 传输、Streamable HTTP 传输。

免责声明

MCP Server 由第三方构建和维护。TRAE 不审查或认可这些服务器，并且不对其行为、任何 MCP Server 调用失败或它们返回的数据承担任何责任。部分 MCP Server 也可能因相关法律法规、网络限制、或服务器自身的访问策略，在你所在的国家或地区无法访问或使用。TRAE 无法控制这些因素，亦无法保证你所在国家或地区对这些服务器的可用性或功能性。你在尝试使用这些服务器时，应自行确保遵守当地法律法规。

配置系统环境

为确保正常启动 MCP Server，你可能需要安装：

  • npx：依赖于 Node.js，版本需大于等于 18。

  • uvx：基于 Python 的快速执行工具，需手动安装。

  • (可选) Docker：容器化平台，用于隔离和运行应用程序，需根据系统版本安装对应版本。若使用 GitHub MCP Server，则需要使用 Docker。

安装 Node.js

  1. 请前往 Node.js 官网，下载并安装 Node.js 18 或更高版本。

  2. 安装完成后，在终端中运行以下命令确认是否安装成功。

node -v npx -v

若安装成功，终端中会输出已安装的 Node.js 的版本号，例如：

v18.19.0
10.2.0

  1. 重启 TRAE，使 Node.js 生效。

安装 uvx（Python 工具）

uvx 是 uv 提供的命令行工具，用于快速运行 Python 脚本。

  1. 前往 Python 官网，下载并安装 Python 3.8 或更高版本。

  2. 安装完成后，在终端中执行以下命令确认是否安装成功。

python --version

若安装成功，终端中会输出已安装的 Python 的版本号。

  1. 执行以下命令，安装 uv（包含 uvx）。安装脚本会自动下载 uv 并放置到系统默认路径中。
  • macOS / Linux 安装命令：
curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows 安装命令（PowerShell）：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. 执行以下命令，验证是否安装成功。
uvx --version

若安装成功，终端中会输出已安装的 uvx 的版本号。

(可选) 安装 Docker

若使用 GitHub MCP Server，则需要使用 Docker。使用以下步骤安装 Docker Desktop。
操作系统
macOS
Windows

使用以下操作验证是否安装成功：

  • 打开终端，输入 docker --version 命令。如果安装成功，会显示 Docker 的版本信息。

  • 输入 docker info 命令，可以查看 Docker 的详细信息。如果能正确显示信息，代表 Docker 已安装并启动成功。

配置 MCP Server

你可以直接从市场中添加合适的 MCP Server，或手动添加。

方式一：从市场添加

MCP 市场中提供了社区中热门的 MCP Server，你可以选择需要的 MCP Server 进行添加。

  1. 在 AI 侧边对话框的右上角，点击 设置 图标。

  2. 选择 MCP 页签。

  3. 点击 + 添加 MCP Servers 按钮；或点击右上角的 + 添加 按钮，然后在菜单中选择 从市场添加。

    1. 你将进入 MCP 市场。

image
image972×878 84.8 KB

  1. 在 MCP 市场中找到所需的 MCP Server。

  2. 点击右侧的 + 按钮。

  3. 在弹窗中填入 MCP Server 的配置信息。

:balloon:对于标记为 “Local” 的 MCP Server，需要在本地安装 NPX 或 UVX 后才能使用。

配置内容中的 env 信息（例如 API Key、Token、Access Key 等字段）须替换为真实信息。

  1. 点击 确认 按钮。

方式二：手动添加

如果在市场中无法找到想要的 MCP Server，或者想使用自己开发的 MCP Server，则需要手动添加。

  1. 在 AI 侧边对话框的右上角，点击 设置 图标，然后在菜单中选择 MCP。

    1. 界面上显示 MCP 页签。

  2. 点击右上角的 + 添加 按钮，然后在菜单中选择 手动添加。

    1. 界面上显示 手动配置 窗口。

image
image974×1096 75.3 KB

  1. 填入 MCP Server 的配置内容。

:balloon: 优先使用 NPX 或 UVX 配置。

  • 若你希望添加一个全新的 MCP Server，将 JSON 配置内容填入输入框中，然后点击 确认 按钮。该 MCP Server 将被添加至 MCP 列表中。

  • 若你已在其他 IDE 中配置了 MCP Server，并希望在 TRAE 中复用。你可以点击 原始配置（JSON） 按钮，然后将 MCP Server 的 JSON 配置内容粘贴至 TRAE 的 mcp.json 文件中。粘贴完成后，MCP 列表中将自动添加相应的 MCP Server。

在智能体中使用 MCP Server

将 MCP Server 添加至智能体，让其调用 MCP Server 中的工具来更好地处理你的需求。

内置智能体：Builder with MCP

Builder with MCP 是 TRAE 的内置智能体，所有已配置的 MCP Server 都将被自动添加至该智能体，且不可编辑。

自定义智能体

你可以将 MCP Server 添加到自定义智能体中，然后由智能体自动调用 MCP Server 中的工具来完成任务。

  • 直接在 MCP Server 列表中将 MCP Server 添加至智能体，步骤如下：

    • 前往 MCP Server 列表。

    • 点击目标 MCP Sever 右侧的 + 按钮。

    • 在列表中勾选需要添加该 MCP Server 的智能体。

    • 点击 确认 按钮。

image
image1098×694 49.9 KB

  • 若你未创建自定义智能体，则可以在创建时为其添加所需的 MCP Server。详情参考《智能体》。

管理 MCP Server

你可以编辑或删除 MCP Server。

使用火山引擎的 MCP Server

火山引擎 MCP Server 市场提供了涵盖计算、存储、数据库等云服务的 MCP Server，你可以在 TRAE 中使用它们。使用说明参考火山引擎官网对每个 MCP Server 的介绍。

教程

在众多场景中，MCP Server 都能够发挥作用，提高你的工作效率，你可以参考以下教程来了解更多 MCP Server 的使用方法。

============= :alien_monster: 以下为常见问题 :alien_monster: ==============

报错：You must supply a command / 您必须提供一个命令

node 版本太老了，需要升级一下系统的 node。如果使用的是 nvm 的话，使用 nvm alias default 21。修改完之后记得重启 IDE。

image
image1258×866 92.3 KB

image
image1218×480 61.6 KB

NPM Error

如果报错信息中出现

  • cannot find module 'xxx'

  • Error: EACCES: permission denied, mkdir 'xxx'

  • /Users/xxx/.npm/_npx/__cache/...

  • Users/xxx/.npm/_npx/<一串 16 进制数字>/node_modules/...

image
image704×630 91.9 KB

这种情况往往是 npm 缓存坏掉了，请依次尝试下面的命令：

npm cache clean --force
sudo npm cache clean --force
rm -rf ~/.npm/_npx
sudo rm -rf ~/.npm/_npx

超时时间问题

TRAE 的默认启动和调用的超时时间都是 10 分钟（包括 Stdio / HTTP）

你可以自定义超时时间。

// http { "headers": { "RUN_MCP_TIMEOUT_MS": "60000" } } // stdio { "env": { "RUN_MCP_TIMEOUT_MS": "60000" } }

WSL 默认 Node 环境问题

如果 WSL 里只有 node，没有 npm，是因为：

wsl 系统里有一个默认的 node，在 /usr/bin/node，但是这个 Node SDK 是残缺的，缺失了 npm 工具，所以 npx 是运行不了的（npx 是 npm 里的命令）

需要使用 sudo apt install npm 命令安装缺失的 npm 工具。

Elasticsearch MCP，启动多个窗口会对应启动多个Docker容器是正常现象吗

正常，需确保每个窗口实例运行于独立容器中，以保证环境隔离和资源独占。

http 类型的 mcp server，如何配置 header

可以参考如下方式：

{
"mcpServers": {
"mcp_name": {
"url": "https://example.com/mcp",
"headers": {
"key": "value"
}
}
}
}

创建 Figma AI Bridge 时启动失败，提示如下问题该如何处理：Error: Could not load the “sharp” module using the darwin-arm64 runtime

错误：无法使用 darwin-arm64 运行时加载 “sharp” 模块

可能的解决办法：

  1. 删除 npx 缓存（核心）

rm -rf ~/.npm/_npx

  1. 清理项目 node_modules 和锁文件（避免残留依赖干扰）

rm -rf node_modules package-lock.json yarn.lock

  1. 重新安装依赖（确保完整、适配当前环境）

npm install

  1. 单独重装 sharp（重点修复目标）

npm install --arch=arm64 --platform=darwin sharp

  1. 重启 Trae，避免老进程干扰

模型效果相关

:light_bulb:模型的上下文窗口是固定的，也是稀缺资源，所以我们对什么东西能给到模型是有取舍的，MCP 目前限制比较多。后续的发展方向是一方面把上下文窗口开的更大一点，另一方面是放松 MCP 的限制。

Trae 似乎没读到 MCP 的工具，为什么？

  • 现象：使用 Builder with MCP 或者自定义 Agent 时，注册了 MCP Server，但在问答的时候，即使我指定模型调用某个工具，它依然无法做到。

  • 解释：因模型上下文窗口的限制，Trae 只预留了一部分固定的空间用于向模型描述 MCP 信息，限制如下:

    • 所有 MCP Server 描述信息的字符数上限：8000

    • 所有 MCP Server 工具的数量上限：40

    • 在触达任一上限的时候，会按工具的粒度丢弃装不下的工具信息

模型似乎没有完整地读到 MCP 的响应内容，为什么？

  • 现象：MCP 工具执行成功，但是在下一次模型问答时，模型要么不知道响应内容，要么是只知道部分内容。

  • 解释：因模型上下文窗口的限制，Trae 限制了 MCP 工具响应内容的大小，这是一个动态的裁剪过程:

    • 每个模型它的上下文窗口是不一样的，目前普遍在 45K 左右，但 MCP 的响应内容不可能全部占用这 45K 的空间

    • 这个上限是动态的，取决于模型和你当前对话的上下文内容（比如你用了多少 #File, #Doc, #Folder 之类的上下文）

    • 也取决于你的工具调用次数，工具调用多了，历史记录里的工具响应内容也多了，然后如果空间不够了，会优先裁掉历史的工具调用记录

使用MCP tools返回的文字过长，出现【输出过长，请输入“继续”后获得更多结果。】提示，有什么办法解决这个问题吗

选择模型时开启 max 模式。

3 个赞