AgentCore Gateway to MCP Server

The connection generator can register an MCP server (either TypeScript or Python) as a target of an AgentCore Gateway.

Once connected, the Gateway aggregates the MCP server’s tools into its single MCP endpoint, evaluates calls against its Cedar policy engine, and signs outbound traffic to the MCP server with IAM SigV4.

Prerequisites

Before using this generator, ensure you have:

1. A agentcore-gateway project
2. An MCP server component (ts#mcp-server or py#mcp-server) created with infra: agentcore and auth: iam

The Gateway must have protocol: mcp and the MCP server must have auth: iam — the generator validates both. Non-IAM MCP servers cannot be attached because the Gateway signs outbound traffic with SigV4.

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 Gateway project as the source and the MCP server project as the target. If the MCP server project contains multiple components, specify targetComponent to disambiguate.

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/<gateway>

  • project.json the Gateway’s dev target gains a dependency on the MCP server’s <mcp>-dev
  • local-dev.ts ATTACHED_MCP_SERVERS updated so the local gateway aggregates the MCP server

The Gateway project’s dev target gains a dependency on the MCP server’s <mcp>-dev target, so running the Gateway locally also starts the MCP server. The MCP server is also registered in the Gateway project’s local-dev.ts so the local gateway aggregates its tools.

Adding the MCP server target to your stack

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

CDK

In the stack where you instantiate the Gateway, register the MCP server as a 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);

The Gateway target name (the MCP server’s mcpServerName by default) is used as the prefix for Cedar action names — the action format is AgentCore::Action::"<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:

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

The construct configures the target with iamCredentialProvider.service = 'bedrock-agentcore' so the Gateway signs outbound calls using its own execution role.

Terraform

In the Terraform file where you instantiate the Gateway, wire the MCP server target in:

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

The target name (my-mcp-server above) is used as the prefix for Cedar action names — see the Writing Policies section. policy_dependencies ensures Cedar policies referencing this target’s actions are created after the target has registered them.

Local Development

Running the Gateway locally with:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

starts a local gateway plus every attached MCP server on its assigned local port. The local gateway exposes a single MCP endpoint that aggregates the attached servers’ tools. Agents connected to the Gateway via the TypeScript or Python gateway-connection generators point at it when running with LOCAL_DEV=true.

Local fidelity

Local development uses a local stand-in gateway — a lightweight MCP aggregator started by the Gateway project, not the AgentCore Gateway service. As a consequence, Cedar policies are not evaluated locally. Every agent sees every tool on every attached MCP server. 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.

Tool names are still prefixed locally as <target-name>___<tool-name> to match the deployed Gateway’s namespacing, so an agent’s system prompt and the Cedar action names you reference remain consistent across local and deployed runs.