Agente TypeScript Strands a MCP

El generador connection puede conectar tu TypeScript Strands Agent 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 está desplegado 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 TypeScript con un componente Strands Agent
2. Un proyecto con un componente de servidor MCP (ya sea ts#mcp-server o py#mcp-server)
3. Ambos componentes creados con computeType: BedrockAgentCoreRuntime

Uso

Ejecutar el generador

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

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

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

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

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

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	The source project
targetProject Requerido	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.

Salida del generador

El generador crea un paquete compartido agent-connection y modifica el código de tu agente:

• Directoriopackages/common/agent-connection

  • Directoriosrc

    • Directorioapp

      • <mcp-server-name>-client.ts Cliente de alto nivel para el servidor MCP conectado
    • Directoriocore

      • agentcore-mcp-client.ts Cliente MCP AgentCore de bajo nivel con autenticación SigV4/JWT
    • index.ts Exporta todos los clientes
  • project.json
  • tsconfig.json

Además:

• Transforma el agent.ts de tu agente para importar y usar las herramientas del servidor MCP
• Actualiza el objetivo serve-local del agente para que dependa del objetivo serve del servidor MCP
• Instala las dependencias requeridas

Usar el servidor MCP conectado

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

El parámetro sessionId se transmite desde el llamador, asegurando consistencia para Bedrock AgentCore Observability.

Infraestructura

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

El ARN del runtime AgentCore del servidor MCP se registra automáticamente en el namespace connection 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: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
}

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

Desarrollo local

El generador configura el objetivo serve-local del agente para:

1. Iniciar automáticamente el/los servidor(es) MCP conectado(s)
2. Establecer SERVE_LOCAL=true para que el cliente generado use transporte HTTP directo en lugar de AgentCore

Ejecuta el agente localmente con:

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>

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.