Mastra Agent 接入 MCP 实战回顾：用四个 MCP 服务器与增强记忆构建全能个人助理

Mastra Agent 接入 MCP 实战回顾用四个 MCP 服务器与增强记忆构建全能个人助理【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇文章是对 Mastra 官方教程「Agent Tools MCP」课程模块docs/src/course/02-agent-tools-mcp的完整总结与深度复盘。它回顾了从零开始为 Mastra Agent 接入 Model Context ProtocolMCP服务器的全过程安装mastra/mcp、建立MCPClient配置、通过listTools()注入工具并依次接入 Zapier、GitHub、Hacker News、Filesystem 四个 MCP 服务器最后为 Agent 配置会话记忆、语义召回与工作记忆。读完本文你将掌握 MCP 在 Mastra 中的完整接入链路、两种服务器连接方式远程 HTTP 与本地 stdio、认证与权限配置、Agent 指令instructions的迭代技巧以及对应的验证与排障方法。一、课程目标回顾MCP 让 Agent 摆脱手写工具的束缚MCPModel Context Protocol模型上下文协议是一种让 AI 模型通过统一接口访问外部工具与服务的开放标准。在接入 MCP 之前Agent 每获得一项能力读邮件、查仓库、看新闻通常都要为其编写自定义工具函数而通过 MCP一个标准化的客户端即可同时连接大量现成的服务器每个服务器对外暴露一组工具Agent 无需关心它们的内部实现。在本课程结束时你构建的personalAssistantAgent已经具备五类核心能力通过 Zapier MCP 服务器获得邮件与社交媒体集成Gmail、Twitter/X、LinkedIn 等通过官方 GitHub MCP 服务器获得仓库监控能力PR、Issue、提交历史通过 Hacker News MCP 服务器获得科技资讯与讨论检索能力通过 Filesystem MCP 服务器获得本地文件读写能力笔记、待办清单通过增强记忆配置获得个性化交互能力会话历史、语义召回、工作记忆。MCP 的价值在于模块化扩展新能力以服务器为单位即插即用而不是以一行行手写工具函数为代价这让 Agent 的能力边界可以随着 MCP 生态的成长而持续扩张。二、MCP 基础设施搭建安装、配置、初始化与挂载1. 安装mastra/mcpMCP 客户端能力由独立包提供首先安装npm install mastra/mcplatestmastra/mcp包封装了 Mastra 与各类 MCP 服务器之间的通信基础设施连接管理、工具发现、认证流等安装它是整个接入流程的第一步。2. 创建 MCP 配置打开你的 Agent 定义文件src/mastra/agents/index.ts导入并实例化MCPClientimport { MCPClient } from mastra/mcp const mcp new MCPClient({ servers: { // 后续逐步添加服务器 }, })servers属性是一个对象每个 key 是服务器的唯一标识符value 是该服务器的连接配置。从源码看MCPClientOptions还支持可选的id用于避免相同配置重复创建实例导致内存泄漏与timeout全局请求超时默认 60000ms而每个服务器配置的类型是MastraMCPServerDefinition即stdio 子进程与HTTP 远程服务器两种形态的联合类型由是否提供command或url自动判别见 types.ts。这正好对应了后面两种接入方式。3. 初始化 MCP 工具配置就绪后异步拉取所有已配置服务器的工具清单const mcpTools await mcp.listTools()listTools()会连接配置中的每个服务器、检索其可用工具并返回可以直接交给 Mastra Agent 使用的工具对象。需要留意的是返回的工具名会以服务器名_工具名的形式做命名空间隔离防止多服务器之间的同名工具冲突源码见 configuration.ts单服务器连接失败只会被记录而不会让整个调用抛错因此后续在 Playground 中通过 Tools 面板核对工具是否加载成功非常关键。源码还提供了listToolsets()按服务器分组、不做命名空间前缀适合generate()/stream()动态注入与listToolDefinitions()返回可 JSON 序列化的工具定义便于缓存复用等进阶 API。4. 将工具挂载到 Agent修改 Agent 定义把 MCP 工具展开进tools属性export const personalAssistantAgent new Agent({ name: Personal Assistant, instructions: You are a helpful personal assistant that can help with various tasks. Keep your responses concise and friendly. , model: openai/gpt-5.4, tools: { ...mcpTools }, // 将 MCP 工具注入 Agent })通过展开运算符配置过的所有 MCP 服务器的工具都会对 Agent 可见。后续每增加一个服务器mcpTools都会自动包含它的工具Agent 能力随之扩张。5. 基线验证此时尚未配置任何服务器但可以验证基础链路使用npm run dev启动开发服务器打开 Playgroundhttp://localhost:4111/在 Agent 列表中应能看到 Personal Assistant发送 Hello, what can you help me with? 之类的消息确认它能正常回复。这个阶段 Agent 还没有特殊能力但配置骨架已经就位——接下来就是逐个添加服务器。三、接入 Zapier MCP邮件与社交媒体集成1. 认识 Zapier MCPZapier MCP 服务器通过 Zapier 平台暴露数千个应用与服务覆盖 Gmail、Outlook 等邮件服务Twitter/X、LinkedIn 等社交平台以及 Trello、Asana 等项目工具。接入后Agent 无需为每个应用编写自定义工具即可完成读邮件、发邮件、排程社交内容等任务。Zapier MCP 需要认证你需要两样东西MCP Server URLAgent 连接的端点API Key随每次请求发送的密钥用于身份验证。2. 获取 URL 与 API Key在 zapier.com 注册账户如还没有进入 mcp.zapier.com选择 New MCP Server客户端类型选择OpenAI API——它提供 API Key 认证与 Mastra 这类自定义 MCP 客户端配合良好为服务器添加工具例如搜索 Gmail 并添加 Find Email 与 Send Email打开Connect标签页获取MCP Server URL与API Key如需可点击Rotate token重新生成。重要API Key 仅在生成时显示一次务必立即复制遗失后只能通过Rotate token重新生成。将两个值写入.env# 添加到 .env 文件 ZAPIER_MCP_URLhttps://mcp.zapier.com/api/v1/connect ZAPIER_MCP_API_KEYyour-api-key-here使用环境变量可以让凭证不进入源码请确保.env已列入.gitignore。3. 更新 MCP 配置在src/mastra/agents/index.ts中添加 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}, }, }, }, }, })逐项拆解zapier该服务器在配置中的唯一标识urlZapier MCP 端点从.env读取requestInit.headers随每个 HTTP 请求发送的请求头Authorization: Bearer ...以 Bearer Token 形式携带 API Key向 Zapier 证明身份。new URL(...)把环境变量字符串构造成 URL 对象|| 在环境变量缺失时提供空字符串默认值避免应用因缺少环境变量而崩溃。requestInit选项用于定制发往 MCP 服务器的 HTTP 请求——Zapier 要求每次请求都携带Authorization: Bearer {apiKey}头。4. 更新 Agent 指令指令instructions是帮助 Agent 判断何时用、怎么用工具的关键。为 Zapier 工具更新系统提示export const personalAssistantAgent new Agent({ name: Personal Assistant, instructions: You are a helpful personal assistant that can help with various tasks such as email and scheduling social media posts. You have access to the following tools: 1. Gmail: - Use these tools for reading and categorizing emails from Gmail - You can categorize emails by priority, identify action items, and summarize content - You can also use this tool to send emails Keep your responses concise and friendly. , model: openai/gpt-5.4, tools: { ...mcpTools }, memory, })5. 验证与排障在 Playground 中尝试以下提示词Get my last emailSend an email to youremailgmail.com with the subject Test and body Hello, this is a test email配置正确时Agent 会自动选择合适的 Zapier 工具完成任务。如果无法访问 Zapier 工具按序排查.env中ZAPIER_MCP_URL与ZAPIER_MCP_API_KEY是否都已设置MCP 配置是否包含requestInit.headers与Authorization: Bearer头是否在 mcp.zapier.com 的服务器上添加了动作如 Gmail在 Playground 的 Tools 标签页核对工具是否已加载。常见问题401 Missing OAuth authorization header配置缺少requestInit.headers块Zapier 每次请求都要求Authorization头401 Invalid OAuth tokenAPI Key 错误或已过期请从 Zapier MCP 控制台的Connect标签页重新复制或Rotate token重新生成除zapier_get_configuration_url外没有工具未在 Zapier 控制台添加动作如 Gmail或尚未连接应用账户环境变量不生效修改.env后需重启开发服务器环境变量在启动时读取。另外npm run dev的终端输出中MCPClient会记录带详细原因的连接错误是排查的重要线索。四、接入 GitHub MCP仓库监控1. 认识 GitHub MCP官方 GitHub MCP 服务器提供与 GitHub 仓库交互的工具包括监控仓库活动、查看 Pull Request 与 Issue、查看提交历史、总结开发模式。接入后Agent 可以帮你盯住仓库动态而无需频繁手动打开 GitHub。2. 获取 Personal Access Token连接使用 GitHub 托管的远程端点https://api.githubcopilot.com/mcp/并通过请求头中的 GitHub Personal Access TokenPAT完成认证。创建步骤进入 GitHub Settings Developer settings Personal access tokens新建Fine-grained tokens起一个描述性名称如 Mastra Agent选择 Agent 需要访问的仓库在Repository permissions中至少授予Issues: Read、Pull requests: Read、Contents: Read、Metadata: Read默认选中点击Generate token并复制。将 Token 写入.env# 添加到 .env 文件 GITHUB_PERSONAL_ACCESS_TOKENyour_github_token3. 更新 MCP 配置在配置中追加 GitHub 服务器const mcp new MCPClient({ servers: { zapier: { url: new URL(process.env.ZAPIER_MCP_URL || ), requestInit: { headers: { Authorization: Bearer ${process.env.ZAPIER_MCP_API_KEY}, }, }, }, github: { url: new URL(https://api.githubcopilot.com/mcp/), requestInit: { headers: { Authorization: Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}, }, }, }, }, })工作原理url指向 GitHub 托管的远程 MCP 服务器requestInit.headers传递 PAT 用于认证该服务器与 Zapier 一样使用 Streamable HTTP 传输协议。多个服务器并存意味着 Agent 能访问更广泛的工具集——每个服务器都为 Agent 增加一组能力。如果你希望本地运行 GitHub MCP 服务器而不是使用托管端点也可以用 stdio 传输github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PERSONAL_ACCESS_TOKEN }, }这种方式不依赖api.githubcopilot.com行为与托管选项一致。4. 更新 Agent 指令与验证在指令中加入 GitHub 工具说明总结提交、PR、Issue、开发模式然后在 Playground 测试Check the recent activity on my repositorySummarize the open pull requestsWhat are the latest commits on the main branch?Are there any issues that need my attention?排障要点确认GITHUB_PERSONAL_ACCESS_TOKEN已正确设置、Token 具备所需的仓库权限Issues、Pull requests、Contents、Metadata、Playground Tools 面板中工具已加载。常见问题包括 Token 缺失或过期、权限不足、网络无法连接api.githubcopilot.com可在控制台日志中查找与 GitHub MCP 服务器相关的错误信息。五、接入 Hacker News MCP科技资讯1. 认识 Hacker News MCPHacker News MCP 服务器提供对 Hacker News 内容的访问获取热门故事top stories、搜索特定故事、追踪技术趋势与讨论。对开发者、技术爱好者和创业者尤为实用。2. 本地 NPX 运行方式与前两个使用 URL 的服务器不同Hacker News MCP 服务器可以直接通过 NPX 运行无需任何外部服务或认证。在配置中加入const mcp new MCPClient({ servers: { zapier: { url: new URL(process.env.ZAPIER_MCP_URL || ), requestInit: { headers: { Authorization: Bearer ${process.env.ZAPIER_MCP_API_KEY}, }, }, }, github: { url: new URL(https://api.githubcopilot.com/mcp/), requestInit: { headers: { Authorization: Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}, }, }, }, hackernews: { command: npx, args: [-y, devabdultech/hn-mcp-server], }, }, })该配置指示 MCP 在需要时用 NPX 启动 Hacker News 服务器-y标志自动确认所有提示保证无中断运行。这就是源码中所说的 stdio 子进程形态通过commandargs定义相比 URL 远程服务器更简单无需认证或外部服务搭建。3. 更新 Agent 指令与验证在指令中加入 Hackernews 工具说明搜索故事、获取热门故事、检索评论然后在 Playground 测试What are the top stories on Hacker News today?Find Hacker News discussions about AI agentsSummarize the comments on the top storyWhats trending in tech on Hacker News?首次提问时可能稍有延迟——NPX 需要安装并启动服务器后续查询会明显加快。排障时检查NPX 是否正常安装、网络是否允许 NPX 下载运行包、防火墙/代理是否拦截了 Hacker News API也可以直接在终端手动运行npx -y devabdultech/hn-mcp-server以定位问题在 NPX 本身还是 Mastra 配置。六、接入 Filesystem MCP本地文件管理1. 认识 Filesystem MCPFilesystem MCP 服务器让 Agent 具备本地文件系统读写能力读文件、写文件、创建目录、列出目录、管理笔记与待办清单等持久化数据。接入后Agent 可以跨会话维护持久信息即使应用关闭数据依然保留。2. 创建 notes 目录与 Hacker News 类似Filesystem 服务器通过包管理器直接运行这里使用 PNPXpnpm 版的 NPX。首先创建存放文件的目录mkdir -p notes-p标志保证目录已存在时命令不会报错。为 Agent 的文件开辟专用目录是好习惯隔离 Agent 数据与应用代码、便于备份与版本控制、划清 Agent 可访问的边界以增强安全性。3. 更新 MCP 配置在配置中加入 Filesystem 服务器import path from path const mcp new MCPClient({ servers: { zapier: { url: new URL(process.env.ZAPIER_MCP_URL || ), requestInit: { headers: { Authorization: Bearer ${process.env.ZAPIER_MCP_API_KEY}, }, }, }, github: { url: new URL(https://api.githubcopilot.com/mcp/), requestInit: { headers: { Authorization: Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}, }, }, }, hackernews: { command: npx, args: [-y, devabdultech/hn-mcp-server], }, textEditor: { command: pnpx, args: [ modelcontextprotocol/server-filesystem, path.join(process.cwd(), .., .., notes), // 相对输出目录 ], }, }, })textEditor是该服务器在配置中的唯一标识command指定用 PNPX 运行服务器args提供传给 PNPX 的参数包括包名与 notes 目录路径。path.join(process.cwd(), ...)保证路径不依赖应用的具体运行位置而始终正确。4. 更新 Agent 指令与验证在指令中说明 Filesystem 工具读写 notes 目录、存储信息、维护待办清单并在 Playground 测试Create a to-do list for meAdd Buy groceries to my to-do listCreate a note about the meeting tomorrowWhats on my to-do list?Read my meeting notes首次使用时同样会有 PNPX 安装启动服务器的短暂延迟。排障要点PNPX 是否正常安装、notes 目录是否存在且权限正确、MCP 配置中的路径是否无误可手动运行pnpx modelcontextprotocol/server-filesystem ./notes验证。七、增强记忆配置让交互个性化最后一步是为 Agent 配置更精细的记忆能力使其在拥有强大工具的同时记住用户的偏好与历史。1. 配置存储、向量库与记忆选项import { LibSQLStore, LibSQLVector } from mastra/libsql const memory new Memory({ storage: new LibSQLStore({ id: learning-memory-storage, url: file:../../memory.db, }), vector: new LibSQLVector({ id: learning-memory-vector, url: file:../../memory.db, }), embedder: openai/text-embedding-3-small, options: { // 上下文保留最近 20 条消息 lastMessages: 20, // 语义搜索查找相关的历史对话 semanticRecall: { topK: 3, messageRange: { before: 2, after: 1, }, }, // 工作记忆记住用户信息 workingMemory: { enabled: true, template: user first_name/first_name username/username preferences/preferences interests/interests conversation_style/conversation_style /user, }, }, })这套配置对应三类记忆能力记忆选项的完整类型定义见 packages/core/src/memory/types.ts会话历史Conversation HistorylastMessages: 20让最近 20 条消息保持在上下文内Agent 可以引用近期对话。语义召回Semantic RecallsemanticRecall让 Agent 通过语义搜索找到相关的历史对话——即使发生在很久以前。topK: 3指定召回条数messageRange.before/after控制命中消息前后各携带多少条上下文。注意语义召回依赖向量存储与 embedder 的配置本例中由LibSQLVector与openai/text-embedding-3-small承担。工作记忆Working MemoryworkingMemory.enabled: true配合template定义的结构化模板姓名、用户名、偏好、兴趣、对话风格等让 Agent 记住关于用户的特定信息并据此提供个性化回复。2. 更新 Agent 指令与挂载记忆export const personalAssistantAgent new Agent({ name: Personal Assistant, instructions: // ... 既有指令 ... You have access to conversation memory and can remember details about users. When you learn something about a user, update their working memory using the appropriate tool. This includes: - Their interests - Their preferences - Their conversation style (formal, casual, etc.) - Any other relevant information that would help personalize the conversation Always maintain a helpful and professional tone. Use the stored information to provide more personalized responses. , model: openai/gpt-5.4, tools: { ...mcpTools }, memory, })在指令中显式告知 Agent 记忆能力的存在与用法何时更新工作记忆、记录哪些字段、如何使用存储信息是让记忆真正产生价值的关键一步——它让 Agent 在面对新用户信息时主动落盘并在后续对话中主动调用从而提供更连贯、更个性化的体验。八、完整配置终态与扩展建议经过本课程五个阶段src/mastra/agents/index.ts中的MCPClient配置已经同时管理四个服务器——两种形态兼备Zapier 与 GitHub 走远程 HTTPurlrequestInit认证头Hacker News 与 Filesystem 走本地 stdiocommandargs。这正是MastraMCPServerDefinition联合类型的实际应用Mastra 会根据是否提供command或url自动选择传输方式见 packages/mcp/src/client/types.ts。回顾整条链路每个环节都有对应的源码实现支撑实例化与防泄漏MCPClient会按配置的哈希缓存实例相同配置重复创建会抛出提示要求显式传入id或先disconnect()见 configuration.ts工具发现listTools()并发发现所有服务器单服务器失败不影响整体并自动为工具名添加serverName_前缀见 configuration.ts生命周期disconnect()优雅关闭所有连接并清理缓存可用于应用退出时的资源回收见 configuration.ts进阶能力MCPClient还提供resources资源、prompts提示词模板、elicitation交互式信息收集、progress长任务进度、authenticate()OAuth 授权码流程等 API本文的四个服务器只用到了其中很小一部分。继续探索的方向包括寻找更多适合自己场景的 MCP 服务器、尝试listToolsets()的动态工具注入、为需要 OAuth 的服务器走authenticate()授权流、把listToolDefinitions()产出的可序列化工具定义缓存到 Redis 或数据库实现跨进程复用以及结合第三课程模块Agent Memory进一步打磨记忆策略。MCP 生态正在持续扩张每一次接入都是在为你的 Mastra Agent 打开一扇通往外部世界的新窗口。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考