Installer et configurer un MCP

Le fichier de configuration MCP

Les MCP se configurent dans un fichier JSON qui indique à Claude Code quels serveurs MCP lancer et comment les connecter. Il existe deux niveaux de configuration, global pour vos outils personnels, et par projet pour la stack technique de chaque dépôt.

Structure du fichier .mcp.json

{
  "mcpServers": {
    "nom-du-mcp": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "API_KEY": "votre-clé-ici"
      }
    }
  }
}

Chaque entrée dans mcpServers définit un MCP avec :

• command : la commande pour lancer le serveur MCP (npx, uvx, docker, ou un chemin vers un binaire)
• args : les arguments passés à la commande (le package npm, les options de configuration)
• env (optionnel) : les variables d'environnement nécessaires (tokens, clés API)

Installation d'un MCP : les trois méthodes

# Syntaxe générale
claude mcp add <nom> -- <commande> <args...>

# Exemple : ajouter Context7
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Exemple : ajouter GitHub avec un token
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Exemple : ajouter un MCP avec des variables d'environnement
claude mcp add slack -e SLACK_BOT_TOKEN=xoxb-votre-token -- npx -y @modelcontextprotocol/server-slack

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_votre_token"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URL",
        "mcp/postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/dbname"
      }
    }
  }
}

Configuration dans Claude Code

Vérifier les MCP installés

Après avoir ajouté un MCP, relancez Claude Code et vérifiez qu'il est bien connecté.

# Lister tous les MCP configurés
claude mcp list

# Résultat attendu :
# context7: connected
#   Tools: query-docs, resolve-library-id
# github: connected
#   Tools: list_issues, create_pull_request, search_code, ...

# Supprimer un MCP
claude mcp remove <nom>

# Voir les détails d'un MCP
claude mcp get <nom>

Portée de la configuration

# Ajouter un MCP au niveau du projet (défaut)
claude mcp add context7 -- npx -y @upstash/context7-mcp

# Ajouter un MCP au niveau global (tous les projets)
claude mcp add context7 --scope global -- npx -y @upstash/context7-mcp

# Ajouter un MCP au niveau utilisateur (pour cet utilisateur)
claude mcp add context7 --scope user -- npx -y @upstash/context7-mcp

Debug et troubleshooting

Le MCP ne se connecte pas

# Vérifier que npx est installé
which npx

# Vérifier que le package MCP existe
npx -y @upstash/context7-mcp --help

# Si vous utilisez uvx (Python)
which uvx

# Voir les logs de connexion MCP
claude mcp logs

# Voir les logs d'un MCP spécifique
claude mcp logs context7

# Valider votre fichier .mcp.json
cat .mcp.json | python3 -m json.tool

# Ou avec Node.js
node -e "console.log(JSON.parse(require('fs').readFileSync('.mcp.json','utf8')))"

# Lancer le serveur MCP directement
npx -y @upstash/context7-mcp

# Si le serveur démarre et attend des entrées stdin, c'est bon
# Ctrl+C pour quitter

Erreurs courantes et solutions

Exemple complet : configurer trois MCP

Voici un exemple réaliste de configuration avec trois MCP pour un projet de développement web.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Avec cette configuration, vous pouvez demander à Claude Code :

"Consulte la documentation de Next.js 14, crée une page d'erreur 404 avec les bonnes pratiques, teste-la dans le navigateur, et crée une pull request."

Claude Code enchaînera automatiquement Context7 (documentation), l'édition de fichiers (création de la page), Playwright (test visuel) et GitHub (pull request).

Prochaines étapes

Votre premier MCP est configuré ? Découvrez maintenant les meilleurs MCP par catégorie.

• Comprendre les MCP : Le fonctionnement du protocole MCP expliqué
• Top MCP productivité : Gmail, Slack, Calendar, Figma, Lighthouse
• Top MCP développement : Context7, GitHub, Sentry, bases de données
• Top MCP design & UI : Playwright, Chrome DevTools, 21st.dev Magic