D5 · Tools and MCPs

Ce domaine représente environ 5 items sur 53. Il vérifie que vous savez bien définir des outils (la description est le levier le plus important), exécuter correctement le cycle de vie de l’utilisation d’outils, choisir entre outils côté client et côté serveur, et comprendre et écrire des serveurs MCP. Le thème : les outils sont la façon dont Claude agit sur le monde – décrivez-les précisément et connectez-les en toute sécurité.

Objectifs d’apprentissage

À la fin de cette page, vous devriez être capable de :

1. Exécuter le cycle de vie utilisation d’outils / function-calling avec un JSON correct.
2. Écrire des descriptions d’outils efficaces et concevoir l’input_schema.
3. Utiliser tool_choice (auto/any/tool/none) et connaître la restriction Fable 5.1.
4. Utiliser les appels d’outils parallèles et distinguer les outils côté client vs côté serveur.
5. Utiliser tool search + defer_loading, l’appel d’outils programmatique, et les patterns d’approbation.
6. Expliquer les fondamentaux MCP et écrire un serveur MCP en Python (FastMCP) et TypeScript.
7. Configurer MCP dans Claude Code / Desktop et via le connecteur MCP dans la Messages API.

5.1 The tool-use lifecycle

{
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city. Use when the user asks about weather, temperature, or conditions in a named location.",
    "input_schema": {
      "type": "object",
      "properties": {
        "city": {"type": "string", "description": "City name, e.g. 'Paris'"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
      },
      "required": ["city"]
    }
  }]
}

{
  "stop_reason": "tool_use",
  "content": [
    {"type": "text", "text": "Let me check the weather."},
    {"type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": {"city": "Paris"}}
  ]
}

{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01", "content": "18C, partly cloudy"}
  ]
}

Les erreurs sont renvoyées avec "is_error": true dans le tool_result pour que Claude puisse récupérer.

A complete round-trip on the wire

Les quatre Tabs ci-dessus sont les quatre messages sur le fil d’un aller-retour. Lisez-les comme une seule conversation pour que le chaînage du tool_use_id soit sans équivoque. La requête déclare les outils ; Claude répond avec stop_reason: 'tool_use' ; vous exécutez la fonction et envoyez un tool_result référençant le même id ; Claude produit la réponse end_turn.

import anthropic
client = anthropic.Anthropic()

TOOLS = [{
    "name": "get_weather",
    "description": "Get current weather for a city. Use when the user asks about "
                   "weather, temperature, or conditions in a named location. "
                   "Returns a short text summary. Read-only, no side effects.",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name, e.g. 'Paris'"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
        },
        "required": ["city"],
    },
}]

messages = [{"role": "user", "content": "What's the weather in Paris?"}]

# 1. Tour du modèle -> Claude demande l'outil
resp = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024, tools=TOOLS, messages=messages,
)
assert resp.stop_reason == "tool_use"          # NE JAMAIS parser le texte pour décider cela
messages.append({"role": "assistant", "content": resp.content})

# 2. Vous exécutez l'outil pour chaque bloc tool_use
for block in resp.content:
    if block.type == "tool_use":
        result = fetch_weather(**block.input)   # votre vraie fonction
        messages.append({"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": block.id,            # DOIT correspondre à l'id d'origine
            "content": result,
        }]})

# 3. Tour du modèle à nouveau -> Claude donne la réponse finale
final = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024, tools=TOOLS, messages=messages,
)
assert final.stop_reason == "end_turn"
print(final.content[0].text)

5.2 Tool descriptions – the most important lever

La description est le principal déterminant de savoir si Claude utilise un outil correctement. Investissez ici plus que partout ailleurs. Une bonne description se lit comme la docstring que vous écririez pour un collègue qui n’a jamais vu la fonction.

Good vs bad tool descriptions – four pairs

Chaque bonne description répond à quatre questions : ce qu’elle fait, quand l’utiliser (et quand non), ce qu’elle renvoie, et quels effets de bord / quelle irréversibilité elle comporte.

5.3 input_schema design checklist

Le schéma est du JSON Schema. Il contraint ce que Claude peut passer et, avec strict: true, garantit la forme. Concevez-le délibérément.

• Types — donnez un type à chaque propriété. Utilisez le type le plus étroit (integer plutôt que number quand c’est entier).
• Enums — contraignez les ensembles fermés avec enum pour que Claude ne puisse pas inventer une valeur : {"type": "string", "enum": ["celsius", "fahrenheit"]}.
• required — listez chaque argument dont l’outil a réellement besoin. Les arguments requis-mais-omis sont une cause majeure d’appels malformés.
• Descriptions par propriété — décrivez chaque champ, avec un exemple. Claude les lit.
• Nullable / optionnel — les params optionnels sont simplement absents de required ; pour autoriser un null explicite, utilisez {"type": ["string", "null"]}.
• Bornes et formats — minimum, maximum, pattern, format: 'date' réduisent les entrées de mauvaise qualité.
• strict: true — activez le respect strict du schéma pour que les sorties soient exactement conformes (aussi un moyen d’obtenir un comportement structuré sur Fable 5.1 où les outils forcés font 400).

{
  "name": "create_ticket",
  "description": "Open a support ticket. Use only after the user confirms they want one.",
  "input_schema": {
    "type": "object",
    "properties": {
      "priority": {"type": "string", "enum": ["low", "normal", "high", "urgent"],
                   "description": "Urgency; default to 'normal' unless the user signals otherwise"},
      "summary":  {"type": "string", "description": "One-line summary, e.g. 'Cannot log in'"},
      "due_date": {"type": ["string", "null"], "format": "date",
                   "description": "ISO date, or null if none"}
    },
    "required": ["priority", "summary"]
  },
  "strict": true
}

5.5 tool_choice

5.6 Parallel tool calls

Quand les sous-tâches sont indépendantes, Claude peut émettre plusieurs blocs tool_use dans une seule réponse. Exécutez-les en concurrence et renvoyez tous les blocs tool_result dans le message user suivant (en faisant correspondre chaque tool_use_id). Si les appels sont dépendants (le résultat de l’un alimente le suivant), Claude les sérialisera plutôt entre les tours.

tool_uses = [b for b in resp.content if b.type == "tool_use"]
results = run_concurrently(tool_uses)     # outils indépendants en parallèle
messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": u.id, "content": r}
    for u, r in zip(tool_uses, results)]})   # TOUS les résultats dans UN tour user

5.7 Client-side vs server-side tools

Les outils côté serveur sont activés en les déclarant ; Anthropic les exécute et peut mettre le tour en pause (pause_turn) pendant l’exécution.

Server-side built-in tools

5.8 Tool search, defer_loading and programmatic calling

• Au-delà de ~10 outils, utilisez le tool search tool avec defer_loading: true pour que les définitions complètes d’outils soient chargées à la demande plutôt que toutes en amont — réduit le gonflement du contexte et la sélection du mauvais outil (anti-pattern nº 8).
• L’appel d’outils programmatique permet au code d’invoquer les outils directement dans une boucle contrôlée.
• Patterns d’approbation : exiger une approbation humaine/par hook avant les actions d’outils irréversibles (voir hooks, Domaines 3 et 6).

# Grand catalogue : différer les définitions complètes, exposer l'outil de recherche.
tools = [
    {"type": "tool_search_tool_20250000", "name": "tool_search"},  # laisse Claude trouver des outils à la demande
    {"name": "get_order",     "description": "...", "input_schema": {...}, "defer_loading": True},
    {"name": "issue_refund",  "description": "...", "input_schema": {...}, "defer_loading": True},
    # ...50 autres outils différés ; seuls ceux que Claude recherche sont hydratés dans le contexte
]
resp = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                              tools=tools, messages=messages)

Le pattern garde l’ensemble d’outils actifs restreint (4–5 dans le contexte à la fois) même quand le catalogue est grand, ce qui est exactement le correctif de l’anti-pattern nº 8.

5.9 MCP fundamentals

Le Model Context Protocol est un standard ouvert (JSON-RPC 2.0) pour connecter Claude à des outils et données externes.

• Transports : stdio (sous-processus local) et Streamable HTTP (distant ; SSE est hérité).
• La négociation des capacités a lieu à initialize.
• OAuth 2.1 sécurise les serveurs distants.

Host (Claude Desktop / Code)
   │  JSON-RPC 2.0
   ├── stdio ──► local MCP server (subprocess)
   └── Streamable HTTP ──► remote MCP server (OAuth 2.1)

5.10 Authoring an MCP server

Un serveur minimal mais complet : il se nomme, déclare un outil avec un schéma typé et une description en docstring, gère ses propres erreurs, et s’exécute sur stdio. Les deux SDK ci-dessous sont exécutables tels quels.

# weather_server.py — run: python weather_server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get current weather for a city.

    Use when the user asks about weather, temperature or conditions in a
    named location. Returns a short text summary. Read-only, no side effects.
    """
    if not city:
        raise ValueError("city is required")
    return fetch_weather(city, unit)

@mcp.resource("config://units")
def default_units() -> str:
    """Application-controlled resource: the default unit system."""
    return "celsius"

if __name__ == "__main__":
    mcp.run()   # transport stdio par défaut ; utiliser mcp.run(transport='streamable-http') pour le distant

// weather_server.ts — run: node weather_server.js
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'weather', version: '1.0.0' });

server.tool(
  'get_weather',
  'Get current weather for a city. Use when asked about weather in a named location. Read-only.',
  { city: z.string().describe('City name, e.g. Paris'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius') },
  async ({ city, unit }) => {
    if (!city) throw new Error('city is required');
    return { content: [{ type: 'text', text: await fetchWeather(city, unit) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);   // pour le distant : StreamableHTTPServerTransport

5.11 Configuring MCP

# stdio (sous-processus local)
claude mcp add weather --scope project -- python weather_server.py

# HTTP (serveur distant)
claude mcp add --transport http docs https://mcp.example.com/mcp --scope user

# list / remove
claude mcp list
claude mcp remove weather

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["weather_server.py"],
      "env": { "WEATHER_API_KEY": "${WEATHER_API_KEY}" }
    },
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}

resp = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Search the docs for retry policy."}],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/mcp",
        "name": "docs",
        "authorization_token": "Bearer …",   # token OAuth 2.1 pour le serveur distant
    }],
    betas=["mcp-client-2025-04-04"],
)

5.12 MCP vs custom tool vs Skill – decision table

Ces trois façons d’étendre Claude sont fréquemment confondues à l’examen.

Règle générale : une app, quelques fonctions → custom tools ; réutilisation entre hosts/équipes → MCP ; savoir-faire empaqueté et scripts d’aide pour Claude Code → Skill.

5.13 MCP transports, capability negotiation and OAuth 2.1

Les détails « sur le fil » de MCP reviennent dans les items d’examen. MCP est du JSON-RPC 2.0 ; un host et un serveur négocient les capacités à initialize, puis échangent des appels tool/resource/prompt sur un transport.

Host ──initialize──► Server         (capability negotiation: tools? resources? prompts?)
Host ◄─capabilities─ Server
Host ──tools/list───► Server         (discover model-controlled tools)
Host ──tools/call───► Server         (Claude invokes a tool)
Host ──resources/read► Server        (application-controlled data)
Host ──prompts/get──► Server         (user-controlled templates)

5.14 Approval and human-in-the-loop for irreversible tools

Certains outils sont irréversibles (remboursements, suppressions, envois, déploiements). La conception correcte les protège de manière déterministe, pas en faisant confiance au modèle.

# Protéger un outil irréversible derrière une approbation ; renvoyer is_error pour que Claude s'adapte.
if block.name == "issue_refund" and block.input["amount_cents"] > 50000:
    result = {"type": "tool_result", "tool_use_id": block.id,
              "content": "Refund over $500 requires human approval; request queued.",
              "is_error": True}

5.15 Common misconceptions

5.16 Scenario walkthrough: a payments tool that must be safe and portable

Scénario. Une fintech veut que Claude consulte les commandes, cherche dans un centre d’aide, et — avec précaution — émette des remboursements, et elle veut les mêmes outils disponibles dans Claude Code, Claude Desktop et un service Messages API de production, maintenus en un seul endroit. Elle est sur Fable 5.1 pour sa qualité de raisonnement. Les premières tentatives forcent l’outil de remboursement avec tool_choice: {type: 'tool', name: 'issue_refund'} (obtenant des 400), suppriment parfois un résultat d’outil quand deux outils s’exécutent en parallèle (obtenant des 400), et émettent des remboursements sans étape d’approbation.

Trace de raisonnement d’expert.

1. Choisissez le mécanisme de réutilisation. « Mêmes outils entre Code, Desktop et l’API, un seul endroit » → construisez un serveur MCP et connectez chaque host (stdio en local, Streamable HTTP pour le serveur partagé/distant sécurisé avec OAuth 2.1 ; la Messages API utilise le connecteur MCP). Copier le JSON de custom-tool dans chaque app est le piège de maintenance.
2. Corrigez les 400 de Fable 5.1 sur le choix d’outil. Fable 5.1 rejette le choix d’outil forcé/any. Utilisez tool_choice: 'auto' avec une instruction claire, ou les sorties structurées / strict: true pour les parties d’extraction. Réessayer le 400 avec backoff est faux — il est déterministe.
3. Corrigez les 400 de résultats parallèles. Renvoyez exactement un tool_result par bloc tool_use, tous dans le même tour user suivant, chacun indexé sur son tool_use_id ; en cas d’échec, renvoyez is_error: true pour que Claude puisse récupérer. Supprimer un résultat provoque le 400.
4. Rendez les remboursements sûrs. Les remboursements sont irréversibles → protégez-les avec un hook PreToolUse / workflow d’approbation et gardez l’outil de remboursement hors de la liste blanche de tout agent routinier en lecture seule. « Confirmer avant de rembourser » dans la description n’est pas une application.
5. Dimensionnez correctement le catalogue. Gardez ~4–5 outils actifs ; si le catalogue grandit, utilisez tool search + defer_loading.
6. Rejetez les alternatives tentantes. « Forcer l’outil de remboursement pour le déterminisme » — 400 sur Fable 5.1. « Réessayer le 400 avec backoff » — erreur déterministe. « Mettre les outils dans CLAUDE.md pour les partager » — CLAUDE.md contient des instructions, pas des outils exécutables. « Utiliser un Skill pour partager entre hosts » — les Skills sont du savoir-faire empaqueté propre à Claude Code.

Décision correcte. Un serveur MCP (OAuth 2.1 pour le transport distant) connecté à tous les hosts ; auto + instruction ou sorties structurées sur Fable 5.1 au lieu du choix d’outil forcé ; gestion correcte des tool_result parallèles avec is_error ; remboursements derrière un hook d’approbation et hors des listes blanches routinières ; tool search + defer_loading si le catalogue grandit.

Pièges de l’examen dans ce domaine

Questions d’entraînement

À retenir

• Le cycle de vie d’utilisation d’outils : définir les outils → tool_use → exécuter et renvoyer tool_result (correspondant au tool_use_id) → réponse finale.
• La description d’outil et l’input_schema sont le levier le plus important pour une utilisation correcte des outils.
• tool_choice vaut auto/any/tool/none ; Fable 5.1 rejette any et les outils forcés – utilisez les sorties structurées / strict / auto.
• Les outils indépendants peuvent s’exécuter en parallèle ; renvoyez tous les résultats dans un tour user.
• Les outils côté client s’exécutent dans votre code ; les intégrés côté serveur (web search, exécution de code, computer use, éditeur de texte, bash, memory) s’exécutent chez Anthropic.
• Au-delà de ~10 outils, utilisez tool search + defer_loading ; exigez une approbation pour les actions irréversibles.
• MCP est du JSON-RPC 2.0 avec tools (modèle), resources (app), prompts (utilisateur) ; stdio pour le local, Streamable HTTP + OAuth 2.1 pour le distant ; écrivez-le avec FastMCP (Python) ou @modelcontextprotocol/sdk (TS).
• La négociation des capacités a lieu à initialize ; choisissez stdio pour les outils en sous-processus local et Streamable HTTP + OAuth 2.1 pour les serveurs partagés/distants (SSE-only est hérité).
• Protégez les outils irréversibles (remboursements/suppressions/envois/déploiements) avec un hook PreToolUse / workflow d’approbation et le moindre privilège — la description de l’outil est une consigne, pas une application.
• Renvoyez chaque tool_result parallèle dans un tour user indexé sur son tool_use_id, et marquez les échecs avec is_error: true pour que Claude puisse récupérer.
• Un 400 d’outil forcé sur Fable 5.1 est déterministe — passez à auto/aux sorties structurées plutôt que de réessayer avec backoff.