TypeScript Agent para MCP

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

O gerador configura toda a estrutura 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:

1. Um projeto TypeScript com um componente Strands Agent
2. Um projeto com um componente de servidor MCP (seja ts#mcp-server ou py#mcp-server)
3. Ambos os componentes criados com infra: agentcore

Uso

Executar o Gerador

Execute este gerador@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 o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Monte seu comando5

sourceProjectObrigatório

targetProjectObrigatório

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

Opções do gerador5 opções

sourceProjectObrigatóriostring

O projeto de origem

targetProjectObrigatóriostring

O projeto de destino para conectar

sourceComponentstring

O componente de origem a partir do qual conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.

targetComponentstring

O componente de destino ao qual conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.

preferInstallDependenciesbooleanPadrão: 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 pacote compartilhado agent-connection e modifica o código do seu agente:

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directoryapp

      • <mcp-server-name>-client-strands.ts Cliente Strands de alto nível para o servidor MCP conectado
    • Directorycore

      • agentcore-endpoints.ts Resolução de ARN/URL independente de framework
      • agentcore-fetch.ts Fetch com SigV4 / JWT / encaminhamento de sessão independente de framework
      • agentcore-transport.ts Estrutura de transporte AgentCore compartilhada
      • agentcore-mcp-transport.ts Transporte MCP independente de framework
      • agentcore-mcp-client-strands.ts Cliente MCP Strands envolvendo o transporte
    • index.ts Exporta todos os clientes
  • project.json
  • tsconfig.json

Além disso, ele:

• Transforma o agent.ts do seu agente para importar e usar as ferramentas do servidor MCP
• Atualiza o target dev do agente para depender do target serve do servidor MCP
• Instala as dependências necessárias

Usando o Servidor MCP Conectado

O gerador transforma o agent.ts do seu agente para usar as ferramentas do servidor 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],
  });
};

O ID de sessão do AgentCore é propagado para o servidor MCP automaticamente via cabeçalho X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, então create() não recebe argumentos: o servidor do agente vincula a sessão da requisição de entrada em um contexto AsyncLocalStorage (enterSessionContext no router.ts gerado, ou runWithSessionId no middleware de sessão A2A/AG-UI), e o fetch do cliente de conexão em agentcore-fetch.ts o carimba em cada chamada de saída — garantindo consistência para Bedrock AgentCore Observability.

Infraestrutura

Projeto de infraestrutura necessário

Os geradores de agente, servidor MCP e Gateway fornecem seus construtos e módulos em packages/common, mas eles não criam uma aplicação para implantá-los — então packages/infra não existe até que você o gere. Execute o gerador ts#infra (CDK) ou o gerador terraform#project (Terraform) antes de editar o arquivo abaixo.

CDK

Após executar o gerador de conexão, você precisa conceder ao agente permissão para invocar o 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 as ações de invocação do AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeForUser e InvokeAgentRuntimeWithWebSocketStream) no ARN do runtime do servidor MCP.

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

Terraform

Após executar o gerador de conexão, você precisa conceder ao agente permissão para invocar o servidor MCP na sua configuração 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
}

O ARN do runtime AgentCore do servidor MCP é automaticamente registrado no namespace agentcore da Runtime Configuration 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:

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

Execute o agente localmente com:

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>

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