AgentCore Gateway a MCP Server

Il generatore connection può registrare un server MCP (sia TypeScript che Python) come target di un AgentCore Gateway.

Una volta connesso, il Gateway aggrega gli strumenti del server MCP nel suo singolo endpoint MCP, valuta le chiamate rispetto al suo motore di policy Cedar e firma il traffico in uscita verso il server MCP con IAM SigV4.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto agentcore-gateway
2. Un componente server MCP (ts#mcp-server o py#mcp-server) creato con infra: agentcore e auth: iam

Il Gateway deve avere protocol: mcp e il server MCP deve avere auth: iam — il generatore valida entrambi. I server MCP non-IAM non possono essere collegati perché il Gateway firma il traffico in uscita con SigV4.

Utilizzo

Eseguire il Generatore

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Seleziona il progetto Gateway come sorgente e il progetto server MCP come target. Se il progetto server MCP contiene più componenti, specifica targetComponent per disambiguare.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore collega i progetti esistenti insieme piuttosto che emettere nuovi file sorgente. I seguenti file vengono modificati:

• Directorypackages/<gateway>

  • project.json il target dev del Gateway acquisisce una dipendenza dal <mcp>-dev del server MCP
  • local-dev.ts ATTACHED_MCP_SERVERS aggiornato in modo che il gateway locale aggreghi il server MCP

Il target <gateway>-dev del progetto Gateway acquisisce una dipendenza dal target <mcp>-dev del server MCP, quindi eseguire il Gateway localmente avvia anche il server MCP. Il server MCP viene anche registrato nel file local-dev.ts del progetto Gateway in modo che il gateway locale aggreghi i suoi strumenti.

Aggiungere il target del server MCP al tuo stack

Il generatore non può collegare automaticamente il target del server MCP nella tua infrastruttura perché non sa quale stack o modulo istanzia il Gateway. Aggiungi tu stesso una singola chiamata a gateway.addMcpServer(server).

CDK

Nello stack in cui istanzi il Gateway, registra il server MCP come target:

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's `mcpServerName` (its class name in
// kebab-case, e.g. `MyMcpServer` -> `my-mcp-server`).
myGateway.addMcpServer(myMcpServer);

Il nome del target del Gateway (il mcpServerName del server MCP per impostazione predefinita) viene utilizzato come prefisso per i nomi delle azioni Cedar — il formato dell’azione è AgentCore::Action::"<targetName>___<toolName>". Vedi la sezione Scrittura delle Policy. Mantieni il nome del target breve e stabile; modificarlo successivamente invalida qualsiasi policy Cedar che faccia riferimento al vecchio nome.

Per sovrascrivere il nome del target predefinito, passa gatewayTargetName:

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

Il costrutto configura il target con iamCredentialProvider.service = 'bedrock-agentcore' in modo che il Gateway firmi le chiamate in uscita utilizzando il proprio ruolo di esecuzione.

Terraform

Nel file Terraform in cui istanzi il Gateway, collega il target del server 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"
    }
  }
}

Il name del target (my-mcp-server sopra) viene utilizzato come prefisso per i nomi delle azioni Cedar — vedi la sezione Scrittura delle Policy. policy_dependencies garantisce che le policy Cedar che fanno riferimento alle azioni di questo target vengano create dopo che il target ha registrato tali azioni.

Sviluppo Locale

Eseguire il Gateway localmente con:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

avvia un gateway locale più ogni server MCP collegato sulla sua porta locale assegnata. Il gateway locale espone un singolo endpoint MCP che aggrega gli strumenti dei server collegati. Gli agenti connessi al Gateway tramite i generatori di connessione gateway TypeScript o Python puntano ad esso quando vengono eseguiti con LOCAL_DEV=true.

Fedeltà locale

Lo sviluppo locale utilizza un gateway sostitutivo locale — un aggregatore MCP leggero avviato dal progetto Gateway, non dal servizio AgentCore Gateway. Di conseguenza, le policy Cedar non vengono valutate localmente. Ogni agente vede ogni strumento su ogni server MCP collegato. Per esercitare le policy Cedar, esegui invece il target serve dell’agente (vedi le guide di connessione agente TypeScript / Python) in modo che l’agente in esecuzione locale chiami il Gateway distribuito.

I nomi degli strumenti sono ancora prefissati localmente come <target-name>___<tool-name> per corrispondere al namespacing del Gateway distribuito, quindi il prompt di sistema di un agente e i nomi delle azioni Cedar a cui fai riferimento rimangono coerenti tra le esecuzioni locali e distribuite.