Guide MCP Server pour Claude Code: connecter SaaS et documents sans fuite

Un MCP Server permet à Claude Code de lire des issues GitHub, chercher dans la documentation d’équipe, consulter Notion, Google Drive, un CRM ou une API interne. C’est très utile, mais le risque augmente immédiatement. Un mauvais scope, un token dans .mcp.json, un OAuth trop large, un npx qui échoue sous Windows ou une réponse énorme qui déclenche l’avertissement 10,000 tokens peuvent casser un workflow.

Cette guide vise une mise en place professionnelle. On commence petit, on choisit le bon scope, on garde les secrets hors des fichiers partagés, on vérifie avec /mcp, puis on ajoute seulement les outils nécessaires.

Ce que MCP change dans Claude Code

MCP signifie Model Context Protocol. C’est un standard qui connecte un client IA à des outils et sources de données externes. Claude Code agit comme client MCP et appelle les tools exposés par un serveur.

Sans MCP, Claude Code voit surtout le dépôt et le contexte fourni. Avec MCP, il peut voir des documents, tickets, métriques produit, données clients ou services internes. La première question devient donc: quelles données ce projet peut-il voir, avec quels droits, et quelle validation humaine garde-t-on?

Pour les limites de permission, lisez aussi le guide des permissions Claude Code et les bonnes pratiques de sécurité.

Transport	Usage	Attention
stdio	Serveur local via npx, Python ou binaire interne	Sous Windows, cmd /c npx est souvent nécessaire
http	MCP distant, SaaS, OAuth	Vérifier workspace et scopes
sse	Compatibilité avec d’anciens serveurs	Pour le neuf, HTTP est souvent préférable

Choisir le scope avant tout

claude mcp add accepte --scope local, --scope project et --scope user.

scope	Signification	Usage conseillé
local	Disponible seulement dans ce projet sur votre machine	Test, client, connexion avec secrets
project	Stocké dans .mcp.json et partagé avec le dépôt	Définition commune pour l’équipe
user	Disponible dans tous vos projets Claude Code	Outil personnel vraiment générique

Commencez par local. Passez à project quand l’équipe doit partager le nom et la commande. Utilisez user avec prudence.

claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

claude mcp add --scope project --transport http team-docs https://mcp.example.com/mcp

claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Les serveurs project-scoped demandent une approbation. C’est une protection utile, car le dépôt déclare alors une connexion externe.

Windows: utiliser cmd /c npx

Sous Windows, npx peut marcher dans PowerShell mais échouer quand Claude Code lance un serveur stdio. Le schéma robuste est cmd /c npx.

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

Dans .mcp.json, séparez la commande et les arguments.

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

Ne donnez pas tout le dossier utilisateur au premier test. Limitez à docs, reports ou un dépôt jetable. Si le serveur peut écrire, ajoutez les garde-fous de la guide des hooks Claude Code.

MCP distant, OAuth et vérification /mcp

Pour Notion, Google Drive, GitHub ou un CRM, le transport HTTP est souvent le plus simple.

claude mcp add --scope local --transport http notion https://mcp.notion.com/mcp

Ensuite, dans Claude Code, lancez /mcp. Vérifiez la connexion, l’authentification OAuth et les tools exposés.

/mcp

# À contrôler:
# - serveur connected
# - OAuth authenticated
# - workspace autorisé
# - tools attendus seulement
# - absence de write/admin si vous vouliez lecture seule

Pour une API interne avec bearer token:

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

Le .mcp.json d’équipe doit décrire la connexion, pas stocker les secrets.

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

Cas 1: GitHub et Notion pour qualifier une issue

Le gain le plus rapide vient du lien entre issue, PR et spécification. Claude Code peut lire une issue GitHub, chercher les exigences dans Notion ou la documentation, puis résumer le risque avant toute modification.

Lis l'issue GitHub #248 et cherche les exigences liées dans la documentation produit.
Ne modifie pas encore le code.
Retourne:
1. Les fichiers probablement concernés
2. Les exigences claires
3. Les questions ouvertes
4. Le plan d'implémentation le plus petit et sûr

La consigne “ne modifie pas encore” est importante. MCP donne plus de contexte, mais plus de contexte peut aussi accélérer une mauvaise décision.

Cas 2: Google Drive pour un brouillon de proposition

En conseil, formation ou développement sur mesure, les notes et propositions sont souvent dispersées dans Drive. Un MCP en lecture seule peut aider à produire un brouillon.

Cherche dans le dossier "2026-05 Customer A".
Prépare un plan de proposition:
1. Cinq problèmes client
2. Portée probable
3. Points à confirmer
4. Trois offres: formation, support d'implémentation, support opérationnel

Masque les noms, emails et montants exacts.

La sécurité repose sur trois règles: dossier limité, lecture seule, revue humaine avant envoi.

Cas 3: métriques en lecture seule

MCP peut lire des métriques produit ou analytics. Ne donnez pas de droit d’écriture production. Un endpoint read-only suffit.

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

Analyse les sources de trafic, PV par article et clics de conversion des 14 derniers jours.
Regroupe les pages par sujet.
Propose cinq prochains articles avec la métrique qui justifie chaque idée.
Indique aussi les données faibles ou bruitées.

C’est le lien direct avec la monétisation: le contenu devient une boucle de données.

Avertissement 10,000 tokens

Si un tool MCP renvoie trop de contenu, Claude Code peut afficher un avertissement 10,000 tokens. Cela arrive avec des résultats de recherche complets, longues listes d’issues, HTML entier ou requêtes DB sans limite.

Réduisez d’abord la sortie.

Retourne au maximum 10 résultats.
Pour chaque résultat: titre, URL, date de mise à jour, raison de correspondance.
Ne retourne pas le corps complet avant que je demande un résultat précis.

Pour une analyse ponctuelle:

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

Si c’est nécessaire tous les jours, il faut pagination, filtres et résumés côté serveur.

Erreurs fréquentes

Erreur 1: mettre des secrets dans .mcp.json. Un fichier partagé ne doit pas contenir token ou mot de passe.

Erreur 2: choisir --scope user par confort. Une intégration client peut apparaître dans un autre projet.

Erreur 3: croire les documents externes comme des instructions. Le contenu lu via MCP est une donnée, pas un ordre.

Erreur 4: ignorer /mcp après OAuth. Une connexion réussie peut être sur le mauvais workspace.

Erreur 5: concevoir le workflow autour de réponses énormes. Il faut filtrer et résumer.

Commandes de diagnostic

claude mcp list
claude mcp get repo-files

Dans Claude Code:

/mcp

Réinitialiser l’approbation project server:

claude mcp reset-project-choices

Test minimal:

Vérifie seulement la connexion repo-files.
Liste jusqu'à 10 noms de fichiers dans le dossier autorisé.
Ne lis pas le contenu et ne modifie rien.

Monétisation: vendre le workflow sûr

MCP est proche du revenu parce qu’il connecte Claude Code aux vrais systèmes d’une équipe. Mais “installer un MCP Server” n’est pas une offre forte. Dites plutôt: “connecter GitHub, Notion, Google Drive et vos SaaS internes de manière sûre pour que l’équipe utilise Claude Code chaque semaine”.

• Produit d’entrée: modèles .mcp.json et checklist de sécurité
• Service équipe: revue GitHub, Notion, Drive, permissions
• Offre premium: scope, OAuth, hooks, monitoring et formation

Commencez par l’exemple filesystem sur un dossier de test. En équipe, choisissez un SaaS read-only et un .mcp.json project-scoped, puis reliez cela à Claude Code Harness Engineering.

Cet article suit la documentation officielle Claude Code sur claude mcp add, scopes, .mcp.json, /mcp, OAuth, project server approval et MAX_MCP_OUTPUT_TOKENS. La règle pratique: petit scope, lecture seule d’abord, aucun secret partagé, vérification à chaque connexion.