TypeScript Strands Agent para MCP

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

O gerador configura toda a infraestrutura 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 computeType: BedrockAgentCoreRuntime

Uso

Execute o Gerador

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

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

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

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

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	-	The source project
targetProject Obrigatório	string	-	The target project to connect to
sourceComponent	string	-	The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.
targetComponent	string	-	The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.

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.ts Cliente de alto nível para o servidor MCP conectado
    • Directorycore

      • agentcore-mcp-client.ts Cliente MCP AgentCore de baixo nível com autenticação SigV4/JWT
    • 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 alvo serve-local do agente para depender do alvo 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 { MyMcpServerClient } from ':my-scope/agent-connection';

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

O parâmetro sessionId é propagado do chamador, garantindo consistência para Bedrock AgentCore Observability.

Infraestrutura

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 access to bedrock models
myAgent.agentCoreRuntime.addToRolePolicy(
  new PolicyStatement({
    actions: ['bedrock:InvokeModel', 'bedrock:InvokeModelWithResponseStream'],
    resources: ['arn:aws:bedrock:*:*:foundation-model/*', 'arn:aws:bedrock:*:*:inference-profile/*'],
  }),
);

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

O ARN do runtime AgentCore do servidor MCP é automaticamente registrado no namespace connection da Configuração de Runtime 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: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 connection 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 alvo serve-local do agente para:

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

Execute o agente localmente com:

pnpm

pnpm nx <agent-name>-serve-local <project-name>

yarn

yarn nx <agent-name>-serve-local <project-name>

npm

npx nx <agent-name>-serve-local <project-name>

bun

bunx nx <agent-name>-serve-local <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.