Connecteur MCP

La fonctionnalité de connecteur « Model Context Protocol », ou MCP, de Claude vous permet de vous connecter à des serveurs MCP distants directement depuis l'API Messages sans client MCP distinct.



Fonctionnalités clés

• Intégration API directe : Connectez-vous aux serveurs MCP sans implémenter de client MCP
• Prise en charge des appels d'outils : Accédez aux outils MCP via l'API Messages
• Configuration flexible des outils : Activez tous les outils, autorisez des outils spécifiques via une liste d'autorisation, ou excluez des outils indésirables via une liste de refus
• Configuration par outil : Configurez des outils individuels avec des paramètres personnalisés
• Authentification OAuth : Prise en charge des jetons OAuth Bearer pour les serveurs authentifiés
• Serveurs multiples : Connectez-vous à plusieurs serveurs MCP dans une seule requête



Quand Claude utilise les outils MCP

Une fois qu'un serveur MCP est connecté, Claude appelle ses outils lorsque la requête de l'utilisateur correspond à une capacité décrite d'un outil, que ce soit explicitement (« recherche les bugs ouverts dans Jira ») ou implicitement (« qu'est-ce qui bloque la release ? » avec un serveur Jira attaché).

Claude n'appelle pas d'outil MCP pour des questions de connaissances générales concernant un service connecté. Demander « comment fonctionnent les bases de données Notion ? » avec un serveur Notion attaché reçoit une réponse directe ; demander « qu'y a-t-il dans ma base de données Projects ? » déclenche l'outil.

Vous pouvez orienter la propension de Claude à appeler les outils MCP via votre invite système. Consultez Quand Claude utilise les outils pour des conseils généraux et des exemples de formulations.



Limitations

• Parmi l'ensemble des fonctionnalités de la spécification MCP, seuls les appels d'outils sont actuellement pris en charge.
• Le serveur doit être exposé publiquement via HTTP (prend en charge les transports Streamable HTTP et SSE). Les serveurs STDIO locaux ne peuvent pas être connectés directement.
• Le connecteur MCP est disponible sur l'API Claude, Claude Platform sur AWS et Microsoft Foundry. Il n'est actuellement pas disponible sur Amazon Bedrock ni Vertex AI.



Utilisation du connecteur MCP dans l'API Messages

Le connecteur MCP utilise deux composants :

1. Définition de serveur MCP (tableau mcp_servers) : Définit les détails de connexion au serveur (URL, authentification)
2. MCP Toolset (tableau tools) : Configure quels outils activer et comment les configurer



Exemple de base

Cet exemple active tous les outils d'un serveur MCP avec la configuration par défaut :

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)



Configuration du serveur MCP

Chaque serveur MCP dans le tableau mcp_servers définit les détails de connexion :

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}



Description des champs



Configuration du MCP Toolset

Le MCPToolset se trouve dans le tableau tools et configure quels outils du serveur MCP sont activés et comment ils doivent être configurés.



Structure de base

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}



Description des champs



Options de configuration des outils

Chaque outil (qu'il soit configuré dans default_config ou dans configs) prend en charge les champs suivants :

Pour le répertoire complet des outils fournis par Anthropic et les propriétés optionnelles telles que defer_loading, consultez la Référence des outils. Pour effectuer des recherches dans de grands ensembles d'outils, consultez l'outil de recherche d'outils.



Fusion des configurations

Les valeurs de configuration fusionnent selon cet ordre de priorité (de la plus haute à la plus basse) :

1. Paramètres spécifiques à l'outil dans configs
2. default_config au niveau de l'ensemble
3. Valeurs par défaut du système

Exemple :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Résultat :

• search_events : enabled: false (depuis configs), defer_loading: true (depuis default_config)
• Tous les autres outils : enabled: true (valeur par défaut du système), defer_loading: true (depuis default_config)



Modèles de configuration courants



Activer tous les outils avec la configuration par défaut

Le modèle le plus simple — activer tous les outils d'un serveur :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}



Liste d'autorisation : activer uniquement des outils spécifiques

Définissez enabled: false comme valeur par défaut, puis activez explicitement des outils spécifiques :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}



Liste de refus : désactiver des outils spécifiques

Activez tous les outils par défaut, puis désactivez explicitement les outils indésirables. Il est recommandé de placer les outils d'écriture ou destructifs sur une liste de refus lors de la création d'assistants en lecture seule, ou lorsque vous souhaitez une étape de confirmation humaine avant les changements d'état :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}



Mixte : liste d'autorisation avec configuration par outil

Combinez la liste d'autorisation avec une configuration personnalisée pour chaque outil :

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

Dans cet exemple :

• search_events est activé avec defer_loading: false
• list_events est activé avec defer_loading: true (hérité de default_config)
• Tous les autres outils sont désactivés



Règles de validation

L'API applique ces règles de validation :

• Le serveur doit exister : Le mcp_server_name dans un MCPToolset doit correspondre à un serveur défini dans le tableau mcp_servers
• Le serveur doit être utilisé : Chaque serveur MCP défini dans mcp_servers doit être référencé par exactement un MCPToolset
• Toolset unique par serveur : Chaque serveur MCP ne peut être référencé que par un seul MCPToolset
• Noms d'outils inconnus : Si un nom d'outil dans configs n'existe pas sur le serveur MCP, un avertissement backend est enregistré mais aucune erreur n'est renvoyée (les serveurs MCP peuvent avoir une disponibilité d'outils dynamique)



Types de contenu de réponse

Lorsque Claude utilise des outils MCP, la réponse inclut deux nouveaux types de blocs de contenu :



Bloc d'utilisation d'outil MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}



Bloc de résultat d'outil MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}



Serveurs MCP multiples

Vous pouvez vous connecter à plusieurs serveurs MCP en incluant plusieurs définitions de serveur dans mcp_servers et un MCPToolset correspondant pour chacun dans le tableau tools :

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Avec de nombreux outils disponibles, Claude effectue sa sélection en fonction des noms et descriptions des outils. Des descriptions d'outils claires et spécifiques améliorent la précision de la sélection. Pour les grands ensembles d'outils (des dizaines d'outils répartis sur plusieurs serveurs), envisagez d'activer defer_loading avec l'outil de recherche d'outils afin que seuls les outils pertinents soient présentés pour chaque requête.



Authentification

Pour les serveurs MCP qui nécessitent une authentification OAuth, vous devrez obtenir un jeton d'accès. La bêta du connecteur MCP prend en charge le passage d'un paramètre authorization_token dans la définition du serveur MCP. Les consommateurs de l'API doivent gérer le flux OAuth et obtenir le jeton d'accès avant d'effectuer l'appel API, et actualiser le jeton si nécessaire.



Obtention d'un jeton d'accès pour les tests

L'inspecteur MCP peut vous guider dans le processus d'obtention d'un jeton d'accès à des fins de test.

1. Exécutez l'inspecteur avec la commande suivante. Node.js doit être installé sur votre machine.

   npx @modelcontextprotocol/inspector

   

2. Dans la barre latérale de gauche, pour « Transport type », sélectionnez « SSE » ou « Streamable HTTP ».

3. Saisissez l'URL du serveur MCP.

4. Dans la zone de droite, cliquez sur le bouton « Open Auth Settings » après « Need to configure authentication? ».

5. Cliquez sur « Quick OAuth Flow » et autorisez sur l'écran OAuth.

6. Suivez les étapes de la section « OAuth Flow Progress » de l'inspecteur et cliquez sur « Continue » jusqu'à atteindre « Authentication complete ».

7. Copiez la valeur access_token.

8. Collez-la dans le champ authorization_token de votre configuration de serveur MCP.



Utilisation du jeton d'accès

Une fois que vous avez obtenu un jeton d'accès à l'aide de l'un des flux OAuth précédents, vous pouvez l'utiliser dans votre configuration de serveur MCP :

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Pour des explications détaillées sur le flux OAuth, consultez la section Authorization de la spécification MCP.



Fonctions d'aide MCP côté client

Si vous gérez votre propre connexion client MCP (par exemple, avec des serveurs stdio locaux, des prompts MCP ou des ressources MCP), les SDK fournissent des fonctions d'aide qui effectuent la conversion entre les types MCP et les types de l'API Claude. Cela élimine le code de conversion manuel lors de l'utilisation d'un SDK MCP (tel que le SDK MCP TypeScript) conjointement avec le SDK Anthropic.



Installation

Installez à la fois le SDK Anthropic et le SDK MCP :

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk



Fonctions d'aide disponibles

Importez les fonctions d'aide depuis l'espace de noms bêta :

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";



Utiliser les outils MCP

Convertissez les outils MCP pour une utilisation avec le tool runner du SDK, qui gère automatiquement l'exécution des outils :

import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Se connecter à un serveur MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Lister les outils et les convertir pour l'API Claude
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);



Utiliser les prompts MCP

Convertissez les messages de prompt MCP au format de message de l'API Claude :

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);



Utiliser les ressources MCP

Convertissez les ressources MCP en blocs de contenu à inclure dans les messages, ou en objets fichier pour le téléversement :

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// En tant que bloc de contenu dans un message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// En tant que fichier téléversé
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });



Gestion des erreurs

Les fonctions de conversion lèvent une erreur UnsupportedMCPValueError si une valeur MCP n'est pas prise en charge par l'API Claude. Cela peut se produire avec des types de contenu non pris en charge, des types MIME non pris en charge ou des liens de ressources non HTTP.



Requêtes par lots

Vous pouvez inclure mcp_servers dans les requêtes de l'API Message Batches. Les appels d'outils MCP via l'API Batches sont facturés au même tarif que ceux des requêtes régulières de l'API Messages.



Conservation des données

Le connecteur MCP n'est pas couvert par les accords ZDR. Les données échangées avec les serveurs MCP, y compris les définitions d'outils et les résultats d'exécution, sont conservées conformément à la politique standard de conservation des données d'Anthropic.

Pour l'éligibilité ZDR de toutes les fonctionnalités, consultez API et conservation des données.



Guide de migration

Si vous utilisez l'en-tête bêta obsolète mcp-client-2025-04-04, suivez ce guide pour migrer vers la nouvelle version.



Changements clés

1. Nouvel en-tête bêta : Passez de mcp-client-2025-04-04 à mcp-client-2025-11-20
2. Configuration des outils déplacée : La configuration des outils se trouve désormais dans le tableau tools sous forme d'objets MCPToolset, et non dans la définition du serveur MCP
3. Configuration plus flexible : Le nouveau modèle prend en charge les listes d'autorisation, les listes de refus et la configuration par outil



Étapes de migration

Avant (obsolète) :

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Après (actuel) :

{
  "model": "claude-opus-4-8",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}



Modèles de migration courants



Version obsolète : mcp-client-2025-04-04

La version précédente du connecteur MCP incluait la configuration des outils directement dans la définition du serveur MCP :

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}



Description des champs obsolètes