Passerelle AgentCore vers serveur MCP

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

Une fois connectée, la passerelle 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 :

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

La passerelle 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 passerelle signe le trafic sortant avec SigV4.

Utilisation

Exécuter le générateur

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

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

Options

Paramètre	Type	Par défaut	Description
sourceProject Requis	string	-	Le projet source
targetProject Requis	string	-	Le projet cible auquel se connecter
sourceComponent	string	-	Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponent	string	-	Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.
preferInstallDependencies	boolean	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 <gateway>-dev gagne une dépendance sur le <mcp>-dev du serveur MCP
  • local-dev.ts ATTACHED_MCP_SERVERS mis à jour pour que la passerelle locale agrège le serveur MCP

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

Ajouter la cible du serveur MCP à votre stack

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

CDK

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

packages/infra/src/stacks/application-stack.ts

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 passerelle (l’id de la construction en kebab-case 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' });

La construction configure la cible avec iamCredentialProvider.service = 'bedrock-agentcore' afin que la passerelle signe les appels sortants en utilisant son propre rôle d’exécution.

Terraform

Dans le fichier Terraform où vous instanciez la passerelle, câblez la cible du serveur MCP :

packages/infra/src/main.tf

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 = "https://bedrock-agentcore.${local.aws_region}.amazonaws.com/runtimes/${urlencode(module.my_mcp_server.agent_core_runtime_arn)}/invocations?qualifier=DEFAULT"
      }
    }
  }

  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 a enregistré ces actions.

Développement local

L’exécution de la passerelle localement avec :

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

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

Fidélité locale

Le développement local utilise une passerelle de substitution locale — un agrégateur MCP léger démarré par le projet de passerelle, et non le service de passerelle AgentCore. En conséquence, les politiques Cedar ne sont pas évaluées localement. Chaque agent voit tous les outils 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 d’agent TypeScript / Python) afin que l’agent s’exécutant localement appelle la passerelle 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 passerelle déployée, de sorte que l’invite 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.

les exécutions locales et déployées. :::