1. 引言

随着大模型应用走向工程化，智能体（Agent）不再只是单次问答，而是需要调用外部工具、访问实时数据、操作业务系统。MCP（Model Context Protocol）正是为了解决「模型与工具、数据源之间的标准化连接」而诞生的开放协议。TRAE 作为一款面向 AI 编程与智能体开发的平台，原生支持通过 MCP Server 扩展智能体的能力边界。本文将从 MCP 的基本概念出发，结合 TRAE 的实际配置与代码示例，带你一步步在智能体中接入并使用 MCP Server。

2. MCP 协议基础

MCP 由 Anthropic 提出并开源，旨在为 LLM 应用提供一套统一的工具调用与上下文获取标准。它采用客户端-服务器架构，核心角色包括：

• MCP Host：运行智能体的宿主程序，例如 TRAE、Claude Desktop 等。
• MCP Client：内嵌于 Host 中，负责与 Server 建立连接、协商能力、收发请求。
• MCP Server：暴露工具、资源和提示词的服务端，可以是本地进程，也可以是远程 HTTP 服务。

一次典型的 MCP 调用流程如下：

sequenceDiagram
    participant Agent as TRAE 智能体
    participant Client as MCP Client
    participant Server as MCP Server
    Agent->>Client: 请求调用工具 get_weather
    Client->>Server: 发送 JSON-RPC 请求
    Server->>Server: 执行工具逻辑
    Server-->>Client: 返回工具结果
    Client-->>Agent: 返回结构化结果
    Agent->>Agent: 结合结果生成最终回复

MCP 的传输层支持两种主流方式：stdio（本地子进程，通过标准输入输出通信）和 Streamable HTTP（远程服务，通过 HTTP 通信）。TRAE 对两者均提供支持。

3. TRAE 中配置 MCP Server

在 TRAE 中接入 MCP Server 通常有两种方式：通过图形界面添加，或通过配置文件声明。下面分别说明。

3.1 通过界面添加

打开 TRAE 的设置面板，找到「MCP 服务器」入口，点击「添加服务器」，填写服务器名称、传输类型（stdio 或 HTTP）以及启动命令或 URL 即可。TRAE 会自动完成握手并列出该服务器暴露的工具。

3.2 通过配置文件声明

TRAE 支持在项目根目录或用户目录下维护 MCP 配置文件，格式为 JSON。下面是一个典型的配置示例：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["mcp_weather_server.py"],
      "env": {
        "API_KEY": "your-api-key"
      }
    },
    "github": {
      "url": "https://mcp.example.com/github",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

其中 weather 使用 stdio 方式启动本地 Python 脚本，github 则通过 HTTP 连接远程服务。配置完成后，重启 TRAE 或刷新 MCP 连接，即可在智能体中看到新增的工具。

4. 编写第一个 MCP Server

为了让智能体真正「用起来」，我们需要自己实现一个 MCP Server。这里以 Python 官方 SDK 为例，实现一个支持查询天气和计算器功能的服务器。

4.1 环境准备

pip install mcp

4.2 实现服务器

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo-server")


@mcp.tool()
def get_weather(city: str) -> str:
    """查询指定城市的天气情况"""
    # 这里替换为真实天气 API 调用
    return f"{city} 今天晴，气温 22°C，适合出行。"


@mcp.tool()
def add(a: float, b: float) -> float:
    """计算两个数字之和"""
    return a + b


if __name__ == "__main__":
    mcp.run(transport="stdio")

这段代码通过 FastMCP 快速声明了两个工具：get_weather 和 add。函数签名中的类型注解和文档字符串会被自动转换为 MCP 的工具描述，供智能体理解何时调用。

4.3 在 TRAE 中连接

将上面的脚本保存为 demo_server.py，然后在 TRAE 的 MCP 配置中添加：

{
  "mcpServers": {
    "demo": {
      "command": "python",
      "args": ["demo_server.py"]
    }
  }
}

连接成功后，在智能体对话中输入「北京天气怎么样」，TRAE 会自动识别意图并调用 get_weather 工具，返回结果后组织成自然语言回复。

5. 在智能体中调用 MCP 工具

配置好 MCP Server 后，智能体如何感知并调用这些工具？这取决于 TRAE 的 Agent 运行时如何把 MCP 工具注入到模型上下文中。下面通过一个更完整的示例，演示如何让智能体完成「查询天气并计算温差」的复合任务。

5.1 扩展服务器能力

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")


@mcp.tool()
def get_temperature(city: str) -> float:
    """获取指定城市的当前温度（摄氏度）"""
    # 模拟数据，实际可对接天气 API
    data = {"北京": 22.0, "上海": 26.5, "广州": 30.0}
    return data.get(city, 20.0)


@mcp.tool()
def get_weather(city: str) -> str:
    """获取指定城市的天气描述"""
    temp = get_temperature(city)
    if temp > 28:
        desc = "炎热"
    elif temp > 20:
        desc = "舒适"
    else:
        desc = "偏凉"
    return f"{city} 当前 {temp}°C，天气{desc}。"


if __name__ == "__main__":
    mcp.run(transport="stdio")

5.2 智能体多步调用

当用户在 TRAE 中提问「北京和上海温差多少」时，智能体会自动规划以下步骤：

1. 调用 get_temperature("北京")，得到 22.0。
2. 调用 get_temperature("上海")，得到 26.5。
3. 计算差值 4.5，并组织回答。

整个过程对用户透明，TRAE 会在对话流中展示每一步的工具调用记录，方便调试和追溯。

6. 使用 TypeScript 实现 MCP Server

除了 Python，TRAE 生态同样支持 TypeScript/Node.js 编写的 MCP Server。下面给出一个等价实现。

6.1 初始化项目

npm init -y
npm install @modelcontextprotocol/sdk

6.2 编写服务器

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "demo-server",
  version: "1.0.0"
});

server.tool(
  "get_weather",
  { city: z.string().describe("城市名称") },
  async ({ city }) => ({
    content: [{ type: "text", text: `${city} 今天晴，气温 22°C。` }]
  })
);

server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

在 TRAE 中配置时，将启动命令改为：

{
  "mcpServers": {
    "demo-ts": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

7. 远程 MCP Server 接入

当工具逻辑部署在远端服务时，可以通过 Streamable HTTP 方式接入。TRAE 支持在配置中直接声明远程地址。下面是一个基于 FastAPI 的远程 MCP 服务示例。

7.1 服务端实现

from mcp.server.fastmcp import FastMCP
from mcp.server.sse import SseTransport
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import uvicorn

mcp = FastMCP("remote-server")


@mcp.tool()
def get_stock_price(symbol: str) -> str:
    """查询股票实时价格"""
    # 对接真实行情接口
    return f"{symbol} 当前价格 128.50 元"


app = FastAPI()


@app.post("/mcp")
async def mcp_endpoint(request: Request):
    transport = SseTransport(endpoint="/mcp")
    return await transport.handle_request(request)


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

7.2 TRAE 配置远程连接

{
  "mcpServers": {
    "stock": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

远程接入时需要注意鉴权与网络安全，建议在生产环境使用 HTTPS 并配置访问令牌。

8. 调试与常见问题

在 TRAE 中使用 MCP Server 时，可能会遇到以下几类问题：

• 工具未出现：检查服务器是否成功启动，TRAE 的 MCP 面板中是否显示「已连接」；确认工具函数是否有类型注解和文档字符串。
• 调用超时：本地 stdio 服务若启动缓慢，可适当调大 TRAE 的超时时间；远程服务需检查网络连通性。
• 参数校验失败：MCP 会按 JSON Schema 校验参数，确保函数签名类型与调用参数一致。
• 日志查看：在 TRAE 的 MCP 面板中可查看服务器输出日志，定位启动报错。

此外，建议在本地先独立运行服务器脚本，确认工具可正常调用后再接入 TRAE，能显著减少排查成本。

9. 总结

MCP 为智能体提供了一套标准化的工具接入方式，而 TRAE 让这一过程变得简单直观。通过本文的示例，你已经掌握了在 TRAE 中配置本地与远程 MCP Server、使用 Python 与 TypeScript 实现工具、以及让智能体自动完成多步调用的完整链路。下一步，可以尝试把真实业务 API 封装为 MCP 工具，让智能体真正融入你的工作流。