AgentCore Gateway para Servidor MCP

O gerador connection pode registrar um servidor MCP (seja TypeScript ou Python) como um destino de um AgentCore Gateway.

Uma vez conectado, o Gateway agrega as ferramentas do servidor MCP em seu único endpoint MCP, avalia chamadas contra seu mecanismo de políticas Cedar e assina o tráfego de saída para o servidor MCP com IAM SigV4.

Pré-requisitos

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

1. Um projeto agentcore-gateway
2. Um componente de servidor MCP (ts#mcp-server ou py#mcp-server) criado com infra: agentcore e auth: iam

O Gateway deve ter protocol: mcp e o servidor MCP deve ter auth: iam — o gerador valida ambos. Servidores MCP não-IAM não podem ser anexados porque o Gateway assina o tráfego de saída com SigV4.

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 o projeto Gateway como origem e o projeto do servidor MCP como destino. Se o projeto do servidor MCP contiver múltiplos componentes, especifique 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 conecta projetos existentes em vez de emitir novos arquivos de origem. Os seguintes arquivos são modificados:

• Directorypackages/<gateway>

  • project.json <gateway>-serve-local ganha uma dependência no <mcp>-serve-local do servidor MCP
  • serve-local.ts ATTACHED_MCP_SERVERS atualizado para que o gateway local agregue o servidor MCP

O destino dev do projeto Gateway ganha uma dependência no destino <mcp>-dev do servidor MCP, então executar o Gateway localmente também inicia o servidor MCP. O servidor MCP também é registrado no local-dev.ts do projeto Gateway para que o gateway local agregue suas ferramentas.

Adicionando o destino do servidor MCP à sua stack

O gerador não pode conectar automaticamente o destino do servidor MCP à sua infraestrutura porque ele não sabe qual stack ou módulo instancia o Gateway. Adicione uma única chamada para gateway.addMcpServer(server) você mesmo.

CDK

Na stack onde você instancia o Gateway, registre o servidor MCP como um destino:

packages/infra/src/stacks/application-stack.ts

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

O nome do destino do Gateway (o mcpServerName do servidor MCP por padrão) é usado como prefixo para nomes de ações Cedar — o formato da ação é AgentCore::Action::"<targetName>___<toolName>". Veja a seção Escrevendo Políticas. Mantenha o nome do destino curto e estável; alterá-lo posteriormente invalida quaisquer políticas Cedar que referenciem o nome antigo.

Para substituir o nome do destino padrão, passe gatewayTargetName:

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

O construto configura o destino com iamCredentialProvider.service = 'bedrock-agentcore' para que o Gateway assine chamadas de saída usando sua própria função de execução.

Terraform

No arquivo Terraform onde você instancia o Gateway, conecte o destino do servidor MCP:

packages/infra/src/main.tf

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"
    }
  }
}

O name do destino (my-mcp-server acima) é usado como prefixo para nomes de ações Cedar — veja a seção Escrevendo Políticas. policy_dependencies garante que as políticas Cedar que referenciam as ações deste destino sejam criadas após o destino ter registrado essas ações.

Desenvolvimento Local

Executar o Gateway localmente com:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

inicia um gateway local mais cada servidor MCP anexado em sua porta local atribuída. O gateway local expõe um único endpoint MCP que agrega as ferramentas dos servidores anexados. Agentes conectados ao Gateway via os geradores de conexão de gateway TypeScript ou Python apontam para ele ao executar com LOCAL_DEV=true.

Fidelidade local

O desenvolvimento local usa um gateway substituto local — um agregador MCP leve iniciado pelo projeto Gateway, não o serviço AgentCore Gateway. Como consequência, as políticas Cedar não são avaliadas localmente. Cada agente vê todas as ferramentas em todos os servidores MCP anexados. Para exercitar as políticas Cedar, execute o destino serve do agente (veja os guias de conexão de agente TypeScript / Python) para que o agente em execução local chame o Gateway implantado.

Os nomes das ferramentas ainda são prefixados localmente como <target-name>___<tool-name> para corresponder ao namespace do Gateway implantado, então o prompt do sistema de um agente e os nomes de ações Cedar que você referencia permanecem consistentes entre execuções locais e implantadas.

s e implantadas. :::