> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# MCP 概述

Mastra 支持 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/introduction)。这是一项用于将 AI Agent 连接到外部 Tool 和资源的开放标准。

使用 [`MCPClient`](https://mastra.zisheng.pro/reference/tools/mcp-client) 连接到 MCP Server。使用 [`MCPServer`](https://mastra.zisheng.pro/reference/tools/mcp-server) 将 Mastra Agent、Tool、Workflow、prompt 和资源暴露给其他兼容 MCP 的系统。

## 连接到 MCP Server

安装 MCP 包：

**npm**:

```bash
npm install @mastra/mcp@latest
```

**pnpm**:

```bash
pnpm add @mastra/mcp@latest
```

**Yarn**:

```bash
yarn add @mastra/mcp@latest
```

**Bun**:

```bash
bun add @mastra/mcp@latest
```

使用本地命令或远程 URL 配置各个 Server：

```typescript
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 保护的 Server，使用 `authenticate()` 完成基于浏览器的授权流程。有关配置详情，请参阅 [OAuth 身份验证](https://mastra.zisheng.pro/reference/tools/mcp-client)。

将已配置 Server 中的 Tool 传给 Agent：

```typescript
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(),
})
```

### 静态 Tool 与运行时 Toolset

根据 Server 配置是否会在请求之间发生变化，选择相应的 Tool 加载方式：

|           | 静态 Tool                       | 运行时 Toolset                             |
| --------- | ----------------------------- | --------------------------------------- |
| 方法        | `await mcpClient.listTools()` | `await mcpClient.listToolsets()`        |
| 使用场景      | 共享的固定配置                       | 按用户或按请求配置                               |
| 凭据        | 所有请求共享                        | 可随请求变化                                  |
| Agent API | `Agent` 构造函数中的 `tools`        | `generate()` 或 `stream()` 中的 `toolsets` |

前面的 Agent 示例使用静态 Tool。如需使用运行时凭据，请为当前请求创建客户端，并在调用 Agent 时传入其 Toolset：

```typescript
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()`](https://mastra.zisheng.pro/reference/tools/mcp-client) 和 [`listToolsets()`](https://mastra.zisheng.pro/reference/tools/mcp-client)。

### Tool 审批

在 Server 上设置 `requireToolApproval`，要求对该 Server 的所有 Tool 进行审批：

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

你也可以提供一个函数，根据 Tool 名称、参数或 annotation 作出决定：

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

对于不受你控制的 Server，请将其 Tool annotation 视为不可信提示。有关回调上下文和安全指南，请参阅 [Tool 审批](https://mastra.zisheng.pro/reference/tools/mcp-client)。

### 安全性

MCP Server 会代表 Agent 运行代码并返回内容，因此配置它们时应像对待任何其他外部依赖一样谨慎：

- **Stdio 子进程环境**：子进程只继承 MCP SDK 筛选后的环境变量白名单（例如 POSIX 上的 `PATH` 和 `HOME`），而不是完整的父进程环境。在 Server 上设置 `inheritDefaultEnv: false`，即可只传递你在 `env` 中列出的变量。
- **出站主机限制**：当 HTTP Server URL 来自不可信配置时，设置 `allowedHosts` 来限制客户端可以联系的主机。在默认 fetch 路径上，这还会在发送请求之前阻止重定向跳转；自定义 `fetch` 则会在请求运行后验证其最终响应 URL，因此当需要阻止出站连接时，它本身必须强制执行重定向策略。
- **Tool 响应可信度**：Tool 结果是不可信的模型输入。在内容到达模型前，使用[输入和输出 Processor](https://mastra.zisheng.pro/docs/agents/processors)检查或清理内容，并通过 `requireToolApproval` 限制敏感 Tool。

有关每个选项的强制执行细节，请参阅 [MCPClient 安全性 Reference](https://mastra.zisheng.pro/reference/tools/mcp-client)。

### MCP Registry

Registry 提供托管或打包的 MCP Server。上述客户端配置适用于 Registry endpoint 和命令。

| Registry                                        | 连接方式        | 说明                        |
| ----------------------------------------------- | ----------- | ------------------------- |
| [Klavis AI](https://klavis.ai)                  | 托管 HTTP     | 企业身份验证和托管 Server          |
| [mcp.run](https://www.mcp.run/)                 | 签名 SSE URL  | 将 profile URL 视为密钥        |
| [Composio](https://mcp.composio.dev)            | 托管 SSE URL  | URL 通常与单个用户账户绑定           |
| [Smithery](https://smithery.ai)                 | CLI 或托管 URL | 通过 `npx` 运行本地包            |
| [Apify](https://mcp.apify.com)                  | 托管 HTTP     | 使用 Apify API token 进行身份验证 |
| [Ampersand](https://docs.withampersand.com/mcp) | SSE 或 stdio | 连接到已配置的 SaaS 集成           |

将签名 URL、API Key 和 token 存储在环境变量中。按照 Registry 的文档获取每个 Server 的 endpoint、命令和凭据。

## 暴露 Mastra MCP Server

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

```typescript
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` 实例中注册 Server：

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

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

> **身份验证:** 使用 OAuth middleware 保护 HTTP MCP Server。有关设置说明，请参阅 [OAuth 保护](https://mastra.zisheng.pro/reference/tools/mcp-server)。

有关 prompt、资源、transport 和其他 Server 选项，请参阅 [`MCPServer` Reference](https://mastra.zisheng.pro/reference/tools/mcp-server)。

## 构建 MCP App

[MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) 让 MCP Tool 能够通过 `ui://` 资源提供交互式 HTML 界面。Mastra Studio 会在 Tool 页面和 Agent 对话中以沙盒 iframe 渲染这些 App。

当 Tool 结果适合交互时，例如表单、计算器、颜色选择器或数据可视化，可以使用 MCP App。

### 定义 App 资源

在 `content` 中返回简短的模型摘要，并将 UI 数据放入 `structuredContent`。将 `_meta.ui.resourceUri` 设置为 `appResources` 中使用的同一个 `ui://` URI，以便将 Tool 链接到 App：

```typescript
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(),
  }),
  execute: async ({ num1, num2 }) => ({
    content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
    structuredContent: { result: num1 + num2 },
  }),
})

calculatorTool._meta = {
  ui: { resourceUri: 'ui://calculator/main' },
}

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`，而 App 会收到 `structuredContent`。有关内联 HTML、文件路径、metadata 和内容安全策略选项，请参阅 [`appResources`](https://mastra.zisheng.pro/reference/tools/mcp-server)。

### 将 App 连接到 Studio

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

```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>
```

Guest 端 API 分别负责交互的不同部分：

| API                    | 用途                     |
| ---------------------- | ---------------------- |
| `app.ontoolinput`      | 接收 Host 端 Tool 调用传入的参数 |
| `app.callServerTool()` | 从 iframe 内部调用 MCP Tool |
| `app.sendMessage()`    | 向对话中添加用户消息并开始新的模型轮次    |
| `app.connect()`        | 注册事件处理程序后连接到 Host      |

交互遵循以下顺序：

1. Agent 调用 Tool。
2. Tool 返回面向模型的 `content` 和面向 UI 的 `structuredContent`。
3. Studio 渲染关联的 App 资源。
4. App 接收 Tool 输入，并可调用 Server Tool 或发送对话消息。

有关所有 Guest 端方法和生命周期 hook，请参阅外部 [`App` API Reference](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html)。

### 注册 MCP App

对于本地 App，将 Tool 传给 Agent，并在 `Mastra` 上注册其 MCP Server：

```typescript
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 App 的外部 MCP Server，使用 `MCPClient.listTools()` 加载其 Tool 并注册代理，以便 Studio 解析远程 App 资源：

```typescript
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()` 加载的 Tool 会在 `_meta.ui` 中包含 `serverId`，使 Studio 无需扫描每个 Server 即可解析相应的 App 资源。有关代理配置详情，请参阅 [`toMCPServerProxies()`](https://mastra.zisheng.pro/reference/tools/mcp-client)。

### Sandbox 安全性

Mastra Studio 使用 [`@mcp-ui/client`](https://www.npmjs.com/package/@mcp-ui/client)，通过 Sandbox 代理加载 App HTML，并使用 `postMessage` 通过 JSON-RPC 进行通信。

App iframe 允许使用脚本、表单和弹出窗口，但无法访问父页面的 DOM、Cookie 或存储。Host 控制与 Guest App 的所有通信。

## 后续步骤

- [在 Agent 中使用 Tool](https://mastra.zisheng.pro/docs/agents/using-tools)
- [`MCPClient` Reference](https://mastra.zisheng.pro/reference/tools/mcp-client)
- [`MCPServer` Reference](https://mastra.zisheng.pro/reference/tools/mcp-server)
- [MCP Apps extension 规范](https://github.com/modelcontextprotocol/ext-apps)