Connecter Qwen Code aux outils via MCP

Qwen Code peut se connecter à des outils et sources de données externes via le Model Context Protocol (MCP) . Les serveurs MCP donnent à Qwen Code accès à vos outils, bases de données et API.

Ce que vous pouvez faire avec MCP

Avec des serveurs MCP connectés, vous pouvez demander à Qwen Code de :

• Travailler avec des fichiers et des repos (lire/rechercher/écrire, selon les outils que vous activez)
• Interroger des bases de données (inspection de schéma, requêtes, reporting)
• Intégrer des services internes (exposer vos API en tant qu’outils MCP)
• Automatiser des workflows (tâches répétables exposées en tant qu’outils/prompts)

Démarrage rapide

Qwen Code charge les serveurs MCP depuis mcpServers dans votre settings.json. Vous pouvez configurer les serveurs soit :

• En modifiant settings.json directement
• En utilisant les commandes qwen mcp (voir Référence CLI)

Ajouter votre premier serveur

1. Ajoutez un serveur (exemple : serveur MCP HTTP distant) :

qwen mcp add --transport http my-server http://localhost:3000/mcp

2. Démarrez Qwen Code et ouvrez la boîte de dialogue de gestion MCP pour afficher et gérer les serveurs :

qwen

Entrez ensuite :

/mcp

3. Si Qwen Code était déjà en cours d’exécution avant l’ajout du serveur, redémarrez-le dans le même projet. Demandez ensuite au modèle d’utiliser les outils de ce serveur.

Emplacement de stockage de la configuration (scopes)

La plupart des utilisateurs n’ont besoin que de ces deux scopes :

• Scope utilisateur (par défaut) : ~/.qwen/settings.json pour tous les projets de votre machine
• Scope projet : .qwen/settings.json à la racine de votre projet

Écrire dans le scope utilisateur :

qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp

Configurer les serveurs

Choisir un transport

Configurer via settings.json vs qwen mcp add

Les deux approches produisent les mêmes entrées mcpServers dans votre settings.json — utilisez celle que vous préférez.

Serveur Stdio (processus local)

JSON (.qwen/settings.json) :

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

CLI (écrit dans le scope utilisateur par défaut) :

qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
  --timeout 15000 python -m my_mcp_server --port 8080

Serveur HTTP (HTTP streamable distant)

JSON :

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

CLI :

qwen mcp add --transport http httpServerWithAuth http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-token" --timeout 5000

Serveur SSE (Server-Sent Events distant)

JSON :

{
  "mcpServers": {
    "sseServer": {
      "url": "http://localhost:8080/sse",
      "timeout": 30000
    }
  }
}

CLI :

qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000

Utiliser les prompts et ressources MCP

Outre les outils, Qwen Code découvre et expose deux autres primitives MCP.

Prompts (commandes slash)

Tout prompt qu’un serveur annonce via prompts/list devient une commande slash exécutable. Après la découverte, tapez / et vous verrez le prompt listé (étiqueté MCP: <server>) ; exécutez-le comme n’importe quelle autre commande :

/my_prompt --arg1="value" --arg2="value"
# la forme positionnelle fonctionne aussi :
/my_prompt "value" "value"
# afficher les arguments du prompt :
/my_prompt help

Les messages du prompt sont envoyés au modèle, qui agit ensuite en conséquence.

La découverte est tolérante concernant la capacité prompts déclarée : certains serveurs implémentent prompts/list mais omettent prompts de leurs capacités initialize. Qwen Code tente tout de même prompts/list, de sorte que ces prompts apparaissent quand même. Un serveur qui n’a réellement aucun prompt répond simplement Method not found, ce qui est ignoré.

Ressources

Les ressources qu’un serveur annonce via resources/list sont découvertes par serveur. Ouvrez la boîte de dialogue de gestion avec /mcp et sélectionnez un serveur pour voir son compteur de Ressources à côté de ses outils et prompts. Choisissez View resources pour parcourir les URI des ressources du serveur ; en sélectionner une affiche sa description et son type MIME, ainsi que la référence exacte @server:uri à coller dans un message. Comme pour les prompts, la capacité resources n’a pas besoin d’être déclarée.

Injectez le contenu d’une ressource dans votre message avec la syntaxe @server:uri — tapez @, puis le nom du serveur, un deux-points, et l’URI de la ressource :

summarize @myserver:file:///docs/spec.md and list the open questions

Taper @myserver: affiche une liste d’autocomplétion des ressources de ce serveur ; continuez à taper pour filtrer, en correspondant (sans casse) soit à l’URI de la ressource ou à son nom/titre convivial. Vous n’avez pas besoin de connaître une URI par cœur — avant d’atteindre le deux-points, taper une partie du nom d’un serveur suggère également les serveurs correspondants qui exposent des ressources, afin que vous puissiez en choisir un et accéder directement à sa liste de ressources. Lors de la soumission, la ressource référencée est lue et son contenu est ajouté à votre message (texte en ligne, blobs binaires en pièces jointes) ; la référence @server:uri est conservée dans le prompt afin que le modèle sache ce qu’il regarde. Le préfixe server doit correspondre à un serveur MCP configuré — sinon, le token est traité comme un chemin de fichier normal, de sorte que les références @path/to/file existantes ne sont pas affectées. Les lectures de ressources sont désactivées dans les dossiers non fiables.

Disponibilité progressive et timeouts de découverte

Qwen Code découvre les serveurs MCP en arrière-plan après que l’interface utilisateur est déjà interactive. Vous voyez le premier prompt du CLI en quelques centaines de millisecondes, même si l’un de vos serveurs MCP prend plusieurs secondes (ou ne répond jamais), et la liste des outils du modèle se met à jour en environ une frame (~16 ms) après que chaque serveur a terminé son handshake de découverte.

• Mode interactif : l’interface utilisateur apparaît immédiatement ; un badge de statut MCP en bas à droite affiche N/M MCP servers ready pendant que la découverte est en cours. Envoyer un prompt avant la fin de MCP signifie simplement que le modèle voit les outils qui sont prêts à ce moment-là ; les prompts suivants voient plus d’outils au fur et à mesure que les serveurs se mettent en ligne.
• Mode non interactif (--prompt, stream-json, ACP) : le CLI attend toujours que la découverte MCP se stabilise avant d’envoyer le premier prompt, de sorte que les invocations scriptées / pipées voient le même ensemble d’outils complet que le comportement synchrone hérité produisait.

discoveryTimeoutMs par serveur

Chaque serveur MCP dispose d’un timeout réservé à la découverte qui limite la durée maximale du handshake initial (connect + tools/list + prompts/list + resources/list). Valeurs par défaut :

• serveurs stdio : 30 s
• serveurs HTTP / SSE distants : 5 s (le risque réseau est plus élevé)

Remplacez cette valeur par serveur si nécessaire :

{
  "mcpServers": {
    "slow-stdio": {
      "command": "node",
      "args": ["./slow-server.js"],
      "discoveryTimeoutMs": 60000,
    },
    "flaky-remote": {
      "httpUrl": "https://example.com/mcp",
      "discoveryTimeoutMs": 10000,
    },
  },
}

Le champ timeout existant est le timeout d’appel d’outil (utilisé pour chaque requête tools/call, par défaut 10 minutes) et n’est pas affecté par discoveryTimeoutMs — une invocation d’outil de longue durée n’est pas une pathologie de démarrage.

Désactiver le MCP progressif

Si vous avez besoin de l’ancien comportement synchrone (le CLI attend chaque serveur MCP avant d’afficher l’interface utilisateur), définissez QWEN_CODE_LEGACY_MCP_BLOCKING=1 dans votre environnement. Cela est conservé comme solution de secours pour au moins une version.

Sécurité et contrôle

Confiance (ignorer les confirmations)

• Confiance serveur (trust: true) : ignore les invites de confirmation pour ce serveur (à utiliser avec parcimonie).

Authentification OAuth

Qwen Code prend en charge l’authentification OAuth 2.0 pour les serveurs MCP. Cela est utile lors de l’accès à des serveurs distants nécessitant une authentification.

Utilisation de base

Lorsque vous ajoutez un serveur MCP avec des identifiants OAuth, Qwen Code gère automatiquement le flux d’authentification :

qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
  --oauth-client-id your-client-id \
  --oauth-redirect-uri https://your-server.com/oauth/callback \
  --oauth-authorization-url https://provider.example.com/authorize \
  --oauth-token-url https://provider.example.com/token

Important : Configuration de l’URI de redirection

Le flux OAuth nécessite une URI de redirection vers laquelle le fournisseur d’autorisation envoie le code d’authentification.

• Développement local : Par défaut, Qwen Code utilise http://localhost:7777/oauth/callback. Cela fonctionne lorsque vous exécutez Qwen Code sur votre machine locale avec un navigateur local.

• Déploiements distants/cloud : Lors de l’exécution de Qwen Code sur des serveurs distants, des IDE cloud ou des terminaux web, la redirection localhost par défaut ne fonctionnera PAS. Vous DEVEZ configurer --oauth-redirect-uri pour qu’il pointe vers une URL accessible publiquement capable de recevoir le callback OAuth.

Exemple pour les serveurs distants :

qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback

Configuration manuelle via settings.json

Vous pouvez également configurer OAuth en modifiant settings.json directement :

{
  "mcpServers": {
    "oauthServer": {
      "url": "https://api.example.com/sse/",
      "oauth": {
        "enabled": true,
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "authorizationUrl": "https://provider.example.com/authorize",
        "tokenUrl": "https://provider.example.com/token",
        "redirectUri": "https://your-server.com/oauth/callback",
        "scopes": ["read", "write"]
      }
    }
  }
}

Propriétés de configuration OAuth :

Gestion des tokens

Les tokens OAuth sont automatiquement :

• Stockés dans ~/.qwen/mcp-oauth-tokens.json (texte en clair, mode 0600) par défaut. Si QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true est défini, Qwen Code utilise un stockage basé sur le trousseau de clés lorsqu’il est disponible, ou ~/.qwen/mcp-oauth-tokens-v2.json avec un chiffrement AES-256-GCM.
• Actualisés à l’expiration (si des tokens de rafraîchissement sont disponibles)
• Validés avant chaque tentative de connexion

[!WARNING] Par défaut, les tokens OAuth sont stockés non chiffrés sur le disque. Sur les machines partagées ou multi-utilisateurs, définissez QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true pour protéger les identifiants.

Utilisez la boîte de dialogue /mcp dans Qwen Code pour inspecter les serveurs MCP et gérer l’authentification de manière interactive.

Filtrage des outils (autoriser/refuser des outils par serveur)

Utilisez includeTools / excludeTools pour restreindre les outils exposés par un serveur (du point de vue de Qwen Code).

Exemple : inclure seulement quelques outils :

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      "timeout": 30000
    }
  }
}

Listes globales d’autorisation/refus

L’objet mcp dans votre settings.json définit les règles globales pour tous les serveurs MCP :

• mcp.allowed : liste d’autorisation des noms de serveurs MCP (clés dans mcpServers)
• mcp.excluded : liste de refus des noms de serveurs MCP

Les deux listes prennent en charge les motifs glob : * correspond à n’importe quelle séquence de caractères et ? correspond à un seul caractère (par exemple, "*puppeteer*" correspond à chaque serveur dont le nom contient puppeteer). Les entrées sans caractères glob sont mises en correspondance exacte. Lorsqu’un serveur correspond aux deux listes, mcp.excluded est prioritaire.

Exemple :

{
  "mcp": {
    "allowed": ["my-trusted-server", "*-internal"],
    "excluded": ["experimental-server"]
  }
}

Dépannage

• Le serveur affiche “Disconnected” dans qwen mcp list : vérifiez que l’URL/commande est correcte, puis augmentez le timeout.
• Le serveur Stdio ne démarre pas : utilisez un chemin absolu pour command, et vérifiez cwd/env.
• Les variables d’environnement dans le JSON ne se résolvent pas : assurez-vous qu’elles existent dans l’environnement où Qwen Code s’exécute (les environnements shell et application GUI peuvent différer).

Référence

Structure de settings.json

Configuration spécifique au serveur (mcpServers)

Ajoutez un objet mcpServers à votre fichier settings.json :

// ... le fichier contient d'autres objets de configuration
{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Propriétés de configuration :

Obligatoire (l’un des éléments suivants) :

Optionnel :

Gérer les serveurs MCP avec qwen mcp

Vous pouvez toujours configurer les serveurs MCP en modifiant manuellement settings.json, mais le CLI est généralement plus rapide.

Ajouter un serveur (qwen mcp add)

qwen mcp add [options] <name> <commandOrUrl> [args...]

Les flags --oauth-* s’appliquent uniquement à --transport sse et --transport http. Toute combinaison avec --transport stdio est rejetée.

Supprimer un serveur (qwen mcp remove)

qwen mcp remove <name>