@aws/nx-plugin-mcp 1.0.0-rc.11 → 1.0.0-rc.12

package/bin/aws-nx-mcp.js

@@ -19740,6 +19740,19 @@ const EMPTY_COMPLETION_RESULT = { completion: {
 //#endregion
 //#region ../nx-plugin/generators.json
 var generators$1 = {
+	"agentcore-gateway": {
+		"factory": "./src/agentcore-gateway/generator",
+		"schema": "./src/agentcore-gateway/schema.json",
+		"description": "Generate an AgentCore Gateway project",
+		"metric": "g48"
+	},
+	"agentcore-gateway#mcp-connection": {
+		"factory": "./src/agentcore-gateway/mcp-connection/generator",
+		"schema": "./src/agentcore-gateway/mcp-connection/schema.json",
+		"description": "Connect an AgentCore Gateway to an MCP server",
+		"metric": "g49",
+		"hidden": true
+	},
 	"connection": {
 		"factory": "./src/connection/generator",
 		"schema": "./src/connection/schema.json",
@@ -19760,7 +19773,10 @@ var generators$1 = {
 			"connection/trpc-rdb",
 			"connection/smithy-rdb",
 			"connection/ts-mcp-server-rdb",
-			"connection/ts-agent-rdb"
+			"connection/ts-agent-rdb",
+			"connection/ts-agent-gateway",
+			"connection/py-agent-gateway",
+			"connection/agentcore-gateway-mcp"
 		]
 	},
 	"license": {
@@ -20016,6 +20032,13 @@ var generators$1 = {
 		"metric": "g35",
 		"hidden": true
 	},
+	"ts#agent#gateway-connection": {
+		"factory": "./src/ts/agent/gateway-connection/generator",
+		"schema": "./src/ts/agent/gateway-connection/schema.json",
+		"description": "Connect a TypeScript Agent to an AgentCore Gateway",
+		"metric": "g50",
+		"hidden": true
+	},
 	"py#agent#a2a-connection": {
 		"factory": "./src/py/agent/a2a-connection/generator",
 		"schema": "./src/py/agent/a2a-connection/schema.json",
@@ -20023,6 +20046,13 @@ var generators$1 = {
 		"metric": "g36",
 		"hidden": true
 	},
+	"py#agent#gateway-connection": {
+		"factory": "./src/py/agent/gateway-connection/generator",
+		"schema": "./src/py/agent/gateway-connection/schema.json",
+		"description": "Connect a Python Agent to an AgentCore Gateway",
+		"metric": "g51",
+		"hidden": true
+	},
 	"ts#sync": {
 		"factory": "./src/ts/sync/generator",
 		"schema": "./src/ts/sync/schema.json",
@@ -53590,18 +53620,28 @@ const readCommandsAttr = (node) => {
 * SPDX-License-Identifier: Apache-2.0
 */
 /**
-* Pull out every enum-valued property as a `FilterableOption`. Shared between
-* the MCP server (deriving options from a generator's schema) and the docs
-* filter bar (mapping user-referenced keys onto their enum values).
+* The values an option can be filtered on: its enum values, or true/false
+* for booleans. Returns undefined for non-filterable options.
+*/
+const filterableValuesForProperty = (prop) => {
+	if (Array.isArray(prop.enum) && prop.enum.length > 0) return prop.enum.map((v) => String(v));
+	if (prop.type === "boolean") return ["true", "false"];
+};
+/**
+* Pull out every filterable property (enum or boolean valued) as a
+* `FilterableOption`. Shared between the MCP server (deriving options from a
+* generator's schema) and the docs filter bar (mapping user-referenced keys
+* onto their values).
 */
 const filterableOptionsFromSchema = (schema) => {
 	const props = schema?.properties ?? {};
 	const out = [];
 	for (const [key, prop] of Object.entries(props)) {
-		if (!Array.isArray(prop.enum) || prop.enum.length === 0) continue;
+		const values = filterableValuesForProperty(prop);
+		if (!values) continue;
 		out.push({
 			key,
-			enum: prop.enum.map((v) => String(v)),
+			enum: values,
 			default: prop.default !== void 0 ? String(prop.default) : void 0,
 			description: prop.description
 		});

package/docs/guides/agentcore-gateway.mdx

@@ -0,0 +1,239 @@
+---
+title: AgentCore Gateway
+description: Create an AgentCore Gateway project
+generator: agentcore-gateway
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+import Link from '@components/link.astro';
+import NxCommands from '@components/nx-commands.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Generate an [Amazon Bedrock AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) project. An AgentCore Gateway is a managed entry point that aggregates one or more MCP server targets behind a single MCP endpoint, evaluates every tool call against a [Cedar policy engine](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html), and signs outbound traffic to MCP servers with IAM SigV4.
+
+## Usage
+
+### Generate an AgentCore Gateway
+
+<RunGenerator generator="agentcore-gateway" />
+
+### Options
+
+<GeneratorParameters generator="agentcore-gateway" />
+
+## Generator Output
+
+The generator creates a new project at `packages/<name>/`, plus a CDK construct or Terraform module for the infrastructure:
+
+<FileTree>
+  - packages/\<name>/
+    - policies/ Cedar policy source files (omitted when `cedarPolicy: false`)
+      - permit-all.cedar Default Cedar policy that permits authenticated callers from within the same AWS account
+      - README.md Reference for writing Cedar policies
+    - serve-local.ts Local gateway aggregating attached MCP servers for local development
+    - project.json Adds the \<name>-serve and \<name>-serve-local aggregator targets
+</FileTree>
+
+### Infrastructure
+
+Infrastructure is generated when `infra` is `agentcore` (the default). With `infra: none` no infrastructure is generated — re-run the generator with `infra: agentcore` later to add it.
+
+<Snippet name="shared-constructs" />
+
+<Infrastructure>
+  <Fragment slot="cdk">
+    <FileTree>
+      - packages/common/constructs/src
+        - core
+          - agentcore-gateway/ Shared gateway construct (readiness probe, Cedar policy loading)
+        - app
+          - gateways
+            - \<name>/
+              - \<name>.ts CDK construct for deploying the Gateway
+    </FileTree>
+  </Fragment>
+  <Fragment slot="terraform">
+    <FileTree>
+      - packages/common/terraform/src
+        - app
+          - gateways
+            - \<name>/
+              - \<name>.tf Terraform module for deploying the Gateway
+    </FileTree>
+  </Fragment>
+</Infrastructure>
+
+The generated construct creates the following AWS resources:
+
+- An `AgentCore::Gateway` configured for the MCP protocol with `GatewayAuthorizer.usingAwsIam()` (inbound IAM authentication)
+- An `AgentCore::PolicyEngine` running in `ENFORCE` mode, attached to the Gateway (omitted when `cedarPolicy: false`)
+- One `AgentCore::Policy` per `.cedar` file in `policies/`
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> so agents can discover it at runtime.
+
+## Writing Policies
+
+<OptionFilter when={{ cedarPolicy: true }} description="Cedar policies — cedarPolicy: true only">
+
+Cedar is the policy language used by AgentCore Gateway to authorize tool calls. Every `tools/list` and `tools/call` request flowing through the Gateway is evaluated against the attached policy set, and the caller must have at least one matching `permit` statement (and no matching `forbid`) for the request to succeed.
+
+Refer to the [AWS documentation on AgentCore Gateway policies](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html) for the full reference, including [common policy patterns](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-common-patterns.html).
+
+### Adding a policy
+
+To add a policy, create a new `.cedar` file alongside `permit-all.cedar`. Each `.cedar` file in `policies/` must contain exactly **one** `permit` or `forbid` statement and is deployed as a single `AWS::BedrockAgentCore::Policy` resource. The policy resource's name is derived from the filename: `permit-all.cedar` becomes `PermitAll` (kebab/snake-case is converted to PascalCase). Files containing multiple statements produce `unexpected token 'forbid'` errors at deploy time — split them into separate files.
+
+For example, to permit only a specific agent role to invoke a particular tool, create:
+
+```cedar title="packages/<name>/policies/ts-agent-divide.cedar"
+permit (
+  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
+  action == AgentCore::Action::"ts-mcp___divide",
+  resource == AgentCore::Gateway::"<%= gatewayArn %>"
+);
+```
+
+Pass the role name in as a template variable (see <a href="#template-variables">Template variables</a> below) rather than hard-coding it. Re-synth or re-plan to deploy the new policy.
+
+### Template variables
+
+Policies are [EJS](https://ejs.co/) templates rendered at synth/plan time so they stay portable across accounts and Gateway redeploys:
+
+| Variable             | Substituted with                              |
+| -------------------- | --------------------------------------------- |
+| `<%= gatewayArn %>`  | The deployed Gateway's ARN                    |
+| `<%= accountId %>`   | The AWS account this Gateway is deployed into |
+
+Always reference these variables rather than hard-coding values.
+
+#### Adding your own variables
+
+Add new variables where the policies are rendered, for example to pass an agent's execution role name to the `ts-agent-divide.cedar` example above:
+
+<Infrastructure>
+<Fragment slot="cdk">
+In `packages/common/constructs/src/app/gateways/<name>/<name>.ts`, pass `cedarPolicyVariables` through to the shared construct:
+
+```ts {4-6}
+super(scope, id, {
+  cedarPolicyPath: path.join(
+    ...
+  ),
+  cedarPolicyVariables: {
+    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
+  },
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+In `packages/common/terraform/src/app/gateways/<name>/<name>.tf`, add to the `query` of the `rendered_policies` data source:
+
+```hcl {4}
+query = {
+  template        = "${local.policies_dir}/${each.value}"
+  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
+  tsAgentRoleName = var.ts_agent_role_name
+  # ...
+}
+```
+</Fragment>
+</Infrastructure>
+
+### ENFORCE mode and default-deny
+
+The `PolicyEngine` runs in `ENFORCE` mode, which means **default-deny** semantics apply: if no `permit` statement matches the (principal, action, resource) tuple, the request is denied. Tool calls that are denied return:
+
+```
+Tool Execution Denied: Tool call not allowed due to policy enforcement
+[No policy applies to the request (denied by default).]
+```
+
+Additionally, the Gateway filters the response of `tools/list` so that callers only see tools they have at least one matching `permit` for: if an agent lacks permission for a given tool, the tool is hidden entirely rather than appearing and failing at call time.
+
+### Default `permit-all.cedar`
+
+The generator ships a default policy that permits any IAM caller from the AWS account the Gateway is deployed into:
+
+```cedar title="packages/<name>/policies/permit-all.cedar"
+permit (
+  principal is AgentCore::IamEntity,
+  action,
+  resource == AgentCore::Gateway::"<%= gatewayArn %>"
+) when {
+  principal.id like "arn:aws:*::<%= accountId %>:*"
+};
+```
+
+To lock things down further, add narrower policies alongside it. Always retain at least one matching `permit` in the policy set, otherwise default-deny will block every call.
+
+### Policy scope reference
+
+For Gateways generated by this plugin, all callers are IAM principals (the Gateway is configured with `GatewayAuthorizer.usingAwsIam()`):
+
+```
+principal is AgentCore::IamEntity
+```
+
+Callers are evaluated as STS assumed-role ARNs with the session name stripped, so a role can be matched exactly — no wildcards needed:
+
+```cedar
+principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"
+```
+
+The same value is available as `principal.id` for `when` clauses. Reserve `like` for genuine patterns, such as the account-wide match in the default `permit-all.cedar`.
+
+Tool invocations reach the policy engine as actions with the form:
+
+```
+AgentCore::Action::"<target-name>___<tool-name>"
+```
+
+where `<target-name>` is the Gateway target name (the MCP server's `mcpServerName` by default when using `gateway.addMcpServer(...)`, derived from the MCP project's class name in kebab-case — e.g. `TsMcp` → `ts-mcp`), `<tool-name>` is the MCP tool's name, and the separator is `___` (three underscores). Cedar does not support wildcards on actions — match exact actions, or omit `action ==` to match all actions.
+
+The resource is always the Gateway itself:
+
+```cedar
+resource == AgentCore::Gateway::"<%= gatewayArn %>"
+```
+
+### Validation considerations
+
+The generated infrastructure creates policies with `IGNORE_ALL_FINDINGS`: AgentCore's Cedar analyzer (`FAIL_ON_ANY_FINDINGS`, the service default) rejects many legitimate policies — for example, a `forbid` disabling a single tool for every caller is rejected as "Overly Restrictive", even when scoped with a `when` clause. Enforcement is unaffected; it is configured by the policy engine's `ENFORCE` mode.
+
+One ordering constraint still applies: a policy referencing `AgentCore::Action::"<target>___<tool>"` only validates once the target has registered that tool with the Gateway, which is why the generated infrastructure creates policies after Gateway targets.
+
+If a policy fails to deploy, CloudFormation surfaces the rejection as an opaque `Resource stabilization failed` error — run `aws bedrock-agentcore-control list-policies --policy-engine-id <id>` to retrieve the validator's `statusReasons`, which contain the actual reason.
+
+### Example: forbid one tool while keeping a broader permit
+
+Pair a narrow `forbid` with a broader `permit` (Cedar evaluates `forbid` over `permit`):
+
+```cedar title="packages/<name>/policies/forbid-divide-for-py-agent.cedar"
+forbid (
+  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
+  action == AgentCore::Action::"ts-mcp___divide",
+  resource == AgentCore::Gateway::"<%= gatewayArn %>"
+);
+```
+
+This denies the Python agent role from calling `ts-mcp___divide` while leaving the broader `permit-all.cedar` in place for all other callers.
+
+</OptionFilter>
+
+## Local Development
+
+The generator adds a `<name>-serve-local` target to the Gateway project, which runs `serve-local.ts`: a local gateway exposing a single MCP endpoint that aggregates every attached MCP server (connected via the <Link path="guides/connection/agentcore-gateway-mcp">`agentcore-gateway#mcp-connection` generator</Link>), with tools prefixed `<target>___<tool>` to match the deployed Gateway. Running it starts the local gateway and all attached MCP servers together.
+
+<NxCommands commands={["<name>-serve-local"]} />
+
+See the connection guide for the full local development story.
+
+## Next steps
+
+- Connect an MCP server: <Link path="guides/connection/agentcore-gateway-mcp">`agentcore-gateway#mcp-connection`</Link>
+- Connect a TypeScript Agent: <Link path="guides/connection/ts-agent-gateway">`ts#agent#gateway-connection`</Link>
+- Connect a Python Agent: <Link path="guides/connection/py-agent-gateway">`py#agent#gateway-connection`</Link>

package/docs/guides/connection/agentcore-gateway-mcp.mdx

@@ -0,0 +1,134 @@
+---
+title: AgentCore Gateway to MCP Server
+description: Connect an AgentCore Gateway to an MCP server
+when:
+  sourceType: agentcore-gateway
+  targetType:
+    - ts#mcp-server
+    - py#mcp-server
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can register an MCP server (either <Link path="guides/ts-mcp-server">TypeScript</Link> or <Link path="guides/py-mcp-server">Python</Link>) as a target of an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+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 <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project
+2. An MCP server component (<Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>) 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
+
+<RunGenerator generator="connection" />
+
+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
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator wires existing projects together rather than emitting new source files. The following files are modified:
+
+<FileTree>
+
+- packages/\<gateway>
+  - project.json `<gateway>-serve-local` gains a dependency on the MCP server's `<mcp>-serve-local`
+  - serve-local.ts `ATTACHED_MCP_SERVERS` updated so the local gateway aggregates the MCP server
+
+</FileTree>
+
+The Gateway project's `<gateway>-serve-local` target gains a dependency on the MCP server's `<mcp>-serve-local` target, so running the Gateway locally also starts the MCP server. The MCP server is also registered in the Gateway project's `serve-local.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.
+
+<Infrastructure>
+<Fragment slot="cdk">
+In the stack where you instantiate the Gateway, register the MCP server as a target:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {5-6}
+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 <Link path="guides/agentcore-gateway">Writing Policies section</Link>. 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`:
+
+```ts
+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.
+</Fragment>
+<Fragment slot="terraform">
+In the Terraform file where you instantiate the Gateway, wire the MCP server target in:
+
+```hcl title="packages/infra/src/main.tf" {7,11-27}
+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 <Link path="guides/agentcore-gateway">Writing Policies section</Link>. `policy_dependencies` ensures Cedar policies referencing this target's actions are created after the target has registered them.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+Running the Gateway locally with:
+
+<NxCommands commands={["<gateway-name>-serve-local"]} />
+
+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 <Link path="guides/connection/ts-agent-gateway">TypeScript</Link> or <Link path="guides/connection/py-agent-gateway">Python</Link> gateway-connection generators point at it when running with `SERVE_LOCAL=true`.
+
+:::caution[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 <Link path="guides/connection/ts-agent-gateway">TypeScript</Link> / <Link path="guides/connection/py-agent-gateway">Python</Link> 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.
+:::

package/docs/guides/connection/py-agent-gateway.mdx

@@ -0,0 +1,158 @@
+---
+title: Python Agent to Gateway
+description: Connect a Python Agent to an AgentCore Gateway
+when:
+  sourceType: py#agent
+  targetType: agentcore-gateway
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can connect your <Link path="guides/py-agent">Python Agent</Link> to an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+The generator wires the agent so it authenticates to the Gateway with IAM SigV4 (via `httpx` request signing) when deployed, and connects to the local gateway started by the Gateway project when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Agent</Link> component (`infra: agentcore`)
+2. A <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the agent project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator emits shared core-gateway modules into your `agent_connection` Python project, plus a per-Gateway wrapper, and modifies your agent:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - core/
+      - agentcore\_gateway\_mcp\_client.py SigV4 MCP client using `httpx`
+    - app/
+      - \<gateway\_snake>\_client.py Per-Gateway client wrapper
+    - \_\_init\_\_.py Re-exports the Gateway client
+
+</FileTree>
+
+Additionally, the generator:
+
+- Modifies your agent's `agent.py` to import the Gateway client, enter it via a `with` block, and register its tools in `tools`
+- Adds `agent_connection` as a workspace dependency of the agent
+- Wires the agent's `<agent>-serve-local` target to depend on the Gateway's `<gateway>-serve-local` aggregator
+
+## Using the connected Gateway
+
+The generator transforms your agent's `agent.py` to use the Gateway client:
+
+```python title="packages/example/example/my_agent/agent.py" {4,8,9-13}
+from contextlib import contextmanager
+from strands import Agent
+
+from my_scope_agent_connection import MyGatewayClient
+
+@contextmanager
+def get_agent():
+    my_gateway = MyGatewayClient.create()
+    with (
+        my_gateway,
+    ):
+        yield Agent(
+            system_prompt="...",
+            tools=[*my_gateway.list_tools_sync()],
+        )
+```
+
+`MyGatewayClient.create()` returns a single context-manageable client whose `list_tools_sync()` yields every tool available through the Gateway:
+
+- **Deployed mode** (`SERVE_LOCAL` unset): a single `MCPClient` pointed at the Gateway's MCP endpoint, SigV4-signed.
+- **Local mode** (`SERVE_LOCAL=true`): a plain-HTTP `MCPClient` pointed at the local gateway started by the Gateway project's `serve-local` target.
+
+The session ID is propagated to downstream MCP servers automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header.
+
+## Infrastructure
+
+After running the generator you must grant the agent permission to invoke the Gateway.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const gateway = new MyGateway(this, 'MyGateway');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the Gateway
+gateway.grantInvokeAccess(myAgent);
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf" {12-24}
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+}
+
+# Grant the agent permission to invoke the Gateway
+resource "aws_iam_policy" "agent_invoke_gateway" {
+  name = "AgentInvokeGatewayPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = "bedrock-agentcore:InvokeGateway"
+      Resource = module.my_gateway.gateway_arn
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "agent_invoke_gateway" {
+  role       = module.my_agent.agent_core_runtime_role_arn
+  policy_arn = aws_iam_policy.agent_invoke_gateway.arn
+}
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `serve-local` target to:
+
+1. Start the connected Gateway's local gateway and every attached MCP server
+2. Set `SERVE_LOCAL=true` so the generated client points at the local gateway instead of the deployed Gateway
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+
+To run the agent locally **against the deployed Gateway** instead (for example, to exercise Cedar policies), use the agent's `serve` target. Without `SERVE_LOCAL` set, the client resolves the deployed Gateway URL from runtime configuration and SigV4-signs requests with your local AWS credentials:
+
+<NxCommands commands={["<agent-name>-serve <project-name>"]} />
+
+### Local fidelity
+
+The local gateway stands in for the deployed Gateway, so:
+
+- **No Cedar policy evaluation.** Every tool is visible to the agent regardless of policies. Use the `serve` target to exercise policies against the deployed Gateway.
+- **Tool-name prefixing is preserved.** Each local MCP server's tools are exposed as `<target-name>___<tool-name>`, matching what the deployed Gateway emits. This keeps the agent's system prompt and the Cedar action names you reference consistent across local and deployed runs.

package/docs/guides/connection/ts-agent-gateway.mdx

@@ -0,0 +1,150 @@
+---
+title: TypeScript Agent to Gateway
+description: Connect a TypeScript Agent to an AgentCore Gateway
+when:
+  sourceType: ts#agent
+  targetType: agentcore-gateway
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can connect your <Link path="guides/ts-agent">TypeScript Agent</Link> to an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+The generator wires the agent so it authenticates to the Gateway with IAM SigV4 when deployed, and connects to the local gateway started by the Gateway project when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A TypeScript project with a <Link path="guides/ts-agent">Agent</Link> component (`infra: agentcore`)
+2. A <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the agent project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator emits shared core client files into your `agent-connection` package, plus a per-Gateway wrapper, and modifies your agent:
+
+<FileTree>
+
+- packages/common/agent-connection
+  - src
+    - core/
+      - agentcore-gateway-mcp-client.ts SigV4 MCP client for the deployed Gateway
+    - app/
+      - \<gateway-kebab>-client.ts Per-Gateway client wrapper
+    - index.ts Re-exports the Gateway client
+
+</FileTree>
+
+Additionally, the generator:
+
+- Modifies your agent's `agent.ts` to import the Gateway client class, call `<Gateway>Client.create()`, and register the returned client in the `tools` array
+- Wires the agent's `<agent>-serve-local` target to depend on the Gateway's `<gateway>-serve-local` aggregator
+- Installs the required SigV4 / MCP dependencies
+
+## Using the connected Gateway
+
+The generator transforms your agent's `agent.ts` to use the Gateway client:
+
+```ts title="packages/example/src/my-agent/agent.ts" {2,5,8}
+import { Agent } from '@strands-agents/sdk';
+import { MyGatewayClient } from ':my-scope/agent-connection';
+
+export const getAgent = async () => {
+  const myGateway = await MyGatewayClient.create();
+  return new Agent({
+    systemPrompt: '...',
+    tools: [myGateway],
+  });
+};
+```
+
+When deployed (`SERVE_LOCAL` unset), the client points at the Gateway's MCP endpoint and authenticates with SigV4. When `SERVE_LOCAL=true`, it points at the local gateway started by the Gateway project's `serve-local` target, so the same `agent.ts` works uniformly in both modes.
+
+The session ID is propagated to downstream MCP servers automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header.
+
+## Infrastructure
+
+After running the generator you must grant the agent permission to invoke the Gateway.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const gateway = new MyGateway(this, 'MyGateway');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the Gateway
+gateway.grantInvokeAccess(myAgent);
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf" {12-24}
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+}
+
+# Grant the agent permission to invoke the Gateway
+resource "aws_iam_policy" "agent_invoke_gateway" {
+  name = "AgentInvokeGatewayPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = "bedrock-agentcore:InvokeGateway"
+      Resource = module.my_gateway.gateway_arn
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "agent_invoke_gateway" {
+  role       = module.my_agent.agent_core_runtime_role_arn
+  policy_arn = aws_iam_policy.agent_invoke_gateway.arn
+}
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `serve-local` target to:
+
+1. Start the connected Gateway's local gateway and every attached MCP server
+2. Set `SERVE_LOCAL=true` so the generated client points at the local gateway instead of the deployed Gateway
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+
+To run the agent locally **against the deployed Gateway** instead (for example, to exercise Cedar policies), use the agent's `serve` target. Without `SERVE_LOCAL` set, the client resolves the deployed Gateway URL from runtime configuration and SigV4-signs requests with your local AWS credentials:
+
+<NxCommands commands={["<agent-name>-serve <project-name>"]} />
+
+### Local fidelity
+
+The local gateway stands in for the deployed Gateway, so:
+
+- **No Cedar policy evaluation.** Every tool is visible to the agent regardless of policies. Use the `serve` target to exercise policies against the deployed Gateway.
+- **Tool-name prefixing is preserved.** Each local MCP server's tools are wrapped to expose names of the form `<target-name>___<tool-name>`, matching what the deployed Gateway emits. This keeps an agent's system prompt and the Cedar action names you reference consistent across local and deployed runs.

package/docs/guides/connection.mdx

@@ -148,6 +148,29 @@ The Connection generator supports the following connections:
     source="mcp"
     target="dynamodb"
   />
+  <ConnectionCard
+    title="AgentCore Gateway to MCP Server"
+    description="Aggregate an MCP server behind an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-mcp`}
+    source="agentcore"
+    target="mcp"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to AgentCore Gateway"
+    description="Connect a TypeScript Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-gateway`}
+    source="strands"
+    sourceBadge="typescript"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="Python Agent to AgentCore Gateway"
+    description="Connect a Python Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-gateway`}
+    source="strands"
+    sourceBadge="python"
+    target="agentcore"
+  />
 </CardGrid>
 
 :::note[Runtime Configuration]

package/docs/guides/nx-generator.mdx

@@ -583,6 +583,7 @@ When this generator is run in our repository, it'll generate the following files
   - docs/src/content/docs/guides/
     - \<name>.mdx Documentation page for your generator
   - packages/nx-plugin/generators.json Updated to include your generator
+  - packages/nx-plugin/sdk/\<prefix>.ts Updated to expose your generator from the SDK (for `ts#` and `py#` generators)
 </FileTree>
 
 You can then start to implement your generator.

package/generators.json

@@ -3,6 +3,19 @@
   "name": "@aws/nx-plugin",
   "version": "0.0.1",
   "generators": {
+    "agentcore-gateway": {
+      "factory": "./src/agentcore-gateway/generator",
+      "schema": "./src/agentcore-gateway/schema.json",
+      "description": "Generate an AgentCore Gateway project",
+      "metric": "g48"
+    },
+    "agentcore-gateway#mcp-connection": {
+      "factory": "./src/agentcore-gateway/mcp-connection/generator",
+      "schema": "./src/agentcore-gateway/mcp-connection/schema.json",
+      "description": "Connect an AgentCore Gateway to an MCP server",
+      "metric": "g49",
+      "hidden": true
+    },
     "connection": {
       "factory": "./src/connection/generator",
       "schema": "./src/connection/schema.json",
@@ -23,7 +36,10 @@
         "connection/trpc-rdb",
         "connection/smithy-rdb",
         "connection/ts-mcp-server-rdb",
-        "connection/ts-agent-rdb"
+        "connection/ts-agent-rdb",
+        "connection/ts-agent-gateway",
+        "connection/py-agent-gateway",
+        "connection/agentcore-gateway-mcp"
       ]
     },
     "license": {
@@ -279,6 +295,13 @@
       "metric": "g35",
       "hidden": true
     },
+    "ts#agent#gateway-connection": {
+      "factory": "./src/ts/agent/gateway-connection/generator",
+      "schema": "./src/ts/agent/gateway-connection/schema.json",
+      "description": "Connect a TypeScript Agent to an AgentCore Gateway",
+      "metric": "g50",
+      "hidden": true
+    },
     "py#agent#a2a-connection": {
       "factory": "./src/py/agent/a2a-connection/generator",
       "schema": "./src/py/agent/a2a-connection/schema.json",
@@ -286,6 +309,13 @@
       "metric": "g36",
       "hidden": true
     },
+    "py#agent#gateway-connection": {
+      "factory": "./src/py/agent/gateway-connection/generator",
+      "schema": "./src/py/agent/gateway-connection/schema.json",
+      "description": "Connect a Python Agent to an AgentCore Gateway",
+      "metric": "g51",
+      "hidden": true
+    },
     "ts#sync": {
       "factory": "./src/ts/sync/generator",
       "schema": "./src/ts/sync/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.12",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/agentcore-gateway/mcp-connection/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-gateway#mcp-connection",
+  "title": "agentcore-gateway#mcp-connection",
+  "description": "Connect an AgentCore Gateway to an MCP server",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The gateway project"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The MCP server project"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The gateway component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The MCP server component in the target project"
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}

package/src/agentcore-gateway/schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-gateway",
+  "title": "agentcore-gateway",
+  "description": "Generate an AgentCore Gateway project",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of your AgentCore Gateway project",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What would you like to call your AgentCore Gateway?",
+      "x-priority": "important"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Parent directory where the gateway project is placed.",
+      "default": "packages"
+    },
+    "subDirectory": {
+      "type": "string",
+      "description": "The sub directory the project is placed in. By default this is the project name."
+    },
+    "protocol": {
+      "type": "string",
+      "description": "The inbound protocol exposed by your gateway. Only mcp is supported today; additional protocols may be added in future.",
+      "enum": ["mcp"],
+      "default": "mcp",
+      "x-priority": "important"
+    },
+    "auth": {
+      "type": "string",
+      "description": "The method used to authenticate inbound requests to your gateway. Only iam is supported today; cognito and custom-jwt may be added in future.",
+      "enum": ["iam"],
+      "default": "iam",
+      "x-priority": "important"
+    },
+    "cedarPolicy": {
+      "type": "boolean",
+      "description": "Whether to include a Cedar policy engine enforcing fine-grained authorization on the gateway.",
+      "default": true,
+      "x-priority": "important"
+    },
+    "infra": {
+      "type": "string",
+      "description": "The type of infrastructure to host your gateway. Select none for no hosting.",
+      "x-prompt": "How would you like to host your gateway?",
+      "enum": ["agentcore", "none"],
+      "default": "agentcore",
+      "x-priority": "important"
+    },
+    "iac": {
+      "type": "string",
+      "description": "The preferred IaC provider. By default this is inherited from your initial selection.",
+      "enum": ["inherit", "cdk", "terraform"],
+      "x-priority": "important",
+      "default": "inherit",
+      "x-prompt": "Which provider would you like to manage your infrastructure? (default: inherit)"
+    }
+  },
+  "required": ["name"]
+}

package/src/py/agent/gateway-connection/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "py#agent#gateway-connection",
+  "title": "py#agent#gateway-connection",
+  "description": "Connect a Python Agent to an AgentCore Gateway",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The Python Agent project"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The AgentCore Gateway project"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The agent component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The gateway component in the target project"
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}

package/src/ts/agent/gateway-connection/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "ts#agent#gateway-connection",
+  "title": "ts#agent#gateway-connection",
+  "description": "Connect a TypeScript Agent to an AgentCore Gateway",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The TypeScript Agent project"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The AgentCore Gateway project"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The agent component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The gateway component in the target project"
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}