企业官网建设流程全解析

Mastra Agent 接入 MCP（Model Context Protocol）：从概念到实战配置指南

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

导读

本指南以 Mastra 官方课程《Installing and Setting Up MCP》为骨架，系统讲解如何在 Mastra 框架中为 Agent 接入 MCP（Model Context Protocol）服务器。你将掌握 MCP 的核心概念、@mastra/mcp包的安装、MCPClient的配置方法（含 HTTP 与 stdio 两种传输方式）、工具初始化与挂载流程，以及 Zapier、GitHub、Hacker News、Filesystem 四个真实 MCP 服务器的接入实例。读完本文，你可以不编写任何自定义工具函数，就让 Agent 直接调用外部服务能力。

什么是 MCP（Model Context Protocol）

MCP（Model Context Protocol，模型上下文协议）是一种开放标准，它让 AI 模型能够通过统一、一致的接口访问外部工具与服务。在 Mastra 中，MCP 的价值在于：你无需为每一个外部能力手写自定义工具（tool）函数，只需接入对应的 MCP 服务器，Agent 就能直接使用这些服务器暴露的工具。

MCP 采用客户端-服务器（Client-Server）架构：

• MCP 客户端：在 Mastra 中即@mastra/mcp包提供的MCPClient，负责与远端服务器通信、拉取工具列表；
• MCP 服务器：提供具体能力的服务端，可以是通过url访问的远程 HTTP 服务（如 Zapier、GitHub Copilot 官方 MCP），也可以是通过command本地启动的进程（如 Hacker News、Filesystem 服务器）。

这种解耦设计意味着你的 Agent 可以快速获得来自不同生态的成百上千种工具，而无需重复造轮子。

接入 MCP 后 Agent 能获得的能力

将 MCP 服务器接入 Mastra Agent 后，你可以为 Agent 赋予以下典型能力（来自课程文档的能力清单）：

• 邮件服务：如 Gmail、Outlook 的收发、搜索；
• 代码仓库：如 GitHub 的仓库监控、PR/Issue 查看；
• 社交媒体平台：如 Twitter/X、LinkedIn 的内容交互；
• 天气信息：查询实时天气数据；
• 新闻源：获取新闻与行业动态；
• 文件系统：读写本地文件、管理笔记等持久化数据；
• 以及更多服务：凡是生态中存在 MCP 服务器的服务，都可以按相同方式接入。

第一步：安装 @mastra/mcp 包

在 Mastra 项目中，首先需要安装 MCP 客户端包：

npm install @mastra/mcp@latest

@mastra/mcp包提供了将 Mastra Agent 连接到各类 MCP 服务器所需的全部基础设施，它负责 Agent 与 MCP 服务器之间的通信——包括连接建立、工具发现（tool discovery）与调用转发。在仓库中，该包位于 packages/mcp 目录，其核心实现包括：

• packages/mcp/src/index.ts：包入口，导出客户端与服务器端 API；
• packages/mcp/src/client：客户端实现（MCPClient、配置解析、OAuth、URL 策略等）；
• packages/mcp/src/server：MCP 服务器端实现（将 Mastra 工具以 MCP 协议暴露给其他客户端）。

第二步：创建 MCPClient 配置

安装完成后，打开你的 Agent 文件（课程示例为src/mastra/agents/index.ts），引入MCPClient并创建配置对象：

import { MCPClient } from '@mastra/mcp' const mcp = new MCPClient({ servers: { // 在这里添加各个 MCP 服务器 }, })

servers属性是一个对象：每个键（key）是服务器的唯一标识符，值为该服务器的连接配置。后续添加任何 MCP 服务器，本质都是往这个对象里增加条目。

两种服务器传输方式

从配置结构看，@mastra/mcp支持两种主流 MCP 传输模式（课程后续章节分别给出了实例，源码层面由 packages/mcp/src/client/configuration.ts 统一解析）：

第三步：初始化 MCP 工具

配置好服务器后，需要异步初始化工具列表：

const mcpTools = await mcp.listTools()

listTools()是一个异步方法，它会连接配置中指定的每一个 MCP 服务器，拉取这些服务器暴露的全部工具，并以 Mastra Agent 可直接使用的格式返回。返回的mcpTools对象中包含所有已配置服务器的工具集合。

值得注意的扩展特性：后续每新增一个 MCP 服务器，只要重新调用listTools()，返回的mcpTools就会自动包含新服务器的工具——这正是 MCP 体系可组合、可扩展的体现。

第四步：将 MCP 工具挂载到 Agent

初始化得到mcpTools后，将其展开（spread）进 Agent 的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 })

通过{ ...mcpTools }的展开语法，所有 MCP 服务器提供的工具都会进入 Agent 的工具集，Agent 在响应用户请求时即可按需调用它们。这是接入流程中最关键的一步——它把"服务器能力"真正转化成了"Agent 能力"。

第五步：验证基础配置

在尚未配置任何 MCP 服务器时，可以先行验证整体链路是否打通（课程文档给出的验证步骤）：

1. 确保开发服务器运行中：npm run dev；
2. 打开 Playground：http://localhost:4111/；
3. 在 Agent 列表中应能看到你的 "Personal Assistant"；
4. 发送一条消息，例如 "Hello, what can you help me with?"。

此时 Agent 能够正常应答，但尚不具备特殊能力——因为还没有配置具体的 MCP 服务器。

实战接入：四个 MCP 服务器配置详解

课程后续章节以"逐步为 Agent 增加服务器"的方式展开，下面把四个服务器的配置要点完整整理出来。最终效果是一个同时具备邮件/社交、代码仓库、技术资讯、本地文件管理能力的完整配置。

1. Zapier MCP：连接数千个应用与服务

Zapier MCP 服务器通过 Zapier 平台提供对数千个应用与服务的访问，包括：

• 邮件服务（Gmail、Outlook 等）；
• 社交媒体平台（Twitter/X、LinkedIn 等）；
• 项目管理工具（Trello、Asana 等）；
• 以及更多。

获取 URL 与 API Key

Zapier MCP 需要认证，你需要从 Zapier 获取两样东西：

1. MCP Server URL：Agent 连接的端点；
2. API Key：随每个请求发送以证明身份的密钥。

获取步骤：

1. 创建 Zapier 账号；
2. 访问mcp.zapier.com，选择+ New MCP Server；
3. 客户端类型选择OpenAI API（提供 API Key 认证方式，与自定义 MCP 客户端如 Mastra 配合良好）；
4. 为服务器添加工具（例如搜索 "Gmail" 并添加 "Find Email" 与 "Send Email"）；
5. 打开Connect标签页，找到MCP Server URL与API Key（如需要可点击Rotate token生成）。

重要提醒：API Key 只在显示时出现一次，务必立即复制保存。若不慎丢失，需重新点击Rotate token生成新密钥。

将两个值写入.env文件：

# 添加到 .env 文件 ZAPIER_MCP_URL=https://mcp.zapier.com/api/v1/connect ZAPIER_MCP_API_KEY=your-api-key-here

使用环境变量可以将凭据隔离在源码之外，同时确保.env已被加入.gitignore，避免敏感信息入库。

配置 Zapier 服务器

在MCPClient配置中新增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：该服务器在配置中的唯一标识符；
• url：从.env读取的 Zapier MCP 服务端点。new URL()将字符串构造为 URL 对象，|| ''提供空字符串兜底——即使环境变量缺失也不会导致应用崩溃；
• requestInit.headers：随每次请求发送的 HTTP 头；
• Authorization: Bearer ...：以 Bearer Token 形式携带 API Key，完成 Zapier 的身份校验。

2. GitHub MCP：监控与交互 GitHub 仓库

官方 GitHub MCP 服务器为 Agent 提供与 GitHub 仓库交互的能力，典型用途包括：

• 监控仓库活动；
• 查看 Pull Request 与 Issue；
• 浏览提交历史；
• 总结开发模式。

对于希望随时掌握项目动态、又不想反复手动登录 GitHub 查看的开发者与团队尤其有用。其接入方式与 Zapier 类似——远程 HTTP 服务 + Bearer Token 认证：

github: { url: new URL('https://api.githubcopilot.com/mcp/'), requestInit: { headers: { Authorization: `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN}`, }, }, },

需要你在.env中配置GITHUB_PERSONAL_ACCESS_TOKEN（GitHub Personal Access Token）。

3. Hacker News MCP：获取科技资讯与讨论

Hacker News MCP 服务器让 Agent 可以访问 Hacker News 上的内容，包括：

• 获取热门故事（top stories）；
• 搜索特定故事；
• 跟进科技趋势与新闻。

它通过 stdio 方式本地启动——使用npx运行社区维护的服务器包，无需任何 API Key：

hackernews: { command: 'npx', args: ['-y', '@devabdultech/hn-mcp-server'], },

command指定启动服务器的可执行程序，args提供传给该程序的参数：-y表示自动确认安装，后面是服务器包名。

4. Filesystem MCP：读写本地文件系统

Filesystem MCP 服务器为 Agent 提供本地文件系统交互能力：

• 读取文件；
• 写入文件；
• 创建目录；
• 列出文件与目录；
• 管理笔记、待办清单等持久化数据。

这对构建"跨会话保持信息"的助手非常关键——Agent 创建的笔记和文档在应用关闭后依然存在。同样使用 stdio 方式启动：

import path from 'path' textEditor: { command: 'pnpx', args: [ `@modelcontextprotocol/server-filesystem`, path.join(process.cwd(), '..', '..', 'notes'), // 相对于输出目录 ], },

配置说明：

• textEditor：该服务器在配置中的唯一标识符；
• command: 'pnpx'：使用 pnpm 的包执行器启动服务器；
• args：第一个参数为官方 filesystem 服务器包名；第二个参数通过path.join(process.cwd(), '..', '..', 'notes')定位到预先创建的 notes 目录。path.join保证路径拼接正确，不受应用启动位置影响。

课程建议先创建好notes目录（例如放在项目仓库外层），再让 MCP 服务器指向它，Agent 即可在此目录中创建与管理笔记。

汇总：完整的多服务器配置

将上述四个服务器合并，即得到课程最终形态的配置（见 docs/src/course/02-agent-tools-mcp/26-updating-mcp-config-filesystem.md）：

import { MCPClient } from '@mastra/mcp' 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'), ], }, }, }) const mcpTools = await mcp.listTools() 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 }, })

配置完成后重启开发服务器，即可在 Playground 中让 Agent 使用邮件、GitHub、资讯与本地文件等全部能力。

源码视角：MCPClient 的实现印证

如果你对底层原理感兴趣，可以在仓库中进一步研读：

• packages/mcp/src/client/index.ts：MCPClient的客户端导出与主要实现，包括listTools()等核心方法；
• packages/mcp/src/client/configuration.ts：服务器配置（url/requestInit、command/args）的解析与标准化逻辑，是本文两种传输方式配置能够被统一处理的关键；
• packages/mcp/src/client/types.ts：客户端相关类型定义；
• packages/mcp/src/client/client.test.ts：客户端行为测试；
• packages/mcp/src/server/server.ts：MCP 服务器端实现——它让 Mastra 自己的工具反过来也能通过 MCP 协议暴露给其他 AI 客户端。

从源码结构看，MCPClient的设计同时覆盖了"作为客户端消费外部 MCP 工具"与"作为服务器暴露 Mastra 工具"两个方向，listTools()负责在连接建立后完成工具发现，这与课程文档描述的调用流程完全一致。

小结

通过本文，你已经完成了从概念到实战的完整闭环：理解了 MCP 的客户端-服务器模型，掌握了@mastra/mcp的安装、MCPClient配置、listTools()初始化、tools挂载与 Playground 验证的完整流程，并获得了 Zapier（远程 HTTP + Bearer 认证）、GitHub（远程 HTTP）、Hacker News（stdio + npx）、Filesystem（stdio + 本地目录）四类典型服务器的可运行配置模板。

这套模式具备极强的可扩展性：社区中任何遵循 MCP 标准的服务器，都可以按照"加一条配置 → 重新listTools()"的方式接入你的 Mastra Agent，让 Agent 的能力随服务器生态持续增长。

本文内容基于 Mastra 官方课程 docs/src/course/02-agent-tools-mcp 系列文档（01–29 节）整理，配置中的模型标识与第三方包名请以你实际使用的环境与版本为准。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra