AgentCore Gateway a Servidor MCP

El generador connection puede registrar un servidor MCP (ya sea TypeScript o Python) como destino de un AgentCore Gateway.

Una vez conectado, el Gateway agrega las herramientas del servidor MCP en su único endpoint MCP, evalúa las llamadas contra su motor de políticas Cedar y firma el tráfico saliente al servidor MCP con IAM SigV4.

Requisitos previos

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

Un proyecto agentcore-gateway
Un componente de servidor MCP (ts#mcp-server o py#mcp-server) creado con infra: agentcore y auth: iam

El Gateway debe tener protocol: mcp y el servidor MCP debe tener auth: iam — el generador valida ambos. Los servidores MCP sin IAM no pueden adjuntarse porque el Gateway firma el tráfico saliente con SigV4.

Uso

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

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

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

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

Selecciona el proyecto Gateway como origen y el proyecto del servidor MCP como destino. Si el proyecto del servidor MCP contiene múltiples componentes, especifica targetComponent para desambiguar.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	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 conecta proyectos existentes en lugar de emitir nuevos archivos fuente. Los siguientes archivos se modifican:

Directoriopackages/<gateway>
- project.json <gateway>-serve-local gana una dependencia en el <mcp>-serve-local del servidor MCP
- serve-local.ts ATTACHED_MCP_SERVERS actualizado para que el gateway local agregue el servidor MCP

El objetivo dev del proyecto Gateway gana una dependencia en el objetivo <mcp>-dev del servidor MCP, por lo que ejecutar el Gateway localmente también inicia el servidor MCP. El servidor MCP también se registra en el local-dev.ts del proyecto Gateway para que el gateway local agregue sus herramientas.

Agregar el destino del servidor MCP a tu stack

El generador no puede conectar automáticamente el destino del servidor MCP en tu infraestructura porque no sabe qué stack o módulo instancia el Gateway. Agrega una única llamada a gateway.addMcpServer(server) tú mismo.

CDK
Terraform

En el stack donde instancias el Gateway, registra el servidor MCP como destino:

const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the MCP server as a target of the Gateway. The target name
// defaults to the MCP server construct's id in kebab-case (`my-mcp-server`).
myGateway.addMcpServer(myMcpServer);

El nombre del destino del Gateway (el mcpServerName del servidor MCP por defecto) se usa como prefijo para los nombres de acción de Cedar — el formato de acción es AgentCore::Action::"<targetName>___<toolName>". Consulta la sección Escribir políticas. Mantén el nombre del destino corto y estable; cambiarlo más tarde invalida cualquier política de Cedar que haga referencia al nombre antiguo.

Para anular el nombre de destino predeterminado, pasa gatewayTargetName:

myGateway.addMcpServer(myMcpServer, { gatewayTargetName: 'my-mcp' });

El constructo configura el destino con iamCredentialProvider.service = 'bedrock-agentcore' para que el Gateway firme las llamadas salientes usando su propio rol de ejecución.

En el archivo Terraform donde instancias el Gateway, conecta el destino del servidor MCP:

module "my_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
}

module "my_gateway" {
  source              = "../../common/terraform/src/app/gateways/my-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

# Register the MCP server as a target of the Gateway
resource "aws_bedrockagentcore_gateway_target" "my_mcp_server" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-mcp-server"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = "https://bedrock-agentcore.${local.aws_region}.amazonaws.com/runtimes/${urlencode(module.my_mcp_server.agent_core_runtime_arn)}/invocations?qualifier=DEFAULT"
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

El name del destino (my-mcp-server arriba) se usa como prefijo para los nombres de acción de Cedar — consulta la sección Escribir políticas. policy_dependencies asegura que las políticas de Cedar que hacen referencia a las acciones de este destino se creen después de que el destino haya registrado dichas acciones.

Desarrollo local

Ejecutar el Gateway localmente con:

pnpm nx dev <gateway-name>

yarn nx dev <gateway-name>

npx nx dev <gateway-name>

bunx nx dev <gateway-name>

inicia un gateway local más cada servidor MCP adjunto en su puerto local asignado. El gateway local expone un único endpoint MCP que agrega las herramientas de los servidores adjuntos. Los agentes conectados al Gateway a través de los generadores de conexión de gateway de TypeScript o Python apuntan a él cuando se ejecutan con LOCAL_DEV=true.

El desarrollo local utiliza un gateway sustituto local — un agregador MCP ligero iniciado por el proyecto Gateway, no el servicio AgentCore Gateway. Como consecuencia, las políticas de Cedar no se evalúan localmente. Cada agente ve cada herramienta en cada servidor MCP adjunto. Para ejercitar las políticas de Cedar, ejecuta el objetivo serve del agente en su lugar (consulta las guías de conexión de agente de TypeScript / Python) para que el agente que se ejecuta localmente llame al Gateway desplegado.

Los nombres de las herramientas todavía tienen el prefijo local como <target-name>___<tool-name> para coincidir con el espacio de nombres del Gateway desplegado, por lo que el prompt del sistema de un agente y los nombres de acción de Cedar a los que haces referencia permanecen consistentes entre ejecuciones locales y desplegadas.

desplegadas. :::