Agent TypeScript vers MCP

Le générateur connection peut connecter votre Agent TypeScript à un serveur MCP (soit TypeScript soit Python).

Le générateur configure tout le câblage nécessaire pour que votre agent puisse découvrir et invoquer les outils du serveur MCP, à la fois lorsqu’il est déployé sur AWS (via Bedrock AgentCore) et lors de l’exécution locale.

Prérequis

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

1. Un projet TypeScript avec un composant Strands Agent
2. Un projet avec un composant serveur MCP (soit ts#mcp-server soit py#mcp-server)
3. Les deux composants créés avec infra: agentcore

Utilisation

Exécuter le générateur

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

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

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

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 votre projet d’agent comme source et votre projet de serveur MCP comme cible. Si vos projets contiennent plusieurs composants, spécifiez les options sourceComponent et 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 crée un package partagé agent-connection et modifie le code de votre agent :

• Répertoirepackages/common/agent-connection

  • Répertoiresrc

    • Répertoireapp

      • <mcp-server-name>-client-strands.ts Client Strands de haut niveau pour le serveur MCP connecté
    • Répertoirecore

      • agentcore-endpoints.ts Résolution ARN/URL indépendante du framework
      • agentcore-fetch.ts Fetch SigV4 / JWT / session-forwarding indépendant du framework
      • agentcore-transport.ts Plomberie de transport AgentCore partagée
      • agentcore-mcp-transport.ts Transport MCP indépendant du framework
      • agentcore-mcp-client-strands.ts Client MCP Strands encapsulant le transport
    • index.ts Exporte tous les clients
  • project.json
  • tsconfig.json

De plus, il :

• Transforme le fichier agent.ts de votre agent pour importer et utiliser les outils du serveur MCP
• Met à jour la cible dev de l’agent pour dépendre de la cible serve du serveur MCP
• Installe les dépendances requises

Utiliser le serveur MCP connecté

Le générateur transforme le fichier agent.ts de votre agent pour utiliser les outils du serveur MCP :

packages/example/src/my-agent/agent.ts

import { Agent, tool } from '@strands-agents/sdk';
import { MyMcpServerClientStrands } from '@my-scope/agent-connection';

export const getAgent = async () => {
  const myMcpServerClient = await MyMcpServerClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myMcpServerClient],
  });
};

L’ID de session AgentCore est propagé automatiquement au serveur MCP via l’en-tête X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, donc create() ne prend aucun argument : le serveur de l’agent lie la session de la requête entrante dans un contexte AsyncLocalStorage (enterSessionContext dans le router.ts généré, ou runWithSessionId dans le middleware de session A2A/AG-UI), et le fetch du client de connexion dans agentcore-fetch.ts l’appose sur chaque appel sortant — garantissant la cohérence pour l’observabilité Bedrock AgentCore.

Infrastructure

Projet d’infrastructure requis

Les générateurs d’agent, de serveur MCP et de Gateway fournissent leurs constructs et modules dans packages/common, mais ils ne créent pas d’application pour les déployer — donc packages/infra n’existe pas tant que vous ne le générez pas. Exécutez le générateur ts#infra (CDK) ou le générateur terraform#project (Terraform) avant de modifier le fichier ci-dessous.

CDK

Après avoir exécuté le générateur de connexion, vous devez accorder à l’agent la permission d’invoquer le serveur MCP :

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

const mcpServer = new MyMcpServer(this, 'MyMcpServer');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the MCP server
mcpServer.grantInvokeAccess(myAgent);

grantInvokeAccess configure les actions d’invocation AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeForUser et InvokeAgentRuntimeWithWebSocketStream) sur l’ARN du runtime du serveur MCP.

L’ARN du runtime AgentCore du serveur MCP est automatiquement enregistré dans l’espace de noms agentcore de la Configuration d’exécution par la construction CDK générée, afin que l’agent puisse le découvrir au moment de l’exécution.

Terraform

Après avoir exécuté le générateur de connexion, vous devez accorder à l’agent la permission d’invoquer le serveur MCP dans votre configuration Terraform :

packages/infra/src/main.tf

module "inventory_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
}

module "story_agent" {
  source = "../../common/terraform/src/app/agents/story-agent"
}

# Grant the agent permissions to invoke the MCP server
resource "aws_iam_policy" "agent_invoke_mcp" {
  name = "AgentInvokeMcpPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.inventory_mcp_server.agent_core_runtime_arn,
        "${module.inventory_mcp_server.agent_core_runtime_arn}/*",
      ]
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
  role       = module.story_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
}

L’ARN du runtime AgentCore du serveur MCP est automatiquement enregistré dans l’espace de noms agentcore de la Configuration d’exécution par le module Terraform généré, afin que l’agent puisse le découvrir au moment de l’exécution.

Développement local

Le générateur configure la cible dev de l’agent pour :

1. Démarrer automatiquement le(s) serveur(s) MCP connecté(s)
2. Définir LOCAL_DEV=true afin que le client généré utilise le transport HTTP direct au lieu d’AgentCore

Exécutez l’agent localement avec :

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

Cela démarrera à la fois l’agent et tous les serveurs MCP connectés, l’agent se connectant aux serveurs MCP directement via HTTP sur leurs ports locaux assignés.