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

# MCP 概覽

Mastra 支援 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/introduction)，這是一套將 AI Agent 連接至外部 Tool 與資源的開放標準。

使用 [`MCPClient`](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client) 連接 MCP 伺服器。使用 [`MCPServer`](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-server) 將 Mastra Agent、Tool、Workflow、提示詞與資源公開給其他相容 MCP 的系統。

## 連接 MCP 伺服器

安裝 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 設定各個伺服器：

```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 保護的伺服器，請使用 `authenticate()` 完成以瀏覽器為基礎的授權流程。如需設定詳細資料，請參閱 [OAuth 驗證](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client)。

將已設定伺服器的 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

請根據伺服器設定是否會隨要求改變，選擇 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/zh-TW/reference/tools/mcp-client) 與 [`listToolsets()`](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client)。

### Tool 核准

在伺服器上設定 `requireToolApproval`，要求其所有 Tool 都必須經過核准：

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

你也可以提供一個函式，根據 Tool 名稱、引數或註解決定是否需要核准：

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

對於非由你控制之伺服器所提供的 Tool 註解，應視為不受信任的提示。如需回呼內容與安全性指引，請參閱 [Tool 核准](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client)。

### 安全性

MCP 伺服器會代表你的 Agent 執行程式碼並傳回內容，因此設定時應像對待其他外部相依套件一樣謹慎：

- **Stdio 子處理程序環境**：子處理程序只會繼承 MCP SDK 維護的環境變數白名單（例如 POSIX 上的 `PATH` 與 `HOME`），而非完整的父處理程序環境。在伺服器上設定 `inheritDefaultEnv: false`，即可只傳遞列於 `env` 中的變數。
- **連出主機限制**：當 HTTP 伺服器 URL 來自不受信任的設定時，請設定 `allowedHosts`，限制用戶端可連絡的主機。使用預設 fetch 路徑時，這也會在送出前封鎖重新導向；自訂 `fetch` 則會在要求執行後驗證最終回應 URL，因此需要防止連出時，必須自行強制執行重新導向政策。
- **Tool 回應信任**：Tool 結果是不受信任的模型輸入。請使用[輸入與輸出處理器](https://mastra.zisheng.pro/zh-TW/docs/agents/processors)，在內容抵達模型前檢查或清理內容，並以 `requireToolApproval` 管制敏感 Tool。

如需各選項的強制執行細節，請參閱 [MCPClient 安全性參考資料](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client)。

### MCP Registry

Registry 提供託管或封裝的 MCP 伺服器。上述用戶端設定可搭配 Registry 端點與指令使用。

| Registry                                        | 連線方式        | 備註                |
| ----------------------------------------------- | ----------- | ----------------- |
| [Klavis AI](https://klavis.ai)                  | 託管 HTTP     | 企業驗證與受管理伺服器       |
| [mcp.run](https://www.mcp.run/)                 | 簽署的 SSE URL | 將設定檔 URL 視為機密     |
| [Composio](https://mcp.composio.dev)            | 託管 SSE URL  | URL 通常繫結至單一使用者帳號  |
| [Smithery](https://smithery.ai)                 | CLI 或託管 URL | 透過 `npx` 執行本機套件   |
| [Apify](https://mcp.apify.com)                  | 託管 HTTP     | 使用 Apify API 權杖驗證 |
| [Ampersand](https://docs.withampersand.com/mcp) | SSE 或 stdio | 連接至已設定的 SaaS 整合   |

將簽署的 URL、API 金鑰與權杖儲存在環境變數中。請依 Registry 文件取得各伺服器的端點、指令與憑證。

## 公開 Mastra MCP 伺服器

建立 `MCPServer`，向外部 MCP 用戶端公開 Mastra 基本元件：

```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` 執行個體上註冊伺服器：

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

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

> **驗證:** 使用 OAuth 中介軟體保護 HTTP MCP 伺服器。如需設定說明，請參閱 [OAuth 保護](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-server)。

如需提示詞、資源、傳輸方式與其他伺服器選項，請參閱 [`MCPServer` 參考資料](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-server)。

## 建置 MCP Apps

[MCP Apps 擴充功能](https://github.com/modelcontextprotocol/ext-apps)可讓 MCP Tool 透過 `ui://` 資源提供互動式 HTML 介面。Mastra Studio 會在 Tool 頁面與 Agent 聊天中，以Sandbox 化 iframe 轉譯這些應用程式。

當 Tool 結果適合加入表單、計算機、色彩選擇器或資料視覺化等互動時，請使用 MCP App。

### 定義應用程式資源

為模型傳回簡短的 `content` 摘要，並將 UI 資料放入 `structuredContent`。將 `_meta.ui.resourceUri` 設為 `appResources` 所使用的同一個 `ui://` URI，即可將 Tool 連結至其應用程式：

```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`，應用程式則會收到 `structuredContent`。如需行內 HTML、檔案路徑、中繼資料與內容安全性政策選項，請參閱 [`appResources`](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-server)。

### 將應用程式連接至 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 轉譯相關聯的應用程式資源。
4. 應用程式接收 Tool 輸入，並可呼叫伺服器 Tool 或傳送聊天訊息。

如需所有 Guest 端方法與生命週期 Hook，請參閱外部 [`App` API 參考資料](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html)。

### 註冊 MCP Apps

對於本機應用程式，請將 Tool 傳給 Agent，並在 `Mastra` 上註冊其 MCP 伺服器：

```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 Apps 的外部 MCP 伺服器，請使用 `MCPClient.listTools()` 載入其 Tool 並註冊 Proxy，讓 Studio 能解析遠端應用程式資源：

```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 不必掃描每台伺服器即可解析各個應用程式資源。如需 Proxy 設定詳細資料，請參閱 [`toMCPServerProxies()`](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client)。

### Sandbox 安全性

Mastra Studio 使用 [`@mcp-ui/client`](https://www.npmjs.com/package/@mcp-ui/client)，透過 Sandbox Proxy 載入應用程式 HTML，並以 `postMessage` 透過 JSON-RPC 通訊。

應用程式 iframe 允許指令碼、表單與彈出式視窗，但無法存取父頁面的 DOM、Cookie 或 Storage。Host 會控制與 Guest 應用程式之間的所有通訊。

## 後續步驟

- [搭配 Agent 使用 Tool](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)
- [`MCPClient` 參考資料](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-client)
- [`MCPServer` 參考資料](https://mastra.zisheng.pro/zh-TW/reference/tools/mcp-server)
- [MCP Apps 擴充功能規格](https://github.com/modelcontextprotocol/ext-apps)