Agente Python a MCP

El generador connection puede conectar tu Agente Python a un servidor MCP (ya sea TypeScript o Python).

El generador configura todo el cableado necesario para que tu agente pueda descubrir e invocar las herramientas del servidor MCP, tanto cuando se despliega en AWS (a través de Bedrock AgentCore) como cuando se ejecuta localmente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto Python con un componente Agente Python (Strands o LangChain)
2. Un proyecto con un componente servidor MCP (ya sea ts#mcp-server o py#mcp-server)
3. Ambos componentes creados con infra: agentcore

Uso

Ejecutar el generador

Ejecute este generador@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. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando5

sourceProjectRequerido

targetProjectRequerido

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Selecciona tu proyecto de agente como origen y tu proyecto de servidor MCP como destino. Si tus proyectos contienen múltiples componentes, especifica las opciones sourceComponent y targetComponent para desambiguar.

Opciones

Opciones del generador5 opciones

sourceProjectRequeridostring

El proyecto de origen

targetProjectRequeridostring

El proyecto de destino al que conectar

sourceComponentstring

El componente de origen desde el cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como origen.

targetComponentstring

El componente de destino al cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como destino.

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador crea un proyecto Python compartido agent_connection en packages/common/agent_connection/ (si no existe ya). Los módulos cliente por conexión se generan en este proyecto compartido:

• Directoriopackages/common/agent_connection

  • Directorio<scope>_agent_connection

    • __init__.py Re-exporta clientes por conexión
    • Directoriocore

      • __init__.py Inicialización del paquete Python
      • agentcore_endpoints.py Resolución de ARN/URL independiente del framework
      • agentcore_transport.py Infraestructura de transporte AgentCore compartida
      • agentcore_mcp_transport.py Transporte MCP independiente del framework
      • agentcore_mcp_client_<framework>.py Cliente MCP que envuelve el transporte para el framework de tu agente
      • Directorioauth/ httpx.Auth independiente del framework para SigV4 / reenvío de sesión

        • …
    • Directorioapp

      • __init__.py Inicialización del paquete Python
      • <mcp_server_name>_client_<framework>.py Cliente por conexión para cada servidor MCP

El sufijo del cliente coincide con el framework de tu agente (_strands o _langchain).

Además, el generador:

• Transforma el agent.py de tu agente para importar y usar las herramientas del servidor MCP a través de un cliente basado en clases
• Agrega el proyecto agent_connection como una dependencia de workspace de tu proyecto de agente
• Actualiza el target dev del agente para depender del target serve del servidor MCP

Usar el servidor MCP conectado

El generador transforma el agent.py de tu agente para usar las herramientas del servidor 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()],
        )

El cliente Strands es un administrador de contexto, ingresado en un bloque with alrededor del agente.

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],
    )

El cliente LangChain devuelve una lista de herramientas cargadas a través de langchain-mcp-adapters. Cada herramienta abre una sesión MCP nueva por llamada, por lo que las herramientas permanecen utilizables durante la vida del agente — no se necesita un bloque with.

El ID de sesión de AgentCore se propaga automáticamente al servidor MCP a través del encabezado X-Amzn-Bedrock-AgentCore-Runtime-Session-Id para ambos frameworks, asegurando consistencia para Bedrock AgentCore Observability.

Infraestructura

Proyecto de infraestructura requerido

Los generadores de agente, servidor MCP y Gateway envían sus constructos y módulos a packages/common, pero no crean una aplicación desde la cual desplegarlos — por lo que packages/infra no existe hasta que lo generes. Ejecuta el generador ts#infra (CDK) o el generador terraform#project (Terraform) antes de editar el archivo a continuación.

CDK

Después de ejecutar el generador de conexión, necesitas otorgar al agente permiso para invocar el servidor 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 conecta las acciones de invocación de AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeForUser e InvokeAgentRuntimeWithWebSocketStream) en el ARN del runtime del servidor MCP.

El ARN del runtime AgentCore del servidor MCP se registra automáticamente en el namespace agentcore de Runtime Configuration por el constructo CDK generado, para que el agente pueda descubrirlo en tiempo de ejecución.

Terraform

Después de ejecutar el generador de conexión, necesitas otorgar al agente permiso para invocar el servidor MCP en tu configuración de 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
}

El ARN del runtime AgentCore del servidor MCP se registra automáticamente en el namespace agentcore de Runtime Configuration por el módulo Terraform generado, para que el agente pueda descubrirlo en tiempo de ejecución.

Desarrollo local

El generador configura el target dev del agente para:

1. Iniciar los servidores MCP conectados automáticamente
2. Establecer LOCAL_DEV=true para que el cliente generado use transporte HTTP directo en lugar de AgentCore

Ejecuta el agente localmente con:

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>

Esto iniciará tanto el agente como todos los servidores MCP conectados, con el agente conectándose a los servidores MCP directamente a través de HTTP en sus puertos locales asignados.