Python Agent para MCP

O gerador connection pode conectar seu Python Agent a um servidor MCP (seja TypeScript ou Python).

O gerador configura toda a fiação necessária para que seu agente possa descobrir e invocar as ferramentas do servidor MCP, tanto quando implantado na AWS (via Bedrock AgentCore) quanto quando executado localmente.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

Um projeto Python com um componente Python Agent (Strands ou LangChain)
Um projeto com um componente de servidor MCP (seja ts#mcp-server ou py#mcp-server)
Ambos os componentes criados com infra: agentcore

Uso

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

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

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

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Selecione seu projeto de agente como origem e seu projeto de servidor MCP como destino. Se seus projetos contiverem múltiplos componentes, especifique as opções sourceComponent e targetComponent para desambiguar.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador cria um projeto Python compartilhado agent_connection em packages/common/agent_connection/ (se ainda não existir). Módulos de cliente por conexão são gerados neste projeto compartilhado:

Directorypackages/common/agent_connection
- Directory<scope>_agent_connection
  - __init__.py Re-exporta clientes por conexão
  - Directorycore
    agentcore_endpoints.py Resolução de ARN/URL independente de framework
    agentcore_mcp_transport.py Transporte MCP independente de framework
    agentcore_mcp_client_<framework>.py Cliente MCP envolvendo o transporte para o framework do seu agente
    Directoryauth/ httpx.Auth independente de framework para SigV4 / encaminhamento de sessão
    …
  - Directoryapp
    <mcp_server_name>_client_<framework>.py Cliente por conexão para cada servidor MCP

O sufixo do cliente corresponde ao framework do seu agente (_strands ou _langchain).

Além disso, o gerador:

Transforma o agent.py do seu agente para importar e usar as ferramentas do servidor MCP via um cliente baseado em classe
Adiciona o projeto agent_connection como uma dependência de workspace do seu projeto de agente
Atualiza o target dev do agente para depender do target serve do servidor MCP

Usando o Servidor MCP Conectado

O gerador transforma o agent.py do seu agente para usar as ferramentas do servidor MCP:

Strands
LangChain

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

O cliente Strands é um gerenciador de contexto, inserido em um bloco with ao redor do agente.

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

O cliente LangChain retorna uma lista de ferramentas carregadas via langchain-mcp-adapters. Cada ferramenta abre uma nova sessão MCP por chamada, então as ferramentas permanecem utilizáveis durante o tempo de vida do agente — nenhum bloco with é necessário.

O ID de sessão do AgentCore é propagado automaticamente para o servidor MCP via o cabeçalho X-Amzn-Bedrock-AgentCore-Runtime-Session-Id para ambos os frameworks, garantindo consistência para Bedrock AgentCore Observability.

Infraestrutura

CDK
Terraform

Após executar o gerador de conexão, você precisa conceder ao agente permissão para invocar o servidor MCP:

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

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

O ARN do runtime AgentCore do servidor MCP é automaticamente registrado no namespace agentcore da Configuração de Runtime pelo construto CDK gerado, para que o agente possa descobri-lo em tempo de execução.

Após executar o gerador de conexão, você precisa conceder ao agente permissão para invocar o servidor MCP em sua configuração Terraform:

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
}

O ARN do runtime AgentCore do servidor MCP é automaticamente registrado no namespace agentcore da Configuração de Runtime pelo módulo Terraform gerado, para que o agente possa descobri-lo em tempo de execução.

Desenvolvimento Local

O gerador configura o target dev do agente para:

Iniciar o(s) servidor(es) MCP conectado(s) automaticamente
Definir LOCAL_DEV=true para que o cliente gerado use transporte HTTP direto em vez de AgentCore

Execute o agente localmente com:

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

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

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

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

Isso iniciará tanto o agente quanto todos os servidores MCP conectados, com o agente se conectando aos servidores MCP diretamente via HTTP em suas portas locais atribuídas.