AgentCore Gateway to AgentCore Gateway

The connection generator can register an AgentCore Gateway as a target of another AgentCore Gateway. This lets you compose gateways hierarchically — for example a team-level gateway aggregating several domain gateways, each of which fronts its own MCP servers.

Once connected, the source Gateway aggregates the target Gateway’s tools into its single MCP endpoint. Since the target Gateway already prefixes its tools with its own target names, tools surface through the source Gateway as <gateway-target-name>___<target-name>___<tool-name> — each gateway in the chain adds one prefix. Both gateways evaluate their own Cedar policies: the source Gateway authorizes the caller for the prefixed action, then the target Gateway authorizes the source Gateway’s execution role for the inner action.

Prerequisites

Before using this generator, ensure you have:

1. Two agentcore-gateway projects

Both gateways must have protocol: mcp, and the target gateway must have auth: iam — the source gateway invokes the target signing with its own execution role, so only the target’s inbound auth needs to be IAM. The generator validates this, and also rejects connections that would create a cycle between gateways, which would otherwise recurse infinitely on tools/list.

Usage

Run the Generator

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

Select the aggregating Gateway project as the source and the Gateway to be aggregated as the target.

Options

Parameter	Type	Default	Description
sourceProject Required	string	-	The source project
targetProject Required	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.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator wires existing projects together rather than emitting new source files. The following files are modified:

• Directorypackages/<source-gateway>

  • project.json the source Gateway’s dev target gains a dependency on the target gateway’s dev target
  • local-dev.ts ATTACHED_MCP_SERVERS updated so the local gateway aggregates the target gateway

The source Gateway project’s dev target gains a dependency on the target Gateway’s dev target, so running the source Gateway locally also starts the target gateway (and, transitively, every MCP server attached to it). The target gateway is also registered in the source Gateway project’s local-dev.ts so the local gateway aggregates its tools.

Adding the gateway target to your stack

The generator cannot automatically wire the gateway target into your infrastructure because it doesn’t know which stack or module instantiates the Gateways. Add a single call to gateway.addGateway(targetGateway) yourself.

CDK

In the stack where you instantiate the Gateways, register the target gateway as a target of the source gateway:

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

const innerGateway = new InnerGateway(this, 'InnerGateway');
const outerGateway = new OuterGateway(this, 'OuterGateway');

// Register the inner gateway as a target of the outer gateway. The target
// name defaults to the inner gateway's `gatewayName` (its class name in
// kebab-case, e.g. `InnerGateway` -> `inner-gateway`).
outerGateway.addGateway(innerGateway);

The Gateway target name (the target gateway’s gatewayName by default) prefixes Cedar action names on the source gateway — the action format is AgentCore::Action::"<gatewayTargetName>___<targetName>___<toolName>". See the Writing Policies section. Keep the target name short and stable; changing it later invalidates any Cedar policies that reference the old name.

To override the default target name, pass gatewayTargetName:

outerGateway.addGateway(innerGateway, { gatewayTargetName: 'inner' });

The construct grants the source gateway’s execution role bedrock-agentcore:InvokeGateway access to the target gateway, and configures the target with iamCredentialProvider.service = 'bedrock-agentcore' so the source gateway signs outbound calls using its own execution role. The target is created after the target gateway and all of its own targets, since AgentCore fetches the target’s tools during creation.

Terraform

In the Terraform file where you instantiate the Gateways, wire the gateway target in:

packages/infra/src/main.tf

module "inner_gateway" {
  source = "../../common/terraform/src/app/gateways/inner-gateway"

  # Target ids of the inner gateway's own targets (e.g. its MCP servers), so
  # its gateway_url is not consumed until it serves their tools.
  tool_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

module "outer_gateway" {
  source              = "../../common/terraform/src/app/gateways/outer-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.inner_gateway.target_id]

  additional_iam_policy_statements = [
    {
      Effect   = "Allow"
      Action   = ["bedrock-agentcore:InvokeGateway"]
      Resource = [module.inner_gateway.gateway_arn]
    }
  ]
}

# Register the inner gateway as a target of the outer gateway
resource "aws_bedrockagentcore_gateway_target" "inner_gateway" {
  gateway_identifier = module.outer_gateway.gateway_id
  name               = "inner-gateway"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = module.inner_gateway.gateway_url
      }
    }
  }

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

The target name (inner-gateway above) prefixes Cedar action names on the outer gateway — see the Writing Policies section. The additional_iam_policy_statements entry grants the outer gateway’s execution role invoke access to the inner gateway, which is required both to fetch the inner gateway’s tools at target creation time and to route calls at runtime. policy_dependencies ensures Cedar policies referencing this target’s actions are created after the target has registered them.

Target ordering

AgentCore fetches the inner gateway’s tools when the aws_bedrockagentcore_gateway_target is created, so the inner gateway must already be serving them. Set the inner gateway’s tool_dependencies to its own targets’ ids: its gateway_url then flows through a readiness probe that polls tools/list until those tools are served, so the outer gateway’s target waits for the inner gateway to be ready.

Cedar policies across chained gateways

Each gateway in the chain evaluates its own policy set:

1. The source gateway evaluates the original caller (e.g. an agent’s execution role) against the prefixed action, e.g. AgentCore::Action::"inner-gateway___my-mcp___add".
2. The target gateway evaluates the source gateway’s execution role against the inner action, e.g. AgentCore::Action::"my-mcp___add".

This means a tool call through a gateway chain must be permitted at every hop. The default permit-all.cedar permits any caller in the same AWS account, which includes the source gateway’s role; if you write narrower policies on the target gateway, remember that the principal it sees is the source gateway’s role, not the original caller.

Local Development

Running the source Gateway locally with:

pnpm

pnpm nx dev <source-gateway-name>

yarn

yarn nx dev <source-gateway-name>

npm

npx nx dev <source-gateway-name>

bun

bunx nx dev <source-gateway-name>

starts the local source gateway, the local target gateway, and every MCP server attached to either, each on its assigned local port. Tool names are prefixed at each hop exactly as deployed (<gateway-target-name>___<target-name>___<tool-name>), so agent prompts and Cedar action names remain consistent across local and deployed runs.

Local fidelity

Local development uses local stand-in gateways — lightweight MCP aggregators started by each Gateway project, not the AgentCore Gateway service. As a consequence, Cedar policies are not evaluated locally at either hop. To exercise Cedar policies, run the agent’s serve target instead (see the TypeScript / Python agent-connection guides) so the locally-running agent calls the deployed Gateway.