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 séparé.

Fonctionnalités clés

• Intégration directe à l'API : connectez-vous à des serveurs MCP sans implémenter de client MCP
• Prise en charge de l'appel d'outils : accédez aux outils MCP via l'API Messages
• Configuration flexible des outils : activez tous les outils, autorisez des outils spécifiques (allowlist) ou bloquez les outils indésirables (denylist)
• Configuration par outil : configurez des outils individuels avec des paramètres personnalisés
• Authentification OAuth : prise en charge des jetons Bearer OAuth 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 à la capacité décrite d'un outil, soit explicitement (« recherche les bugs ouverts dans Jira »), soit implicitement (« qu'est-ce qui bloque la publication ? » avec un serveur Jira attaché).

Claude n'appelle pas un outil MCP pour des questions de connaissances générales sur un service connecté. Demander « comment fonctionnent les bases de données Notion ? » avec un serveur Notion attaché reçoit une réponse directe ; demander « que contient ma base de données Projets ? » 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.

Utilisation du connecteur MCP dans l'API Messages

Le connecteur MCP utilise deux composants :

1. Définition du serveur MCP (tableau mcp_servers) : définit les détails de connexion au serveur (URL, authentification)
2. Ensemble d'outils MCP (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-5-5",
    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 de l'ensemble d'outils MCP

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

Avec l'en-tête bêta mcp-client-2026-09-15, un MCPToolset accepte également tools, une copie épinglée de la liste d'outils du serveur. Consultez Épingler la liste d'outils d'un serveur MCP.

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 des 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é (du plus élevé au plus bas) :

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

Allowlist : 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
    }
  }
}

Denylist : 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 bloquer les outils d'écriture ou destructifs 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 : allowlist avec configuration par outil

Combinez l'allowlist 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
• Ensemble d'outils 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 est consigné côté backend 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"
    }
  ]
}

Épingler la liste d'outils d'un serveur MCP (bêta)

Un serveur MCP peut modifier ses outils à tout moment. L'en-tête bêta mcp-client-2026-09-15 enregistre la liste d'outils renvoyée par chaque serveur et vous permet de l'épingler, de sorte qu'un serveur qui modifie ses outils ne change pas ce que Claude voit en cours de conversation. Il inclut tout ce que fait mcp-client-2025-11-20 ; envoyez-le donc à la place de cet en-tête. Il est disponible sur l'API Claude.

Lorsque l'API demande ses outils à un serveur MCP pendant la production d'une réponse, la réponse commence par un bloc mcp_tool_listing pour ce serveur, un bloc pour chaque serveur interrogé :

{
  "type": "mcp_tool_listing",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Si votre code lit content[0], ignorez ces blocs. Renvoyez le message de l'assistant sans modification, blocs mcp_tool_listing compris, et continuez à envoyer mcp-client-2026-09-15 dans chaque requête qui en contient un. Les requêtes suivantes utilisent alors la liste enregistrée pour ce serveur au lieu de l'interroger à nouveau.

Pour épingler vous-même une liste, copiez le champ tools d'un bloc dans le champ tools du MCPToolset de ce serveur. L'API ne demande alors plus ses outils au serveur, et les outils de l'ensemble sont exactement ces entrées, avec default_config et configs appliqués :

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Chaque entrée de tools contient le name de l'outil tel que le serveur le liste (sans le nom du serveur), sa description et son input_schema.

L'exemple suivant envoie une requête avec un ensemble d'outils non épinglé, copie la liste renvoyée dans le champ tools de l'ensemble d'outils, puis envoie à nouveau la requête. La seconde réponse ne contient aucun bloc mcp_tool_listing, car l'API n'interroge pas le serveur :

from anthropic.types.beta import (
    BetaMessageParam,
    BetaRequestMCPServerURLDefinitionParam,
)

client = anthropic.Anthropic()

mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN",
    },
]
messages: list[BetaMessageParam] = [
    {"role": "user", "content": "What tools do you have available?"},
]

# Première requête : le toolset n'est pas épinglé, donc l'API demande au serveur
# ses outils et la réponse commence par un bloc mcp_tool_listing.
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])

# Épinglez la liste : copiez les outils du bloc dans le toolset. L'API utilise
# exactement ces entrées et n'interroge plus le serveur.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# Avec un toolset épinglé, la réponse ne contient aucun bloc mcp_tool_listing.
print([block.type for block in second.content])

Si vous utilisez également l'en-tête bêta inline-tools-2026-09-15, vous pouvez ajouter un serveur MCP en cours de conversation. Consultez Ajouter un serveur MCP en cours de conversation.

Serveurs MCP multiples

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

{
  "model": "claude-opus-5-5",
  "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
      }
    }
  ]
}

Lorsque de nombreux outils sont 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 la transmission d'un paramètre authorization_token dans la définition du serveur MCP. Les consommateurs de l'API sont censés gérer le flux OAuth et obtenir le jeton d'accès avant d'effectuer l'appel API, ainsi que rafraîchir le jeton si nécessaire.

Obtenir 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 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, reportez-vous à la section Authorization de la spécification MCP.

Assistants 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'assistance qui convertissent 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 pour votre langage (par exemple, le SDK MCP TypeScript) aux côtés du SDK Anthropic.

Installation

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

pip install "anthropic[mcp]"

Assistants disponibles

Importez les assistants pour votre langage :

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

Les noms des assistants et leurs signatures exactes suivent les conventions de chaque langage ; ce tableau présente les formes TypeScript :

Utiliser les outils MCP

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

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Se connecter à un serveur MCP
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Lister les outils et les convertir pour l'API Claude
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

Utiliser les prompts MCP

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

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(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 :

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# En tant que bloc de contenu dans un message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# En tant que téléversement de fichier
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

Gestion des erreurs

Les fonctions de conversion échouent avec UnsupportedMCPValueError si une valeur MCP n'est pas prise en charge par l'API Claude (levée comme exception, ou renvoyée comme erreur en Go). Cela peut se produire avec des types de contenu, des types MIME ou des liens de ressources non pris en charge (résolvez les liens de ressources avec votre client MCP avant la conversion).

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 classiques 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 déprécié 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 l'allowlist, la denylist et la configuration par outil

Étapes de migration

Avant (déprécié) :

{
  "model": "claude-opus-5-5",
  "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-5-5",
  "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 dépréciée : 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 dépréciés

Compatibility