Brancher son API métier

1Créer le serveur

mkdir mcp-metier && cd mcp-metier
npm init -y
npm install @modelcontextprotocol/server zod

Ajoute "type": "module" dans package.json. Le paquet @modelcontextprotocol/server est la version 2 du SDK TypeScript ; les exemples qui importent @modelcontextprotocol/sdk datent de la v1.

2Un outil, en lecture seule

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const BASE = process.env.API_BASE_URL;
const JETON = process.env.API_TOKEN;

serveStdio(() => {
  const server = new McpServer({ name: "metier", version: "1.0.0" });

  server.registerTool(
    "statut_commande",
    {
      description:
        "Renvoie l'etat d'avancement d'une commande a partir de son numero. " +
        "A utiliser des qu'on demande ou en est une commande.",
      inputSchema: z.object({
        numero: z.string().describe("Numero de commande, format CMD-12345"),
      }),
      annotations: { readOnlyHint: true },
    },
    async ({ numero }) => {
      const r = await fetch(`${BASE}/orders/${encodeURIComponent(numero)}`, {
        headers: { Authorization: `Bearer ${JETON}` },
      });

      if (r.status === 404) {
        return {
          content: [{ type: "text", text: `Commande introuvable : ${numero}` }],
          isError: true,
        };
      }

      const c = await r.json();

      return {
        content: [
          {
            type: "text",
            text: [
              `Commande ${c.reference}`,
              `Statut : ${c.status}`,
              `Expedition prevue : ${c.shipping_date ?? "non planifiee"}`,
              `Montant : ${c.total_amount} EUR`,
            ].join("\n"),
          },
        ],
      };
    }
  );

  return server;
});

Deux choses méritent d'être notées. annotations: { readOnlyHint: true } déclare que l'outil ne modifie rien : c'est une indication de comportement, pas une garantie technique, la vraie garantie vient du jeton de lecture seule. Et isError: true renvoie une erreur que le modèle peut lire et corriger, au lieu d'une exception qui le laisse deviner.

3Filtrer ce qui sort, pas ce qui entre

C'est le point que presque tout le monde rate. Un return JSON.stringify(c) sur une fiche client, c'est deux cents champs envoyés au modèle : identifiants internes, horodatages techniques, adresse, RIB, historique complet. Coût en jetons, bruit dans la réponse, et fuite de données qui n'avaient rien à faire là.

La règle : le serveur choisit les champs, un par un, explicitement. Si tu ne peux pas nommer les cinq champs utiles, c'est que l'outil n'est pas assez précis.

4Brancher sans mettre le jeton dans un prompt

Les identifiants passent par l'environnement du processus, jamais dans le texte de la conversation :

claude mcp add --env API_BASE_URL=https://api.interne.local \
  --env API_TOKEN=xxxxx \
  --transport stdio metier -- node /chemin/absolu/serveur.js

Vérifie ensuite :

claude mcp list

Le serveur doit apparaître comme connecté. Dans un fichier .mcp.json partagé avec l'équipe, référence les variables au lieu des valeurs, avec la syntaxe ${API_TOKEN} : chacun fournit son propre jeton, et le fichier reste commitable.

5Passer en écriture, plus tard, et jamais en silence

Quand un outil d'écriture devient nécessaire, trois règles.

• Une action précise, pas une action générique. annuler_commande(numero, motif) plutôt que modifier_commande(numero, champs).
• Un compte de service dédié, avec les seuls droits de cette action, distinct du compte de lecture.
• Une trace, côté API : qui a appelé, quand, avec quels arguments. Les journaux du modèle ne suffisent pas.

Et tant que possible, garde l'écriture sur un environnement de test le temps de vérifier que le modèle appelle l'outil au bon moment.