Passer au contenu principal
Afficher en Markdown

Configuration

Ce guide fournit des renseignements détaillés sur la configuration des serveurs Model Context Protocol (MCP) avec Kiro, y compris la structure du fichier de configuration, la configuration des serveurs et leur gestion sur toutes les surfaces.

Structure du fichier de configuration

Les fichiers de configuration MCP utilisent le format JSON avec la structure suivante :

json
{ "mcpServers": { "local-server-name": { "command": "command-to-run-server", "args": ["arg1", "arg2"], "env": { "ENV_VAR1": "hard-coded-variable", "ENV_VAR2": "${EXPANDED_VARIABLE}" }, "disabled": false, "autoApprove": ["tool_name1", "tool_name2"], "disabledTools": ["tool_name3"] }, "remote-server-name": { "url": "https://endpoint.to.connect.to", "headers": { "HEADER1": "value1", "HEADER2": "value2" }, "disabled": false, "autoApprove": ["tool_name1", "tool_name2"], "disabledTools": ["tool_name3"] } } }

Propriétés de configuration

Serveur local

PropriétéTypeRequisDescription
commandStringOuiLa commande pour exécuter le serveur MCP
argsArrayNonArguments à passer à la commande
envObjectNonVariables d'environnement pour le processus du serveur
disabledBooleanNonIndique si le serveur est désactivé (par défaut : false)
autoApproveArrayNonNoms d'outils à approuver automatiquement sans demande (utilisez "*" pour approuver automatiquement tous les outils)
disabledToolsArrayNonNoms d'outils à omettre lors de l'appel de l'Agent

Serveur distant

PropriétéTypeRequisDescription
urlStringOuiPoint de terminaison HTTPS pour le serveur MCP distant (ou point de terminaison HTTP pour localhost)
headersObjectNonEn-têtes à transmettre au serveur MCP pendant la connexion
envObjectNonVariables d'environnement pour le processus du serveur
oauthObjectNonConfiguration OAuth pour les serveurs qui exigent une authentification (voir Configuration OAuth)
oauthScopesArrayNonPortées OAuth à demander. Voir Portées pour savoir quelle valeur Kiro utilise lorsque oauth.oauthScopes est aussi défini
disabledBooleanNonIndique si le serveur est désactivé (par défaut : false)
autoApproveArrayNonNoms d'outils à approuver automatiquement sans demande (utilisez "*" pour approuver automatiquement tous les outils)
disabledToolsArrayNonNoms d'outils à omettre lors de l'appel de l'Agent

Dans Kiro CLI, les deux types de serveurs acceptent aussi timeout, le délai d'attente de connexion en millisecondes; consultez la référence de configuration de l'agent. Les sessions Kiro CLI V2 acceptent aussi la graphie timeoutMs. Dans Kiro CLI 3.4.0 ou une version ultérieure, les sessions V3 acceptent aussi timeoutMs; lorsque les deux sont définis, timeout l'emporte et timeoutMs n'a aucun effet. Pour confirmer que la valeur s'applique, définissez "timeoutMs": 1 sur un serveur local lent dans une session V3; /mcp indique qu'il n'a pas réussi à démarrer dans le délai d'attente.

Emplacements de configuration

Vous pouvez configurer les serveurs MCP à deux niveaux :

  1. Niveau espace de travail : .kiro/settings/mcp.json

    • S'applique uniquement à l'espace de travail actuel
    • Idéal pour les serveurs MCP propres à un projet
  2. Niveau utilisateur : ~/.kiro/settings/mcp.json

    • S'applique globalement à tous les espaces de travail
    • Idéal pour les serveurs MCP que vous utilisez fréquemment

Si les deux fichiers existent, les configurations sont fusionnées, les paramètres de l'espace de travail ayant priorité.

Création des fichiers de configuration

Avec la palette de commandes :

  1. Ouvrez la palette de commandes (Cmd + Shift + P sur Mac, Ctrl + Shift + P sur Windows/Linux)
  2. Recherchez « MCP » et sélectionnez l'une de ces options :
    • Kiro: Open workspace MCP config (JSON) - Pour la configuration au niveau de l'espace de travail
    • Kiro: Open user MCP config (JSON) - Pour la configuration au niveau utilisateur

Avec le panneau Kiro :

  1. Ouvrez le panneau Kiro
  2. Sélectionnez l'icône Open MCP Config

Activation de la prise en charge de MCP

  1. Ouvrez les paramètres avec Cmd + , (Mac) ou Ctrl + , (Windows/Linux)
  2. Recherchez « MCP »
  3. Activez le paramètre de prise en charge de MCP

Application des changements

Les changements à la configuration MCP s'appliquent automatiquement lorsque vous enregistrez le fichier. Enregistrez le fichier de configuration (Cmd+S) et les serveurs se reconnecteront.

Priorité de chargement des serveurs MCP

Lorsque plusieurs configurations définissent le même serveur MCP, elles sont chargées selon cette hiérarchie (priorité la plus élevée à la plus faible) :

  1. Agent Config - champ mcpServers dans le JSON de l'agent
  2. Workspace MCP JSON - .kiro/settings/mcp.json
  3. Global MCP JSON - ~/.kiro/settings/mcp.json

Exemples de scénarios

Remplacement complet :

Agent config: { "fetch": { command: "fetch-v2" } } Workspace config: { "fetch": { command: "fetch-v1" } } Global config: { "fetch": { command: "fetch-old" } } Result: Only "fetch-v2" from agent config is used

Additif (noms différents) :

Agent config: { "fetch": {...} } Workspace config: { "git": {...} } Global config: { "aws": {...} } Result: All three servers are used (fetch, git, aws)

Désactivation par remplacement :

Agent config: { "fetch": { command: "...", disabled: true } } Workspace config: { "fetch": { command: "..." } } Result: No fetch server is launched

Exemples de configurations

Serveur local avec variables d'environnement

json
{ "mcpServers": { "web-search": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-bravesearch" ], "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" } } } }

Serveur distant avec en-têtes

json
{ "mcpServers": { "api-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_TOKEN}", "X-Custom-Header": "value" } } } }

Serveurs multiples

json
{ "mcpServers": { "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "git": { "command": "uvx", "args": ["mcp-server-git"], "env": { "GIT_CONFIG_GLOBAL": "/dev/null" } }, "aws-docs": { "command": "npx", "args": ["-y", "@aws/aws-documentation-mcp-server"] } } }

Variables d'environnement

De nombreux serveurs MCP exigent des variables d'environnement pour l'authentification ou la configuration. Utilisez la syntaxe ${VARIABLE_NAME} pour référencer des variables d'environnement :

json
{ "mcpServers": { "server-name": { "env": { "API_KEY": "${YOUR_API_KEY}", "DEBUG": "true", "TIMEOUT": "30000" } } } }

Pour des raisons de sécurité, Kiro ne développe que les variables d'environnement explicitement approuvées. Lorsque vous ajoutez ou modifiez une configuration de serveur MCP qui comprend des variables d'environnement non approuvées, Kiro affiche une fenêtre d'avertissement de sécurité énumérant les variables qui nécessitent une approbation.

Pour gérer les variables d'environnement approuvées :

  1. Ouvrez les paramètres de Kiro
  2. Recherchez « Mcp Approved Env Vars »
  3. Ajoutez les variables d'environnement que vous souhaitez autoriser pour le développement

Authentification OAuth

Les serveurs MCP distants qui exigent une authentification OAuth sont pris en charge. Kiro gère automatiquement le flux OAuth basé sur le navigateur lors de la connexion à un serveur protégé par OAuth.

json
{ "mcpServers": { "remote-server-with-oauth": { "url": "https://api.example.com/mcp", "oauth": { "clientId": "your-client-id", "redirectUri": "http://127.0.0.1:8080/oauth/callback", "oauthScopes": ["read", "write"] } } } }

Si vous rencontrez des erreurs de portée OAuth, utilisez un tableau vide : "oauthScopes": []

La plupart des serveurs utilisent l'enregistrement dynamique de client (DCR) et n'ont besoin d'aucune configuration supplémentaire - connectez-vous simplement, et Kiro ouvre la page d'autorisation.

Configuration OAuth

Pour les serveurs qui ne prennent pas en charge l'enregistrement dynamique de client (DCR) - comme Figma, Slack ou GitHub - vous pouvez fournir vos propres identifiants OAuth dans l'objet oauth. Cela fonctionne avec des serveurs d'authentification comme Cognito, Auth0 et Okta.

json
{ "mcpServers": { "figma": { "url": "https://mcp.figma.com/mcp", "oauth": { "clientId": "my-figma-client-id", "clientSecret": "my-figma-client-secret", "redirectUri": "http://localhost:7778/oauth/callback", "oauthScopes": ["files:read"] } } } }

Pour utiliser cette configuration, enregistrez une application OAuth dans la console des développeurs Figma. Définissez l'URI de redirection dans les paramètres de votre application à http://localhost:7778/oauth/callback - le port et le chemin doivent correspondre exactement. Figma exige un client confidentiel, donc clientId et clientSecret sont tous les deux nécessaires.

Propriétés OAuth

PropriétéTypeRequisDescription
oauth.clientIdStringNonID de client OAuth préenregistré. Lorsqu'il est défini, l'enregistrement dynamique de client est entièrement ignoré.
oauth.clientSecretStringNonSecret client pour les serveurs qui en exigent un. N'a de sens qu'avec clientId.
oauth.redirectUriStringNonURI de redirection en boucle locale personnalisée pour le rappel OAuth. Voir formats d'URI de redirection ci-dessous.
oauth.clientMetadataUrlStringNonURL HTTPS d'un document de métadonnées d'ID client hébergé. Lorsqu'elle est définie, Kiro s'authentifie en tant que cette URL au lieu d'enregistrer un client. Voir Documents de métadonnées d'ID client ci-dessous.
oauth.oauthScopesArrayNonPortées OAuth à demander au serveur d'autorisation. Voir Portées pour savoir quelle valeur Kiro utilise lorsque le oauthScopes de premier niveau est aussi défini.

Fonctionnement

  • clientId ou clientMetadataUrl non défini - Kiro tente un enregistrement dynamique de client avec le serveur. Si le DCR échoue, il se replie sur une configuration de client par défaut. Dans Kiro CLI 3.2.0 ou une version ultérieure et Kiro IDE 1.4.178 ou une version ultérieure, lorsque le serveur d'autorisation prend en charge les documents de métadonnées d'ID client et n'offre aucun point de terminaison d'enregistrement, Kiro se connecte plutôt avec son propre document hébergé. Voir Documents de métadonnées d'ID client ci-dessous.
  • clientId défini (sans clientSecret) - Kiro ignore le DCR et s'authentifie comme un client OAuth public en utilisant votre ID de client enregistré.
  • clientId et clientSecret définis tous les deux (CLI seulement) - Kiro ignore le DCR et s'authentifie comme un client confidentiel, en envoyant le secret au point de terminaison des jetons. Cela est requis pour des serveurs comme Figma qui n'émettent des jetons qu'à des clients confidentiels.
  • clientMetadataUrl défini (sans clientId) - Kiro ignore le DCR et présente l'URL du document de métadonnées comme son identité de client, lorsque le serveur d'autorisation le prend en charge. Voir Documents de métadonnées d'ID client ci-dessous.

Si vous apportez votre propre fournisseur d'identité, votre serveur MCP doit fournir les métadonnées du serveur d'autorisation à l'URL de découverte RFC 8414 et valider les jetons Bearer par rapport aux JWKS du fournisseur. Pour un émetteur sans chemin tel que https://auth.example.com, les métadonnées se trouvent à https://auth.example.com/.well-known/oauth-authorization-server. Pour un émetteur avec chemin tel que https://auth.example.com/tenant1, le suffixe de découverte est inséré avant le chemin, ce qui donne https://auth.example.com/.well-known/oauth-authorization-server/tenant1.

Formats d'URI de redirection

Le champ redirectUri accepte plusieurs formats. L'hôte doit être 127.0.0.1 ou localhost, et le schéma doit être http (le rappel est servi par un serveur en boucle locale local).

FormatExempleDescription
URL complètehttp://localhost:7778/oauth/callbackFixe le port et le chemin pour correspondre à une application préenregistrée
Hôte et port127.0.0.1:7778Fixe le port; le chemin est par défaut /oauth/callback
Port seulement:7778Fixe le port sur 127.0.0.1; le chemin est par défaut /oauth/callback
Omis(non défini)Le système d'exploitation attribue un port disponible aléatoire sur localhost. Le chemin est /oauth/callback, sauf que dans Kiro IDE 1.4.215 ou une version ultérieure, il est /kiro-mcp/oauth/callback lorsque Kiro s'enregistre ou s'identifie lui-même

Utilisez une URL complète avec un chemin personnalisé lorsque votre application OAuth a un URI de redirection préenregistré qui comprend un chemin de rappel particulier. La valeur que vous configurez est exactement le redirect_uri que Kiro envoie et le seul point de terminaison auquel son serveur local répond : enregistrez donc la même valeur auprès de votre fournisseur - y compris l'orthographe de l'hôte, car localhost et 127.0.0.1 ne sont pas interchangeables pour la plupart des serveurs d'autorisation.

Lorsque vous ne définissez ni clientId, ni clientMetadataUrl, ni redirectUri, Kiro organise lui-même la connexion par l'enregistrement dynamique de client ou par son propre document de métadonnées d'ID client hébergé. Dans Kiro IDE 1.4.215 ou une version ultérieure, ce rappel utilise le chemin /kiro-mcp/oauth/callback, propre à Kiro, et le serveur local de Kiro répond seulement au chemin utilisé pour cette connexion; les versions antérieures de l'IDE et Kiro CLI 3.4.0 utilisent /oauth/callback. Dans Kiro IDE 1.4.215 ou une version ultérieure, un client qu'une version antérieure a enregistré par l'enregistrement dynamique de client est enregistré de nouveau à la prochaine connexion dans le navigateur dont il a besoin; le rafraîchissement du jeton continue de fonctionner entre-temps.

Un redirectUri que Kiro ne peut pas servir est signalé comme une erreur de configuration sur le serveur plutôt qu'ignoré : le port doit être présent et compris entre 1 et 65535, l'hôte doit être 127.0.0.1 ou localhost, le schéma doit être http, et la valeur ne peut pas comporter de chaîne de requête ni de fragment.

Documents de métadonnées d'ID client (CIMD)

Si vous hébergez un document de métadonnées d'ID client, définissez oauth.clientMetadataUrl à son URL HTTPS. Au lieu d'enregistrer un client au moyen du DCR, Kiro présente cette URL comme son identité de client, et le serveur d'autorisation récupère votre document pour connaître les métadonnées du client. Cela ne fonctionne que lorsque le serveur d'autorisation annonce client_id_metadata_document_supported; sinon, Kiro se replie sur le DCR.

json
{ "mcpServers": { "enterprise-server": { "url": "https://mcp.example.com/mcp", "oauth": { "clientMetadataUrl": "https://apps.example.com/kiro-client.json", "redirectUri": "http://127.0.0.1:8080/oauth/callback" } } } }

Ne définissez pas à la fois clientMetadataUrl et clientId. Lorsqu'un clientId est présent, Kiro l'utilise et ne consulte jamais clientMetadataUrl.

Dans Kiro CLI 3.2.0 ou une version ultérieure et Kiro IDE 1.4.178 ou une version ultérieure, vous n'avez besoin d'aucun bloc oauth pour un serveur dont le serveur d'autorisation prend en charge les documents de métadonnées d'ID client et n'offre aucun point de terminaison d'enregistrement, comme le MCP hébergé de Tableau. Kiro se connecte avec son propre document hébergé, https://kiro.dev/oauth/client-metadata.json. Dans Kiro IDE 1.4.215 ou une version ultérieure, ce rappel utilise le chemin /kiro-mcp/oauth/callback; les versions antérieures de l'IDE et Kiro CLI 3.4.0 utilisent /oauth/callback. Le document liste les deux chemins sur localhost et 127.0.0.1, sans port : http://localhost/kiro-mcp/oauth/callback, http://127.0.0.1/kiro-mcp/oauth/callback, http://localhost/oauth/callback et http://127.0.0.1/oauth/callback. Cela fonctionne seulement lorsque le serveur d'autorisation accepte n'importe quel port sur un rappel localhost. Un serveur qui exige une correspondance exacte des ports rejette le port aléatoire qu'utilise le rappel de Kiro. Un serveur qui offre l'enregistrement dynamique de client continue de l'utiliser, et un clientId ou un clientMetadataUrl configuré garde la priorité.

Portées

Vous pouvez spécifier des portées OAuth à deux endroits :

json
{ "mcpServers": { "server": { "url": "https://mcp.example.com", "oauthScopes": ["openid", "email"], "oauth": { "clientId": "my-id", "oauthScopes": ["read:data", "write:data"] } } } }

La valeur que Kiro utilise lorsque les deux sont définis dépend du client. Dans les sessions Kiro CLI V2, oauth.oauthScopes a priorité. Dans les sessions Kiro CLI V3 de Kiro CLI 3.4.0 ou une version ultérieure, et dans Kiro IDE 1.4.215 ou une version ultérieure, le oauthScopes de premier niveau a priorité. Kiro lit oauth.oauthScopes, puis oauth.scopes, seulement lorsque le oauthScopes de premier niveau n'est pas défini. Dans Kiro CLI V3 avant la version 3.4.0, Kiro ignorait la valeur imbriquée. Pour demander les mêmes portées d'un client et d'une version à l'autre, définissez seulement l'une des deux valeurs. Pour confirmer quelle valeur a été appliquée, connectez le serveur et vérifiez le paramètre scope dans l'URL d'autorisation que Kiro ouvre. Lorsque ni l'un ni l'autre n'est spécifié, Kiro demande un ensemble par défaut de portées (openid, email, profile, offline_access).

Rafraîchissement du jeton en cours de session

Lorsqu'un jeton OAuth expire pendant une session et qu'aucun jeton de rafraîchissement n'est disponible, Kiro déclenche automatiquement un nouveau flux d'authentification basé sur le navigateur. Vous n'avez pas besoin de redémarrer votre session - la réauthentification se produit de façon transparente et le serveur MCP se reconnecte avec le nouveau jeton. Dans l'IDE, un indicateur d'avertissement et un bouton Re-authenticate apparaissent dans le panneau MCP lorsqu'un jeton expire.

Ceci est particulièrement utile pour les fournisseurs d'identité qui émettent des jetons de courte durée sans jetons de rafraîchissement.

Gestion des identifiants (CLI)

Lorsque le rafraîchissement automatique n'est pas suffisant - par exemple, si un jeton a été révoqué ou que vous devez changer de compte - vous pouvez gérer les identifiants OAuth manuellement dans la CLI :

CommandeRaccourci clavierDescription
/mcp auth^AForce la réauthentification lorsqu'un jeton est expiré ou invalide
/mcp cancel-auth^XInterrompt un flux d'authentification en attente bloqué en attendant la confirmation du navigateur
/mcp logout^RSupprime les identifiants stockés pour un serveur

Les raccourcis clavier sont disponibles dans la vue d'état du panneau MCP. Voir Slash Commands pour tous les détails d'utilisation.

Rechargement à chaud

Les configurations d'agent et de MCP se rechargent à chaud lorsque vous enregistrez des changements sur le disque. Un observateur de fichiers surveille les répertoires .kiro/agents et les fichiers mcp.json, en réconciliant les serveurs en cours d'exécution et l'état de l'agent sans redémarrer votre session ni perdre le contexte de la conversation.

Cela s'applique à :

  • La modification d'une configuration d'agent existante ou d'un mcp.json
  • L'ajout ou la suppression d'un fichier d'agent
  • L'ajout, la suppression ou la modification d'entrées de serveur MCP

Fonctionnement de la réconciliation :

  • Seuls les serveurs modifiés redémarrent - si vous ajoutez, supprimez ou modifiez une entrée de serveur, seuls les serveurs touchés sont arrêtés ou démarrés. Les serveurs inchangés continuent de fonctionner.
  • Diff de configuration indépendant de l'ordre - réordonner les variables d'environnement ou les clés JSON ne compte pas comme un changement et ne déclenchera pas de redémarrage.
  • Serveurs injectés en session préservés - les serveurs ajoutés en cours de session par /mcp add sont refusionnés pendant la réconciliation.

Aucune commande n'est requise pour déclencher un rechargement. Enregistrez le fichier et le changement prend effet à la prochaine limite d'inactivité (entre les tours).

Désactivation des serveurs et des outils

Pour désactiver temporairement un serveur MCP sans supprimer sa configuration, définissez disabled à true :

json
{ "mcpServers": { "server-name": { "disabled": true } } }

Pour garder un serveur actif tout en empêchant un agent d'utiliser des outils particuliers, utilisez disabledTools :

json
{ "mcpServers": { "server-name": { "disabledTools": ["delete_file", "execute_command"] } } }

Registre MCP (entreprise)

Pour les équipes d'entreprise utilisant IAM Identity Center, l'accès aux serveurs MCP peut être contrôlé de façon centralisée par un registre MCP. Voir la page MCP Registry pour les détails.

Dépannage de la configuration

  1. Valider la syntaxe JSON

    • Assurez-vous que votre JSON est valide sans erreurs de syntaxe
    • Vérifiez les virgules, guillemets ou délimiteurs manquants
    • Utilisez un validateur ou un linter JSON
  2. Vérifier les chemins de commande

    • Assurez-vous que la commande spécifiée existe dans votre PATH
    • Essayez d'exécuter la commande directement dans votre terminal
  3. Vérifier les variables d'environnement

    • Vérifiez que toutes les variables d'environnement requises sont définies
    • Vérifiez les fautes de frappe dans les noms de variables d'environnement
  4. Incompatibilité d'émetteur OAuth

    • Si un serveur protégé par OAuth ne parvient pas à se connecter, l'URL du serveur d'autorisation annoncée par votre serveur MCP peut ne pas correspondre exactement à la valeur issuer dans les métadonnées du serveur d'autorisation.
    • Récupérez /.well-known/oauth-protected-resource depuis votre serveur MCP. Notez l'URL dans authorization_servers[0].
    • Récupérez les métadonnées du serveur d'autorisation pour cette URL d'émetteur. Conformément à la RFC 8414, pour un émetteur sans chemin (p. ex. https://auth.example.com), le point de terminaison des métadonnées est https://auth.example.com/.well-known/oauth-authorization-server; pour un émetteur avec chemin (p. ex. https://auth.example.com/tenant1), il est https://auth.example.com/.well-known/oauth-authorization-server/tenant1. Comparez le champ issuer retourné avec authorization_servers[0], caractère par caractère : le schéma, l'hôte, le port, le chemin et la barre oblique de fin doivent être identiques. Par exemple, https://auth.example.com et https://auth.example.com/ sont traités comme des émetteurs différents.
    • Corrigez la source de métadonnées qui contient la valeur incorrecte. N'ajoutez pas de normalisation côté client ni de contournement.
  5. Transmettre des arguments aux serveurs stdio de Kiro CLI V2 sous Windows

    • Dans les sessions Kiro CLI V2, les arguments sont transmis sans modification lorsqu'une commande se résout sur PATH en un fichier .exe, .com, .bat ou .cmd.
    • Les autres commandes, ainsi que les serveurs dont le env définit PATHEXT, sont toujours lancés au moyen de cmd.exe.
    • Les serveurs résolus directement n'exécutent pas le mécanisme AutoRun de cmd.exe. Si AutoRun définit PATH, ajoutez plutôt cette valeur à la configuration env du serveur.
    • Un argument contenant un saut de ligne fait échouer le lancement d'un .bat ou d'un .cmd au lieu de tronquer l'argument.
  6. Examiner le chargement de la configuration

    • Vérifiez quels fichiers de configuration sont chargés et leur priorité :
    bash
    # Check workspace config cat .kiro/settings/mcp.json # Check user config cat ~/.kiro/settings/mcp.json

Considérations de sécurité

Lors de la configuration des serveurs MCP, suivez ces bonnes pratiques de sécurité :

  • Utilisez des références de variables d'environnement (p. ex., ${API_TOKEN}) plutôt que de codifier en dur les valeurs sensibles
  • Ne versionnez jamais de fichiers de configuration contenant des identifiants
  • Ne connectez-vous qu'à des serveurs distants de confiance
  • Examinez les permissions des outils avant de les ajouter à autoApprove
  • Utilisez disabledTools pour restreindre l'accès aux opérations dangereuses

Pour des directives de sécurité complètes, voir la page MCP Security Best Practices.

Page mise à jour : 17 novembre 2026