AgentCore Gateway vers serveur MCP

Le générateur connection peut enregistrer un serveur MCP (soit TypeScript soit Python) comme cible d’une AgentCore Gateway.

Une fois connectée, la Gateway agrège les outils du serveur MCP dans son point de terminaison MCP unique, évalue les appels par rapport à son moteur de politique Cedar, et signe le trafic sortant vers le serveur MCP avec IAM SigV4.

Prérequis

Avant d’utiliser ce générateur, assurez-vous d’avoir :

Un projet agentcore-gateway
Un composant serveur MCP (ts#mcp-server ou py#mcp-server) créé avec infra: agentcore et auth: iam

La Gateway doit avoir protocol: mcp et le serveur MCP doit avoir auth: iam — le générateur valide les deux. Les serveurs MCP non-IAM ne peuvent pas être attachés car la Gateway signe le trafic sortant avec SigV4.

Utilisation

Exécuter le générateur

Exécuter ce générateur@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
Ouvrez la console Nx dans VSCode
Cliquez sur Generate (UI) dans la section "Common Nx Commands"
Recherchez @aws/nx-plugin - connection
Remplissez les paramètres requis
Cliquez sur Generate

Composez votre commande5

sourceProjectRequis

targetProjectRequis

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Sélectionnez le projet Gateway comme source et le projet serveur MCP comme cible. Si le projet serveur MCP contient plusieurs composants, spécifiez targetComponent pour lever l’ambiguïté.

Options

Options du générateur5 options

sourceProjectRequisstring: Le projet source
targetProjectRequisstring: Le projet cible auquel se connecter
sourceComponentstring: Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant de générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponentstring: Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant de générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.
preferInstallDependenciesbooleanPar défaut: true: Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur relie les projets existants ensemble plutôt que d’émettre de nouveaux fichiers source. Les fichiers suivants sont modifiés :

Répertoirepackages/<gateway>
- project.json la cible dev de la Gateway gagne une dépendance sur le <mcp>-dev du serveur MCP
- local-dev.ts ATTACHED_MCP_SERVERS mis à jour pour que la gateway locale agrège le serveur MCP

La cible dev du projet Gateway gagne une dépendance sur la cible <mcp>-dev du serveur MCP, donc l’exécution de la Gateway localement démarre également le serveur MCP. Le serveur MCP est également enregistré dans le local-dev.ts du projet Gateway pour que la gateway locale agrège ses outils.

Ajouter la cible serveur MCP à votre stack

Le générateur ne peut pas automatiquement relier la cible serveur MCP dans votre infrastructure car il ne sait pas quelle stack ou quel module instancie la Gateway. Ajoutez vous-même un seul appel à gateway.addMcpServer(server).

CDK
Terraform

Dans la stack où vous instanciez la Gateway, enregistrez le serveur MCP comme cible :

const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the MCP server as a target of the Gateway. The target name
// defaults to the MCP server's `mcpServerName` (its class name in
// kebab-case, e.g. `MyMcpServer` -> `my-mcp-server`).
myGateway.addMcpServer(myMcpServer);

Le nom de cible de la Gateway (le mcpServerName du serveur MCP par défaut) est utilisé comme préfixe pour les noms d’action Cedar — le format d’action est AgentCore::Action::"<targetName>___<toolName>". Voir la section Rédaction de politiques. Gardez le nom de cible court et stable ; le changer ultérieurement invalide toutes les politiques Cedar qui référencent l’ancien nom.

Pour remplacer le nom de cible par défaut, passez gatewayTargetName :

myGateway.addMcpServer(myMcpServer, { gatewayTargetName: 'my-mcp' });

Le construct configure la cible avec iamCredentialProvider.service = 'bedrock-agentcore' pour que la Gateway signe les appels sortants en utilisant son propre rôle d’exécution.

Dans le fichier Terraform où vous instanciez la Gateway, reliez la cible serveur MCP :

module "my_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
}

module "my_gateway" {
  source              = "../../common/terraform/src/app/gateways/my-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

# Register the MCP server as a target of the Gateway
resource "aws_bedrockagentcore_gateway_target" "my_mcp_server" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-mcp-server"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = module.my_mcp_server.invocation_url
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

Le name de la cible (my-mcp-server ci-dessus) est utilisé comme préfixe pour les noms d’action Cedar — voir la section Rédaction de politiques. policy_dependencies garantit que les politiques Cedar référençant les actions de cette cible sont créées après que la cible les a enregistrées.

Développement local

L’exécution de la Gateway localement avec :

pnpm nx dev <gateway-name>

yarn nx dev <gateway-name>

npx nx dev <gateway-name>

bunx nx dev <gateway-name>

démarre une gateway locale plus chaque serveur MCP attaché sur son port local assigné. La gateway locale expose un point de terminaison MCP unique qui agrège les outils des serveurs attachés. Les agents connectés à la Gateway via les générateurs de connexion gateway TypeScript ou Python pointent vers elle lors de l’exécution avec LOCAL_DEV=true.

Le développement local utilise une gateway de substitution locale — un agrégateur MCP léger démarré par le projet Gateway, et non le service AgentCore Gateway. En conséquence, les politiques Cedar ne sont pas évaluées localement. Chaque agent voit chaque outil sur chaque serveur MCP attaché. Pour exercer les politiques Cedar, exécutez plutôt la cible serve de l’agent (voir les guides de connexion agent TypeScript / Python) pour que l’agent s’exécutant localement appelle la Gateway déployée.

Les noms d’outils sont toujours préfixés localement comme <target-name>___<tool-name> pour correspondre à l’espacement de noms de la Gateway déployée, de sorte que le prompt système d’un agent et les noms d’action Cedar que vous référencez restent cohérents entre les exécutions locales et déployées.