Les outils personnalisés vous permettent d’étendre les capacités de Claude Code avec vos propres fonctionnalités via des serveurs MCP en processus, permettant à Claude d’interagir avec des services externes, des API, ou d’effectuer des opérations spécialisées.

​
Création d’Outils Personnalisés

Utilisez les fonctions d’aide createSdkMcpServer et tool pour définir des outils personnalisés type-safe : 
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

// Créer un serveur MCP SDK avec des outils personnalisés
const customServer = createSdkMcpServer({
  name: "my-custom-tools",
  version: "1.0.0",
  tools: [
    tool(
      "get_weather",
      "Obtenir la température actuelle d'un lieu en utilisant les coordonnées",
      {
        latitude: z.number().describe("Coordonnée de latitude"),
        longitude: z.number().describe("Coordonnée de longitude")
      },
      async (args) => {
        const response = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`);
        const data = await response.json();

        return {
          content: [{
            type: "text",
            text: `Température : ${data.current.temperature_2m}°F`
          }]
        };
      }
    )
  ]
});

​
Utilisation d’Outils Personnalisés

Passez le serveur personnalisé à la fonction query via l’option mcpServers comme un dictionnaire/objet.
Important : Les outils MCP personnalisés nécessitent le mode d’entrée en streaming. Vous devez utiliser un générateur/itérable asynchrone pour le paramètre prompt - une simple chaîne ne fonctionnera pas avec les serveurs MCP.

​
Format des Noms d’Outils

Lorsque les outils MCP sont exposés à Claude, leurs noms suivent un format spécifique :
  • Modèle : mcp__{server_name}__{tool_name}
  • Exemple : Un outil nommé get_weather dans le serveur my-custom-tools devient mcp__my-custom-tools__get_weather

​
Configuration des Outils Autorisés

Vous pouvez contrôler quels outils Claude peut utiliser via l’option allowedTools : 
import { query } from "@anthropic-ai/claude-agent-sdk";

// Utiliser les outils personnalisés dans votre requête avec entrée en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Quel temps fait-il à San Francisco ?"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Utiliser un générateur asynchrone pour l'entrée en streaming
  options: {
    mcpServers: {
      "my-custom-tools": customServer  // Passer comme objet/dictionnaire, pas comme tableau
    },
    // Spécifier optionnellement quels outils Claude peut utiliser
    allowedTools: [
      "mcp__my-custom-tools__get_weather",  // Autoriser l'outil météo
      // Ajouter d'autres outils selon les besoins
    ],
    maxTurns: 3
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

​
Exemple avec Plusieurs Outils

Lorsque votre serveur MCP a plusieurs outils, vous pouvez les autoriser sélectivement : 
const multiToolServer = createSdkMcpServer({
  name: "utilities",
  version: "1.0.0",
  tools: [
    tool("calculate", "Effectuer des calculs", { /* ... */ }, async (args) => { /* ... */ }),
    tool("translate", "Traduire du texte", { /* ... */ }, async (args) => { /* ... */ }),
    tool("search_web", "Rechercher sur le web", { /* ... */ }, async (args) => { /* ... */ })
  ]
});

// Autoriser seulement des outils spécifiques avec entrée en streaming
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Calcule 5 + 3 et traduis 'bonjour' en espagnol"
    }
  };
}

for await (const message of query({
  prompt: generateMessages(),  // Utiliser un générateur asynchrone pour l'entrée en streaming
  options: {
    mcpServers: {
      utilities: multiToolServer
    },
    allowedTools: [
      "mcp__utilities__calculate",   // Autoriser la calculatrice
      "mcp__utilities__translate",   // Autoriser le traducteur
      // "mcp__utilities__search_web" n'est PAS autorisé
    ]
  }
})) {
  // Traiter les messages
}

​
Sécurité de Type avec Python

Le décorateur @tool prend en charge diverses approches de définition de schéma pour la sécurité de type : 
import { z } from "zod";

tool(
  "process_data",
  "Traiter des données structurées avec sécurité de type",
  {
    // Le schéma Zod définit à la fois la validation d'exécution et les types TypeScript
    data: z.object({
      name: z.string(),
      age: z.number().min(0).max(150),
      email: z.string().email(),
      preferences: z.array(z.string()).optional()
    }),
    format: z.enum(["json", "csv", "xml"]).default("json")
  },
  async (args) => {
    // args est entièrement typé basé sur le schéma
    // TypeScript sait : args.data.name est string, args.data.age est number, etc.
    console.log(`Traitement des données de ${args.data.name} en tant que ${args.format}`);
    
    // Votre logique de traitement ici
    return {
      content: [{
        type: "text",
        text: `Données traitées pour ${args.data.name}`
      }]
    };
  }
)

​
Gestion des Erreurs

Gérez les erreurs avec élégance pour fournir un retour significatif : 
tool(
  "fetch_data",
  "Récupérer des données depuis une API",
  {
    endpoint: z.string().url().describe("URL du point de terminaison API")
  },
  async (args) => {
    try {
      const response = await fetch(args.endpoint);
      
      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `Erreur API : ${response.status} ${response.statusText}`
          }]
        };
      }
      
      const data = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(data, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Échec de récupération des données : ${error.message}`
        }]
      };
    }
  }
)

​
Exemples d’Outils

​
Outil de Requête de Base de Données

const databaseServer = createSdkMcpServer({
  name: "database-tools",
  version: "1.0.0",
  tools: [
    tool(
      "query_database",
      "Exécuter une requête de base de données",
      {
        query: z.string().describe("Requête SQL à exécuter"),
        params: z.array(z.any()).optional().describe("Paramètres de requête")
      },
      async (args) => {
        const results = await db.query(args.query, args.params || []);
        return {
          content: [{
            type: "text",
            text: `Trouvé ${results.length} lignes :\n${JSON.stringify(results, null, 2)}`
          }]
        };
      }
    )
  ]
});

​
Outil de Passerelle API

const apiGatewayServer = createSdkMcpServer({
  name: "api-gateway",
  version: "1.0.0",
  tools: [
    tool(
      "api_request",
      "Effectuer des requêtes API authentifiées vers des services externes",
      {
        service: z.enum(["stripe", "github", "openai", "slack"]).describe("Service à appeler"),
        endpoint: z.string().describe("Chemin du point de terminaison API"),
        method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("Méthode HTTP"),
        body: z.record(z.any()).optional().describe("Corps de la requête"),
        query: z.record(z.string()).optional().describe("Paramètres de requête")
      },
      async (args) => {
        const config = {
          stripe: { baseUrl: "https://api.stripe.com/v1", key: process.env.STRIPE_KEY },
          github: { baseUrl: "https://api.github.com", key: process.env.GITHUB_TOKEN },
          openai: { baseUrl: "https://api.openai.com/v1", key: process.env.OPENAI_KEY },
          slack: { baseUrl: "https://slack.com/api", key: process.env.SLACK_TOKEN }
        };
        
        const { baseUrl, key } = config[args.service];
        const url = new URL(`${baseUrl}${args.endpoint}`);
        
        if (args.query) {
          Object.entries(args.query).forEach(([k, v]) => url.searchParams.set(k, v));
        }
        
        const response = await fetch(url, {
          method: args.method,
          headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
          body: args.body ? JSON.stringify(args.body) : undefined
        });
        
        const data = await response.json();
        return {
          content: [{
            type: "text",
            text: JSON.stringify(data, null, 2)
          }]
        };
      }
    )
  ]
});

​
Outil Calculatrice

const calculatorServer = createSdkMcpServer({
  name: "calculator",
  version: "1.0.0",
  tools: [
    tool(
      "calculate",
      "Effectuer des calculs mathématiques",
      {
        expression: z.string().describe("Expression mathématique à évaluer"),
        precision: z.number().optional().default(2).describe("Précision décimale")
      },
      async (args) => {
        try {
          // Utiliser une bibliothèque d'évaluation mathématique sécurisée en production
          const result = eval(args.expression); // Exemple seulement !
          const formatted = Number(result).toFixed(args.precision);
          
          return {
            content: [{
              type: "text",
              text: `${args.expression} = ${formatted}`
            }]
          };
        } catch (error) {
          return {
            content: [{
              type: "text",
              text: `Erreur : Expression invalide - ${error.message}`
            }]
          };
        }
      }
    ),
    tool(
      "compound_interest",
      "Calculer les intérêts composés pour un investissement",
      {
        principal: z.number().positive().describe("Montant d'investissement initial"),
        rate: z.number().describe("Taux d'intérêt annuel (en décimal, ex : 0,05 pour 5%)"),
        time: z.number().positive().describe("Période d'investissement en années"),
        n: z.number().positive().default(12).describe("Fréquence de composition par an")
      },
      async (args) => {
        const amount = args.principal * Math.pow(1 + args.rate / args.n, args.n * args.time);
        const interest = amount - args.principal;
        
        return {
          content: [{
            type: "text",
            text: `Analyse d'Investissement :\n` +
                  `Principal : ${args.principal.toFixed(2)}$\n` +
                  `Taux : ${(args.rate * 100).toFixed(2)}%\n` +
                  `Durée : ${args.time} années\n` +
                  `Composition : ${args.n} fois par an\n\n` +
                  `Montant Final : ${amount.toFixed(2)}$\n` +
                  `Intérêts Gagnés : ${interest.toFixed(2)}$\n` +
                  `Rendement : ${((interest / args.principal) * 100).toFixed(2)}%`
          }]
        };
      }
    )
  ]
});

​
Documentation Connexe