Vue d'ensemble de MCP

Mastra prend en charge le Model Context Protocol (MCP), un standard ouvert permettant de connecter des Agents d'IA à des Tools et ressources externes.

Utilisez MCPClient pour vous connecter aux serveurs MCP. Utilisez MCPServer pour exposer les Agents, Tools, Workflows, prompts et ressources Mastra à d'autres systèmes compatibles MCP.

Se connecter aux serveurs MCP

Installez le package 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

Configurez chaque serveur avec une commande locale ou une URL distante :

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

Authentification

Pour les serveurs protégés par OAuth, utilisez authenticate() afin de terminer le processus d'autorisation dans le navigateur. Consultez Authentification OAuth pour connaître les détails de configuration.

Transmettez à un Agent les Tools provenant des serveurs configurés :

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

Tools statiques et à l'exécution

Choisissez comment charger les Tools selon que la configuration du serveur change ou non entre les requêtes :

	Tools statiques	Ensembles de Tools à l'exécution
Méthode	await mcpClient.listTools()	await mcpClient.listToolsets()
Cas d'utilisation	Configuration fixe et partagée	Configuration par utilisateur ou par requête
Identifiants	Partagés par toutes les requêtes	Peuvent varier d'une requête à l'autre
API de l'Agent	tools dans le constructeur Agent	toolsets dans generate() ou stream()

L'exemple d'Agent précédent utilise des Tools statiques. Pour des identifiants déterminés à l'exécution, créez un client pour la requête et transmettez ses ensembles de Tools lors de l'appel à l'Agent :

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
}

Consultez listTools() et listToolsets() pour découvrir leurs API complètes.

Approbation des Tools

Définissez requireToolApproval sur un serveur pour exiger l'approbation de tous ses Tools :

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

Vous pouvez également fournir une fonction qui prend une décision en fonction du nom, des arguments ou des annotations du Tool :

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

Considérez les annotations de Tools provenant de serveurs que vous ne contrôlez pas comme des indications non fiables. Consultez Approbation des Tools pour connaître le contexte de la fonction de rappel et les recommandations de sécurité.

Sécurité

Les serveurs MCP exécutent du code et renvoient du contenu pour le compte de votre Agent. Configurez-les donc avec la même prudence que toute autre dépendance externe :

• Environnement des sous-processus stdio : les sous-processus n'héritent que de la liste blanche de variables d'environnement sélectionnée par le SDK MCP (par exemple PATH et HOME sous POSIX), et non de l'environnement parent complet. Définissez inheritDefaultEnv: false sur un serveur pour ne transmettre que les variables répertoriées dans env.
• Restriction des hôtes sortants : lorsque les URL des serveurs HTTP proviennent d'une configuration non fiable, définissez allowedHosts pour limiter les hôtes que le client peut contacter. Avec le parcours de récupération par défaut, cela bloque également les redirections avant leur envoi. Une fonction fetch personnalisée voit l'URL finale de sa réponse validée après l'exécution de la requête ; elle doit donc appliquer elle-même la stratégie de redirection lorsque les contacts sortants doivent être bloqués.
• Confiance dans les réponses des Tools : les résultats des Tools constituent des entrées non fiables pour le modèle. Utilisez des Processors d'entrée et de sortie pour inspecter ou assainir le contenu avant qu'il n'atteigne le modèle, et requireToolApproval pour soumettre les Tools sensibles à approbation.

Consultez la référence de sécurité de MCPClient pour connaître les modalités d'application de chaque option.

Registres MCP

Les registres proposent des serveurs MCP hébergés ou distribués sous forme de packages. La configuration client ci-dessus fonctionne avec les endpoints et les commandes des registres.

Registre	Connexion	Remarques
Klavis AI	HTTP hébergé	Authentification d'entreprise et serveurs gérés
mcp.run	URL SSE signée	Considérez l'URL du profil comme un secret
Composio	URL SSE hébergée	Les URL sont souvent liées à un seul compte utilisateur
Smithery	CLI ou URL hébergée	Exécutez les packages locaux avec npx
Apify	HTTP hébergé	Authentifiez-vous avec un token d'API Apify
Ampersand	SSE ou stdio	Connectez-vous aux intégrations SaaS configurées

Stockez les URL signées, clés d'API et tokens dans des variables d'environnement. Suivez la documentation du registre pour obtenir l'endpoint, la commande et les identifiants de chaque serveur.

Exposer un serveur MCP Mastra

Créez un MCPServer pour exposer les primitives Mastra à des clients MCP externes :

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

Enregistrez le serveur sur l'instance Mastra principale :

src/mastra/index.ts

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

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

Authentification

Protégez les serveurs MCP HTTP avec un middleware OAuth. Consultez Protection OAuth pour connaître les instructions de configuration.

Consultez la référence de MCPServer pour les prompts, les ressources, les transports et les autres options du serveur.

Créer des MCP Apps

L'extension MCP Apps permet aux Tools MCP de proposer des interfaces HTML interactives au moyen de ressources ui://. Mastra Studio affiche ces applications dans des iframes isolées sur les pages de Tools et dans le chat des Agents.

Utilisez une MCP App lorsque le résultat d'un Tool gagne à être interactif, par exemple sous la forme d'un formulaire, d'une calculatrice, d'un sélecteur de couleur ou d'une visualisation de données.

Définir une ressource d'application

Renvoyez un bref résumé content destiné au modèle et placez les données de l'interface dans structuredContent. Associez le Tool à son application en définissant _meta.ui.resourceUri sur le même URI ui:// que celui utilisé dans appResources :

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',
    },
  },
})

Le modèle voit content, tandis que l'application reçoit structuredContent. Consultez appResources pour découvrir les options de HTML intégré, de chemins de fichiers, de métadonnées et de stratégie de sécurité du contenu.

Connecter l'application à Studio

Utilisez la classe App de @modelcontextprotocol/ext-apps dans la ressource HTML. Enregistrez les gestionnaires d'événements avant d'appeler 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>

Les API côté application invitée prennent en charge différentes parties de l'interaction :

API	Fonction
app.ontoolinput	Recevoir les arguments de l'appel au Tool hôte
app.callServerTool()	Appeler un Tool MCP depuis l'iframe
app.sendMessage()	Ajouter un message utilisateur au chat et démarrer un nouvel échange avec le modèle
app.connect()	Se connecter à l'hôte après l'enregistrement des gestionnaires d'événements

L'interaction suit cette séquence :

1. L'Agent appelle le Tool.
2. Le Tool renvoie le contenu content destiné au modèle et le contenu structuredContent destiné à l'interface.
3. Studio affiche la ressource d'application associée.
4. L'application reçoit les entrées du Tool et peut appeler des Tools du serveur ou envoyer des messages dans le chat.

Consultez la référence externe de l'API App pour découvrir toutes les méthodes côté application invitée et les hooks du cycle de vie.

Enregistrer des MCP Apps

Pour une application locale, transmettez le Tool à un Agent et enregistrez son serveur MCP sur Mastra :

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

Pour un serveur MCP externe qui implémente MCP Apps, chargez ses Tools avec MCPClient.listTools() et enregistrez son proxy afin que Studio puisse résoudre les ressources d'application distantes :

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

Les Tools chargés au moyen de listTools() comprennent un serverId dans _meta.ui, ce qui permet à Studio de résoudre chaque ressource d'application sans analyser tous les serveurs. Consultez toMCPServerProxies() pour connaître les détails de configuration du proxy.

Sécurité du Sandbox

Mastra Studio utilise @mcp-ui/client pour charger le HTML de l'application au moyen d'un proxy de Sandbox et communiquer en JSON-RPC avec postMessage.

Les iframes des applications autorisent les scripts, les formulaires et les fenêtres contextuelles. Elles ne peuvent pas accéder au DOM, aux cookies ni au stockage de la page parente. L'hôte contrôle toutes les communications avec l'application invitée.

Étapes suivantes

• Utiliser des Tools avec des Agents
• Référence de MCPClient
• Référence de MCPServer
• Spécification de l'extension MCP Apps