Agent Python vers MCP

Le générateur connection peut connecter votre Agent Python à 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 Python avec un composant Agent Python (Strands ou LangChain)
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

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

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

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

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 crée un projet Python partagé agent_connection dans packages/common/agent_connection/ (s’il n’existe pas déjà). Les modules clients par connexion sont générés dans ce projet partagé :

• Répertoirepackages/common/agent_connection

  • Répertoire<scope>_agent_connection

    • __init__.py Ré-exporte les clients par connexion
    • Répertoirecore

      • agentcore_endpoints.py Résolution ARN/URL indépendante du framework
      • agentcore_mcp_transport.py Transport MCP indépendant du framework
      • agentcore_mcp_client_<framework>.py Client MCP encapsulant le transport pour le framework de votre agent
      • Répertoireauth/ httpx.Auth SigV4 / transfert de session indépendant du framework

        • …
    • Répertoireapp

      • <mcp_server_name>_client_<framework>.py Client par connexion pour chaque serveur MCP

Le suffixe du client correspond au framework de votre agent (_strands ou _langchain).

De plus, le générateur :

• Transforme le fichier agent.py de votre agent pour importer et utiliser les outils du serveur MCP via un client basé sur une classe
• Ajoute le projet agent_connection comme dépendance d’espace de travail de votre projet d’agent
• Met à jour la cible dev de l’agent pour dépendre de la cible serve du serveur MCP

Utiliser le serveur MCP connecté

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

Strands

packages/my-project/my_module/agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyMcpServerClientStrands

@contextmanager
def get_agent():
    my_mcp_server = MyMcpServerClientStrands.create()
    with (
        my_mcp_server,
    ):
        yield Agent(
            system_prompt="...",
            tools=[*my_mcp_server.list_tools_sync()],
        )

Le client Strands est un gestionnaire de contexte, entré dans un bloc with autour de l’agent.

LangChain

packages/my-project/my_module/agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyMcpServerClientLangChain

def get_agent():
    my_mcp_server = MyMcpServerClientLangChain.create()
    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[*my_mcp_server],
    )

Le client LangChain retourne une liste d’outils chargés via langchain-mcp-adapters. Chaque outil ouvre une nouvelle session MCP par appel, de sorte que les outils restent utilisables pendant toute la durée de vie de l’agent — aucun bloc with n’est nécessaire.

L’ID de session AgentCore est propagé automatiquement au serveur MCP via l’en-tête X-Amzn-Bedrock-AgentCore-Runtime-Session-Id pour les deux frameworks, garantissant la cohérence pour Bedrock AgentCore Observability.

Infrastructure

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

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:InvokeAgent"
      Resource = 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.