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

# Vue d'ensemble de MCP

Mastra prend en charge le [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), un standard ouvert permettant de connecter des Agents d'IA à des Tools et ressources externes.

Utilisez [`MCPClient`](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) pour vous connecter aux serveurs MCP. Utilisez [`MCPServer`](https://mastra.zisheng.pro/fr/reference/tools/mcp-server) 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**:

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

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

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

> **Authentification:** Pour les serveurs protégés par OAuth, utilisez `authenticate()` afin de terminer le processus d'autorisation dans le navigateur. Consultez [Authentification OAuth](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) pour connaître les détails de configuration.

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

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

### 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 :

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

Consultez [`listTools()`](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) et [`listToolsets()`](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) pour découvrir leurs API complètes.

### Approbation des Tools

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

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

```typescript
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](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) 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](https://mastra.zisheng.pro/fr/docs/agents/processors) 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](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) 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](https://klavis.ai)                  | HTTP hébergé        | Authentification d'entreprise et serveurs gérés         |
| [mcp.run](https://www.mcp.run/)                 | URL SSE signée      | Considérez l'URL du profil comme un secret              |
| [Composio](https://mcp.composio.dev)            | URL SSE hébergée    | Les URL sont souvent liées à un seul compte utilisateur |
| [Smithery](https://smithery.ai)                 | CLI ou URL hébergée | Exécutez les packages locaux avec `npx`                 |
| [Apify](https://mcp.apify.com)                  | HTTP hébergé        | Authentifiez-vous avec un token d'API Apify             |
| [Ampersand](https://docs.withampersand.com/mcp) | 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 :

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

Enregistrez le serveur sur l'instance `Mastra` principale :

```typescript
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](https://mastra.zisheng.pro/fr/reference/tools/mcp-server) pour connaître les instructions de configuration.

Consultez la [référence de `MCPServer`](https://mastra.zisheng.pro/fr/reference/tools/mcp-server) pour les prompts, les ressources, les transports et les autres options du serveur.

## Créer des MCP Apps

L'[extension MCP Apps](https://github.com/modelcontextprotocol/ext-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` :

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

Le modèle voit `content`, tandis que l'application reçoit `structuredContent`. Consultez [`appResources`](https://mastra.zisheng.pro/fr/reference/tools/mcp-server) 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()` :

```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`](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) 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` :

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

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 :

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

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()`](https://mastra.zisheng.pro/fr/reference/tools/mcp-client) pour connaître les détails de configuration du proxy.

### Sécurité du Sandbox

Mastra Studio utilise [`@mcp-ui/client`](https://www.npmjs.com/package/@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](https://mastra.zisheng.pro/fr/docs/agents/using-tools)
- [Référence de `MCPClient`](https://mastra.zisheng.pro/fr/reference/tools/mcp-client)
- [Référence de `MCPServer`](https://mastra.zisheng.pro/fr/reference/tools/mcp-server)
- [Spécification de l'extension MCP Apps](https://github.com/modelcontextprotocol/ext-apps)