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.

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

{
  "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"]
    }
  }
}

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

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

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

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

{
  "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"]
    }
  }
}

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 :

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

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.

{
  "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.

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.

{
  "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.

• clientId 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.
• 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.

Si vous apportez votre propre fournisseur d'identité, votre serveur MCP doit servir un document de métadonnées /.well-known/oauth-authorization-server pointant vers les points de terminaison du fournisseur, et valider les jetons Bearer par rapport aux JWKS du fournisseur.

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).

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.

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

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

Lorsque les deux sont définis, oauth.oauthScopes a priorité. 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).

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.

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 :

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

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).

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

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

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

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

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.

1. Valider la syntaxe JSON

   • Assurez-vous que votre JSON est valide sans erreurs de syntaxe
   • Vérifiez les virgules, guillemets ou crochets 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. 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
   

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.