Mastra Agent 的 MCP 配置入门：在 agents/index.ts 中搭建 MCPClient 服务器注册表

Mastra Agent 的 MCP 配置入门在 agents/index.ts 中搭建 MCPClient 服务器注册表【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本课是 Mastra 官方教程「Agent Tools MCP」系列的第三节承接 安装 mastra/mcp 之后讲解如何在 agent 文件中创建 MCPClient 配置对象把 MCPModel Context Protocol服务器注册表接入你的 Mastra Agent。学完本节你将掌握new MCPClient({ servers })的完整写法、servers配置对象的结构语义以及后续为 Agent 接入 Zapier、GitHub、Hacker News、Filesystem 等外部工具服务的配置基础。为什么需要一份 MCP 配置对象MCPModel Context Protocol为 AI 模型提供了一套统一接口来访问外部工具与服务。在 Mastra 中mastra/mcp包负责承载 Agent 与 MCP 服务器之间的通信——安装它只是第一步真正让 Agent 具备外部能力的关键是在 agent 文件中创建一份 MCP 配置对象声明「你的 Agent 要连接哪些 MCP 服务器」。这份配置对象就是整个 MCP 集成流程的枢纽后续教程中初始化工具listTools()、把工具挂到 Agent 上updating your agent、接入具体服务器Zapier、GitHub、Hacker News、Filesystem全部围绕这份配置展开。在 agent 文件中创建基础 MCP 配置打开你的src/mastra/agents/index.ts文件先添加MCPClient的导入import { MCPClient } from mastra/mcp随后创建基础 MCP 配置对象const mcp new MCPClient({ servers: { // Well add servers in the next steps }, })这个配置对象用于指定你的 Agent 应该连接到哪些 MCP 服务器。servers属性是一个对象其中每个 key 是某台服务器的唯一标识符value 则包含该服务器的连接配置。在接下来的步骤中我们会向这份配置中逐个添加各类 MCP 服务器让 Agent 获得访问广泛工具与服务的能力——这也是本节被称为「注册表」的原因servers就是一份待扩展的服务器清单。理解 servers 配置对象的结构语义从源码层面看MCPClientOptions的类型定义位于 packages/mcp/src/client/configuration.tsexport interface MCPClientOptions { /** Optional unique identifier to prevent memory leaks when creating multiple instances with identical configurations */ id?: string; /** Map of server names to their connection configurations (stdio or HTTP-based) */ servers: Recordstring, MastraMCPServerDefinition; /** Optional global timeout in milliseconds for all servers (default: 60000ms) */ timeout?: number; }其中servers被定义为Recordstring, MastraMCPServerDefinition即「服务器名称 → 服务器连接定义」的映射表字段类型含义idstring可选实例唯一标识防止相同配置的实例被重复创建导致内存泄漏serversRecordstring, MastraMCPServerDefinition服务器注册表每个 key 是该服务器的唯一标识符如zapier、githubvalue 是它的连接配置timeoutnumber可选全局请求超时毫秒默认60000msservers的 key 就是你为服务器起的唯一标识符后续listTools()返回的工具名会以「服务器名_工具名」的形式命名空间化。从 listTools() 的源码注释 可以看到实际效果const tools await mcp.listTools(); // 返回形如 weather_getWeather、stockPrice_getPrice 的命名空间工具也就是说servers里每个 key 的选择会直接反映到最终工具名上建议使用清晰、有业务含义的标识符。服务器定义的两种形态远程 URL 与本地命令MastraMCPServerDefinition支持两类连接方式这一点在后续教程各章节会反复用到1. 远程 HTTP 服务器Streamable HTTP 传输——通过url指定服务器端点配合requestInit定制请求头。例如 接入 Zapier 的写法const mcp new MCPClient({ servers: { zapier: { url: new URL(process.env.ZAPIER_MCP_URL || ), requestInit: { headers: { Authorization: Bearer ${process.env.ZAPIER_MCP_API_KEY}, }, }, }, }, })new URL()将环境变量中的字符串构造成 URL 对象|| 在环境变量缺失时提供空字符串兜底避免应用因变量未设置而崩溃requestInit.headers指定随每个请求发送的 HTTP 请求头Zapier 要求以Bearer {apiKey}格式在Authorization头中携带 API Key 完成身份校验。2. 本地 stdio 服务器——通过commandargs在本地拉起进程。例如 接入 Hacker News 的写法const mcp new MCPClient({ servers: { hackernews: { command: npx, args: [-y, devabdultech/hn-mcp-server], }, }, })command指定运行服务器的可执行文件如npx、pnpxargs提供传给它的参数-y标志自动确认所有提示使执行过程无缝化。这种形态无需任何认证或外部服务搭建接入 Filesystem 时还可用path.join(process.cwd(), ...)动态构造目录参数保证无论从何处运行应用路径都正确解析。在 InternalMastraMCPClient 的构造器 中可以看到服务器定义还支持更多可选能力例如roots文件系统根声明、protocolVersion协议版本协商、enableServerLogs、enableProgressTracking、requireToolApproval、onToolError、jsonSchemaValidator等从源码结构看这些属于进阶配置项基础使用阶段先掌握url/command两形态即可。配置完成后的验证路径配置对象建好后下一步就是用listTools()初始化工具详见 初始化 MCP 工具const mcpTools await mcp.listTools()这个异步调用会连接到servers中配置的每台服务器、拉取全部可用工具并以 Mastra Agent 可用的格式返回。当服务器较多或个别服务器连接失败时可使用 listToolsWithErrors() 拿到按服务器拆分的tools、errors、errorDetails与durations便于逐个定位故障原因。需要留意的实例缓存行为从 MCPClient 构造函数 的实现看MCPClient 会对相同配置的实例做缓存复用以阻止内存泄漏。这意味着若用相同配置重复new MCPClient(...)且未指定id会抛出明确提示的错误建议改为为实例设置唯一id、用完后await client.disconnect()再重建、或把实例创建收敛到高层作用域只创建一次若指定了id且配置发生变化旧实例会被自动disconnect()并替换。因此在实际项目中MCPClient 实例通常作为模块级单例创建一次而不是放在循环或热路径里反复实例化。小结本节完成了 MCP 集成的最关键一步在src/mastra/agents/index.ts中创建MCPClient配置对象理解servers注册表「标识符 → 连接定义」的结构并认识了远程 URLurlrequestInit与本地命令commandargs两种服务器形态。接下来的课程将逐一演示把 Zapier、GitHub、Hacker News、Filesystem 等真实服务器填入这份配置并结合listTools()与 Agent 更新步骤让你的 Agent 真正获得外部工具能力。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考