MCP

Mastra 支持 Model Context Protocol (MCP)，这是一种用于将 AI agents 连接到外部工具和资源的开放标准。

使用 MCPClient 连接 MCP 服务器。使用 MCPServer 将 Mastra agents、工具、workflows、prompts 和资源暴露给其他兼容 MCP 的系统。两者都通过 stdio 和 Streamable HTTP 使用 MCP 2026-07-28 修订版协议。

对于 Neon、Canva 等托管 MCP 服务器，Mastra 平台上的 Connect 可以代你管理 OAuth 流程和凭据，使 agents 通过 tools() 获取服务器工具，而无需手动配置 MCPClient。

备注

从 @mastra/mcp 1.x 升级？参见迁移指南。

关于凭据选择和权限边界，参见使用 MCP 进行身份验证与授权。

连接 MCP 服务器

安装 MCP 包：

npm

npm install @mastra/mcp@latest

pnpm

pnpm add @mastra/mcp@latest

Yarn

yarn add @mastra/mcp@latest

Bun

bun add @mastra/mcp@latest

使用本地命令或远程 URL 配置每个服务器：

src/mastra/mcp/client.ts

import { MCPClient } from '@mastra/mcp'

export const mcpClient = new MCPClient({
  id: 'my-mcp-client',
  servers: {
    wikipedia: {
      command: 'npx',
      args: ['-y', 'wikipedia-mcp'],
    },
    weather: {
      url: new URL('https://weather.example.com/mcp'),
      requestInit: {
        headers: {
          Authorization: `Bearer ${process.env.WEATHER_API_KEY}`,
        },
      },
    },
  },
})

身份验证

对于受 OAuth 保护的服务器，使用 authenticate() 完成基于浏览器的授权流程。配置细节参见 OAuth 身份验证。

将已配置服务器的工具传给 Agent：

src/mastra/agents/assistant.ts

import { Agent } from '@mastra/core/agent'
import { mcpClient } from '../mcp/client'

export const assistant = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: `
    Use the available MCP tools to answer questions.
    Include the source of any information you retrieve.
  `,
  model: 'openai/gpt-5.6-sol',
  tools: await mcpClient.listTools(),
})

静态工具与运行时工具

根据服务器配置是否会在请求之间变化，选择工具的加载方式：

	静态工具	运行时 toolsets
方法	await mcpClient.listTools()	await mcpClient.listToolsets()
用例	共享的固定配置	按用户或按请求配置
凭据	所有请求共享	可在请求之间变化
Agent API	Agent 构造函数中的 tools	generate() 或 stream() 中的 toolsets

前面的 Agent 示例使用静态工具。若需要运行时凭据，可为该请求创建客户端，并在调用 Agent 时传入其 toolsets：

src/handle-request.ts

import { MCPClient } from '@mastra/mcp'
import { mastra } from './mastra'

export async function handleRequest(prompt: string, apiKey: string) {
  const userMcpClient = new MCPClient({
    servers: {
      weather: {
        url: new URL('https://weather.example.com/mcp'),
        requestInit: {
          headers: { Authorization: `Bearer ${apiKey}` },
        },
      },
    },
  })

  const agent = mastra.getAgent('assistant')
  const response = await agent.generate(prompt, {
    toolsets: await userMcpClient.listToolsets(),
  })

  await userMcpClient.disconnect()
  return response.text
}

完整 API 参见 listTools() 和 listToolsets()。

工具审批

在服务器上设置 requireToolApproval，可要求对其所有工具进行审批：

const mcpClient = new MCPClient({
  servers: {
    github: {
      url: new URL('https://github.example.com/mcp'),
      requireToolApproval: true,
    },
  },
})

你也可以提供一个函数，根据工具名称、参数或注解来决定：

requireToolApproval: ({ toolName }) => toolName.startsWith('delete_')

对于你无法控制的服务器，其工具注解应视为不受信任的提示。回调上下文和安全指南参见工具审批。

安全

MCP 服务器会代表你的 Agent 运行代码并返回内容，因此配置时应像对待其他外部依赖一样谨慎：

• Stdio 子进程环境：子进程仅继承 MCP SDK 精选的环境变量白名单（例如 POSIX 上的 PATH 和 HOME），而不是完整的父环境。在服务器上设置 inheritDefaultEnv: false，可只传递你在 env 中列出的变量。
• 出站主机限制：当 HTTP 服务器 URL 来自不受信任的配置时，设置 allowedHosts，限制客户端可联系的主机。默认 fetch 路径还会在发送前阻止重定向跳转。自定义 fetch 只会在请求完成后根据最终响应 URL 进行校验，因此如果必须阻止出站访问，它需要自行实施重定向策略。
• 工具响应信任：工具结果是不受信任的模型输入。使用输入和输出处理器在内容到达模型前进行检查或清理，并用 requireToolApproval 为敏感工具设置审批关卡。

各选项的具体执行细节参见 MCPClient 安全参考。

MCP 注册表

注册表提供托管或打包的 MCP 服务器。上面的客户端配置同样适用于注册表端点和命令。

注册表	连接方式	说明
Klavis AI	托管 HTTP	企业级身份验证和托管服务器
mcp.run	签名托管 URL	将 profile URL 视为机密
Composio	托管 URL	URL 通常与单个用户账户绑定
Smithery	CLI 或托管 URL	通过 npx 运行本地包
Apify	托管 HTTP	使用 Apify API token 进行身份验证
Ampersand	托管 URL 或 stdio	连接已配置的 SaaS 集成

将签名 URL、API 密钥和 tokens 存储在环境变量中。按照各注册表的文档获取每个服务器的端点、命令和凭据。

暴露 Mastra MCP 服务器

创建 MCPServer，将 Mastra 原语暴露给外部 MCP 客户端：

src/mastra/mcp/server.ts

import { MCPServer } from '@mastra/mcp'
import { assistant } from '../agents/assistant'
import { weatherTool } from '../tools/weather'
import { weatherWorkflow } from '../workflows/weather'

export const mcpServer = new MCPServer({
  id: 'my-mcp-server',
  name: 'My MCP Server',
  version: '1.0.0',
  agents: { assistant },
  tools: { weatherTool },
  workflows: { weatherWorkflow },
})

在主 Mastra 实例上注册该服务器：

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { mcpServer } from './mcp/server'

export const mastra = new Mastra({
  mcpServers: { mcpServer },
})

身份验证

使用 OAuth 中间件保护 HTTP MCP 服务器。设置说明参见 OAuth 保护。

已注册的服务器通过 Streamable HTTP 在 /api/mcp/:serverId/mcp 提供服务。由于每个请求都是自包含的，同一个服务器可以在长时运行的主机和无服务器平台上不加修改地运行。

如果工具在完成前需要用户提供某些信息，可调用 context.suspend() 并携带一个 payload，同时声明 resumeSchema。服务器会将其转换为一个 input_required 轮次，并在答案放入 context.resumeData 后再次运行该工具。客户端在其服务器定义中通过 inputRequests 处理器回答这些轮次。参见向调用方请求输入和回答输入请求。

关于 prompts、资源、传输方式及其他服务器选项，参见 MCPServer 参考文档。

发布 stdio 服务器包

当你希望客户端通过 npx 等命令在本地运行时，可将使用标准输入/输出（stdio）传输方式的服务器打包。创建一个单独的可执行入口来启动服务器：

src/mastra/mcp/stdio.ts

#!/usr/bin/env node
import { mcpServer } from './server'

mcpServer.startStdio().catch(error => {
  console.error('Failed to start MCP server:', error)
  process.exit(1)
})

将该入口构建为可执行的 Node.js 文件，然后将包的 bin 字段指向该输出。将构建后的文件包含在发布的包中，并保留 shebang 作为第一行：

package.json

{
  "bin": {
    "my-mcp-server": "dist/stdio.js"
  },
  "files": ["dist"]
}

发布包后，配置客户端通过包名运行它：

src/mastra/mcp/client.ts

import { MCPClient } from '@mastra/mcp'

const mcpClient = new MCPClient({
  servers: {
    myServer: {
      command: 'npx',
      args: ['-y', '@your-org/my-mcp-server@1.0.0'],
    },
  },
})

包命名、身份验证和发布命令参见 npm 包发布文档。

构建 MCP Apps

MCP Apps 扩展让 MCP 工具可以通过 ui:// 资源提供交互式 HTML 界面。Mastra Studio 会在工具页面和 Agent 聊天中，以沙箱 iframe 渲染这些应用。

当工具结果能通过交互获益时（例如表单、计算器、颜色选择器或数据可视化），可使用 MCP App。

定义应用资源

为模型返回简短的 content 摘要，并将 UI 数据放入 structuredContent。将工具的 mcp._meta.ui.resourceUri 设置为与 appResources 中相同的 ui:// URI，以关联其应用：

src/mastra/mcp/calculator.ts

import { MCPServer } from '@mastra/mcp'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const calculatorTool = createTool({
  id: 'calculatorWithUI',
  description: 'Calculate the sum of two numbers',
  inputSchema: z.object({
    num1: z.number(),
    num2: z.number(),
  }),
  mcp: {
    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
  },
  execute: async ({ num1, num2 }) => ({
    content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
    structuredContent: { result: num1 + num2 },
  }),
})

export const calculatorMcpServer = new MCPServer({
  id: 'calculator-app-server',
  name: 'Calculator App Server',
  version: '1.0.0',
  tools: { calculatorTool },
  appResources: {
    'ui://calculator/main': {
      name: 'Calculator',
      htmlPath: './src/mastra/mcp/calculator.html',
    },
  },
})

模型看到的是 content，而应用接收的是 structuredContent。关于内联 HTML、文件路径、元数据和内容安全策略选项，参见 appResources。

将应用连接到 Studio

在 HTML 资源中使用 @modelcontextprotocol/ext-apps 的 App 类。在调用 connect() 之前注册事件处理器：

src/mastra/mcp/calculator.html

<!doctype html>
<html>
  <body>
    <p id="result">Waiting for input</p>
    <button id="recalculate">Recalculate</button>

    <script type="module">
      import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm'

      const app = new App({ name: 'Calculator', version: '1.0.0' })
      let toolInput

      app.ontoolinput = params => {
        toolInput = params.arguments
      }

      document.querySelector('#recalculate').addEventListener('click', async () => {
        const result = await app.callServerTool({
          name: 'calculatorWithUI',
          arguments: toolInput,
        })
        document.querySelector('#result').textContent = JSON.stringify(result)

        await app.sendMessage({
          role: 'user',
          content: [{ type: 'text', text: 'Explain the recalculated result.' }],
        })
      })

      await app.connect()
    </script>
  </body>
</html>

访客侧 API 分别服务于交互的不同部分：

API	用途
app.ontoolinput	接收来自宿主工具调用的参数
app.callServerTool()	在 iframe 内调用 MCP 工具
app.sendMessage()	向聊天添加用户消息并启动新一轮模型调用
app.connect()	在注册事件处理器后连接到宿主

交互按以下顺序进行：

1. Agent 调用工具。
2. 工具返回面向模型的 content 和面向 UI 的 structuredContent。
3. Studio 渲染关联的应用资源。
4. 应用接收工具输入，并可调用服务器工具或发送聊天消息。

完整的访客侧方法和生命周期钩子参见外部 App API 参考。

注册 MCP Apps

对于本地应用，将工具传给 Agent，并在 Mastra 上注册其 MCP 服务器：

src/mastra/index.ts

import { Agent } from '@mastra/core/agent'
import { Mastra } from '@mastra/core/mastra'
import { calculatorMcpServer, calculatorTool } from './mcp/calculator'

const calculatorAgent = new Agent({
  id: 'calculator-agent',
  name: 'Calculator Agent',
  instructions: 'Use the calculator tool for arithmetic.',
  model: 'openai/gpt-5-mini',
  tools: { calculatorTool },
})

export const mastra = new Mastra({
  agents: { calculatorAgent },
  mcpServers: { calculatorMcpServer },
})

对于实现了 MCP Apps 的外部 MCP 服务器，使用 MCPClient.listTools() 加载其工具，并注册其代理，使 Studio 能解析远程应用资源：

src/mastra/remote-apps.ts

import { Agent } from '@mastra/core/agent'
import { Mastra } from '@mastra/core/mastra'
import { mcpClient } from './mcp/client'

const tools = await mcpClient.listTools()
const mcpServers = mcpClient.toMCPServerProxies()

const agent = new Agent({
  id: 'remote-app-agent',
  name: 'Remote App Agent',
  instructions: 'Use the available remote tools.',
  model: 'openai/gpt-5-mini',
  tools,
})

export const mastra = new Mastra({
  agents: { agent },
  mcpServers,
})

通过 listTools() 加载的工具会在 _meta.ui 中包含 serverId，让 Studio 无需扫描每个服务器即可解析各应用资源。代理配置细节参见 toMCPServerProxies()。

沙箱安全

Mastra Studio 使用 @mcp-ui/client，通过沙箱代理加载应用 HTML，并使用 postMessage 进行 JSON-RPC 通信。

应用 iframe 允许脚本、表单和弹窗，但无法访问父页面的 DOM、cookies 或 storage。宿主控制与访客应用之间的所有通信。

后续步骤

• 在 agents 中使用工具
• MCPClient 参考文档
• MCPServer 参考文档
• MCP Apps 扩展规范