MCP 概覽

Mastra 支援 Model Context Protocol（MCP），這是一套將 AI Agent 連接至外部 Tool 與資源的開放標準。

使用 MCPClient 連接 MCP 伺服器。使用 MCPServer 將 Mastra Agent、Tool、Workflow、提示詞與資源公開給其他相容 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 驗證。

將已設定伺服器的 Tool 傳給 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(),
})

靜態與執行階段 Tool

請根據伺服器設定是否會隨要求改變，選擇 Tool 的載入方式：

	靜態 Tool	執行階段 Toolset
方法	await mcpClient.listTools()	await mcpClient.listToolsets()
使用情境	共用的固定設定	各使用者或各要求的設定
憑證	所有要求共用	可隨要求改變
Agent API	Agent 建構函式中的 tools	generate() 或 stream() 中的 toolsets

前述 Agent 範例使用靜態 Tool。若要使用執行階段憑證，請為該要求建立用戶端，並在呼叫 Agent 時傳入其 Toolset：

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()。

Tool 核准

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

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

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

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

對於非由你控制之伺服器所提供的 Tool 註解，應視為不受信任的提示。如需回呼內容與安全性指引，請參閱 Tool 核准。

安全性

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

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

如需各選項的強制執行細節，請參閱 MCPClient 安全性參考資料。

MCP Registry

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

Registry	連線方式	備註
Klavis AI	託管 HTTP	企業驗證與受管理伺服器
mcp.run	簽署的 SSE URL	將設定檔 URL 視為機密
Composio	託管 SSE URL	URL 通常繫結至單一使用者帳號
Smithery	CLI 或託管 URL	透過 npx 執行本機套件
Apify	託管 HTTP	使用 Apify API 權杖驗證
Ampersand	SSE 或 stdio	連接至已設定的 SaaS 整合

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

公開 Mastra MCP 伺服器

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

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 保護。

如需提示詞、資源、傳輸方式與其他伺服器選項，請參閱 MCPServer 參考資料。

建置 MCP Apps

MCP Apps 擴充功能可讓 MCP Tool 透過 ui:// 資源提供互動式 HTML 介面。Mastra Studio 會在 Tool 頁面與 Agent 聊天中，以Sandbox 化 iframe 轉譯這些應用程式。

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

定義應用程式資源

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

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

將應用程式連接至 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>

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 參考資料。

註冊 MCP Apps

對於本機應用程式，請將 Tool 傳給 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() 載入其 Tool 並註冊 Proxy，讓 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() 載入的 Tool 會在 _meta.ui 中包含 serverId，讓 Studio 不必掃描每台伺服器即可解析各個應用程式資源。如需 Proxy 設定詳細資料，請參閱 toMCPServerProxies()。

Sandbox 安全性

Mastra Studio 使用 @mcp-ui/client，透過 Sandbox Proxy 載入應用程式 HTML，並以 postMessage 透過 JSON-RPC 通訊。

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

後續步驟

• 搭配 Agent 使用 Tool
• MCPClient 參考資料
• MCPServer 參考資料
• MCP Apps 擴充功能規格