MCP et connexion aux outils

Avancé

Le Model Context Protocol (MCP) est le standard ouvert pour connecter l'IA à des outils et données externes. Sur l'API, vous n'avez pas besoin d'exécuter vous-même un client MCP : le connecteur MCP vous permet de nommer un serveur distant dans votre requête et Claude appelle ses outils au sein de la boucle d'agent normale. Deux champs de requête remplacent toute une couche d'intégration.

What you'll learn

Quand le connecteur MCP bat la définition manuelle des outils — et quand non
La forme exacte de la requête : mcp_servers pour la connexion, mcp_toolset pour la politique
Allowlist, denylist et configuration par outil — et comment les trois couches de config fusionnent
Les blocs de réponse que vous devez gérer : mcp_tool_use et mcp_tool_result
Les vraies limites : HTTPS uniquement, outils uniquement, lacunes de plateforme, et pas de couverture ZDR

MCP vs outils définis à la main

	Utilisation des outils (personnalisée)	Connecteur MCP
Vous définissez	Le schéma de chaque outil, et vous l'exécutez	Une connexion à un serveur qui publie des outils
Qui exécute l'outil	Votre code, dans votre boucle	Le côté Anthropic appelle le serveur distant
Idéal pour	Quelques fonctions sur mesure dans votre application	Réutiliser des intégrations existantes (GitHub, BD, navigateurs, SaaS)
Authentification	Votre code	Un jeton OAuth Bearer que vous fournissez par serveur

Ils coexistent. Définissez directement vos outils propres à l'application, et intégrez des capacités prêtes à l'emploi via MCP.

La forme de la requête

Deux morceaux, délibérément séparés : mcp_servers dit où se trouve le serveur et comment s'authentifier ; l'entrée mcp_toolset dans le tableau tools dit lesquels de ses outils vous êtes prêt à exposer et comment.

Guided walkthrough1 of 4

anthropic-beta: mcp-client-2025-11-20 — sans lui, le champ mcp_servers n'est pas accepté. Dans les SDK, c'est la liste betas sur un appel beta.messages.create.

Appel minimal du connecteur MCP (cURL)

curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
  "model": "MODEL_ID",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "What tools do you have available?"}],
  "mcp_servers": [
    {"type": "url", "url": "https://example.com/sse", "name": "example-mcp", "authorization_token": "YOUR_TOKEN"}
  ],
  "tools": [
    {"type": "mcp_toolset", "mcp_server_name": "example-mcp"}
  ]
}'

:::tip Ne codez jamais le modèle en dur MODEL_ID ci-dessus est un placeholder à dessein. Lisez l'ID actuel depuis Modèles et tarification actuels et gardez-le en configuration, pour qu'une mise à niveau de modèle soit un changement d'une ligne. :::

L'API impose un appariement strict : chaque serveur de mcp_servers doit être référencé par exactement un toolset, et le mcp_server_name de chaque toolset doit correspondre à un serveur déclaré. Les incohérences sont des erreurs de validation, pas des no-ops silencieux.

Choisir ce que Claude peut réellement faire

C'est la partie que la plupart des intégrations ratent. Un toolset prend un default_config appliqué à chaque outil, plus des configs avec des overrides par outil. Précédence, du plus fort au plus faible : configs par outil → default_config du set → défauts du système.

Denylist — activez tout, puis désactivez les dangereux. Raisonnable quand vous voulez de la largeur mais pas d'écritures destructives :

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

Allowlist — désactivez par défaut, puis nommez les survivants. C'est la posture du moindre privilège, celle à privilégier par défaut :

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

:::warning Une denylist ne bloque que ce que vous avez pensé Les serveurs peuvent ajouter des outils. Une denylist accorde silencieusement chaque outil livré après votre écriture ; une allowlist les ignore silencieusement. Pour tout ce qui touche des données clients ou de l'argent, allowlist. Notez aussi que nommer dans configs un outil qui n'existe pas sur le serveur journalise un avertissement backend mais n'erreure pas — donc une faute de frappe dans une allowlist désactive silencieusement l'outil que vous vouliez activer. Vérifiez contre la liste vivante des outils du serveur. :::

Gardez les schémas hors de votre contexte

La description de chaque outil activé est envoyée avec la requête, donc un gros catalogue taxe chaque tour. La réponse du connecteur est defer_loading: true : la description reste hors du contexte initial, et Claude la tire à la demande via le Tool Search Tool.

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

Lisez cela comme : différer tout sauf l'outil par lequel cette tâche commence. Un toolset accepte aussi cache_control, de sorte qu'un catalogue stable peut s'installer derrière un point de rupture de cache de prompts au lieu d'être refacturé à chaque tour. Pour les chiffres derrière cela — et pourquoi le différement des outils a amélioré la précision de sélection au lieu de la baisser — voir La taxe MCP sur les tokens. Quand ce sont les résultats plutôt que les définitions qui inondent votre contexte, tournez-vous plutôt vers l'Appel d'outils programmatique.

Ce qui revient

Deux types de blocs de contenu que vous devez gérer :

{ "type": "mcp_tool_use", "id": "mcptoolu_...", "name": "echo",
  "server_name": "example-mcp", "input": { "param1": "value1" } }

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

Notez server_name sur le bloc d'utilisation : avec plusieurs serveurs connectés, c'est ainsi que vous attribuez un appel — essentiel pour la journalisation et pour déboguer quelle intégration s'est mal comportée. Et is_error est un champ, pas une exception : un outil MCP en échec revient comme un résultat, donc votre boucle doit l'inspecter plutôt que présumer le succès.

Les limites qui piquent

Watch out

Outils uniquement. De la spécification MCP, le connecteur ne supporte actuellement que les appels d'outils — pas les prompts ni les ressources. Besoin de ceux-ci ? Exécutez votre propre client et utilisez les helpers MCP du SDK.
HTTPS distant uniquement. Le serveur doit être accessible publiquement via HTTP (transports Streamable HTTP ou SSE). Un serveur stdio local ne peut pas être connecté ainsi — c'est ce que font Claude Code et les applications de bureau.
Lacunes de plateforme. Disponible sur l'API Claude, la Claude Platform sur AWS et Microsoft Foundry (déploiements Hosted-on-Anthropic). Pas actuellement sur Amazon Bedrock ni Google Cloud.
Pas de zéro rétention de données. Les données échangées avec les serveurs MCP — définitions d'outils et résultats d'exécution — relèvent de la rétention standard, pas de ZDR.
Vous portez l'OAuth. L'API prend un authorization_token ; l'obtenir et le rafraîchir avant expiration est votre travail.

Un même standard, trois surfaces

API (cette page) — serveurs distants par URL, via le connecteur.
Claude Code — serveurs locaux et distants dans vos sessions de développement.
Les applications — MCP alimente les Connecteurs.

Apprenez le protocole une fois ; il se transpose. Seul le câblage diffère.

Confiance

:::warning Un serveur MCP, c'est du code plus des accès Ne connectez que des serveurs auxquels vous faites confiance, restreignez-les au moindre privilège avec une allowlist, et rappelez-vous que le contenu qu'un serveur renvoie est une entrée non fiable pouvant véhiculer de l'injection de prompt. Examinez les serveurs tiers avant de les câbler — Examiner le code tiers et Sécuriser les serveurs MCP. :::

Vocabulaire du connecteur MCP

Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.

1 / 6

Vérifiez-vous

0/4

Vous voulez que Claude n'utilise que search_events et create_event depuis un serveur calendrier. Quelle est la forme correcte du toolset ?
Un appel d'outil MCP échoue. Où cela apparaît-il ?
Vous avez besoin que Claude lise des ressources MCP depuis un serveur stdio local. Le connecteur peut-il le faire ?
Votre catalogue d'outils s'étend sur quatre serveurs et domine la fenêtre de contexte à chaque tour. Le premier geste le moins cher ?

Key takeaways

Le connecteur remplace un client MCP par deux champs de requête — mais seulement pour des serveurs HTTPS distants, et seulement pour les appels d'outils.
mcp_servers est la connexion ; le mcp_toolset dans tools est la politique. Chaque serveur doit s'apparier avec exactement un toolset.
Allowlist (default_config.enabled false, plus configs explicites) bat denylist : les outils ajoutés au serveur plus tard sont ignorés, pas accordés.
defer_loading et cache_control sont vos leviers quand les schémas d'outils commencent à manger la fenêtre de contexte.
Gérez les blocs mcp_tool_use et mcp_tool_result — y compris is_error, qui est un champ, pas une exception.
Vérifiez l'en-tête beta avant de déployer : mcp-client-2025-11-20 est actuel, mcp-client-2025-04-04 est déprécié.

Sources et lectures complémentaires

Connecteur MCP — docs Anthropic — la référence de champs faisant autorité et le guide de migration.
Spécification du Model Context Protocol — le standard ouvert lui-même, y compris l'autorisation.

MCP vs outils définis à la main​

La forme de la requête​

Appel minimal du connecteur MCP (cURL)

Choisir ce que Claude peut réellement faire​

Gardez les schémas hors de votre contexte​

Ce qui revient​

Les limites qui piquent​

Un même standard, trois surfaces​

Confiance​