@aws/nx-plugin-mcp 1.0.0-rc.2 → 1.0.0-rc.21

package/docs/guides/agentcore-gateway.mdx

@@ -0,0 +1,240 @@
+---
+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 another Gateway: <Link path="guides/connection/agentcore-gateway-gateway">`agentcore-gateway#gateway-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-gateway.mdx

@@ -0,0 +1,154 @@
+---
+title: AgentCore Gateway to AgentCore Gateway
+description: Connect an AgentCore Gateway to another AgentCore Gateway
+when:
+  sourceType: agentcore-gateway
+  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 register an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link> 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 <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> 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
+
+<RunGenerator generator="connection" />
+
+Select the aggregating Gateway project as the source and the Gateway to be aggregated as the target.
+
+### 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/\<source-gateway>
+  - project.json `<source-gateway>-serve-local` gains a dependency on the target gateway's `<target-gateway>-serve-local`
+  - serve-local.ts `ATTACHED_MCP_SERVERS` updated so the local gateway aggregates the target gateway
+
+</FileTree>
+
+The source Gateway project's `<source-gateway>-serve-local` target gains a dependency on the target Gateway's `<target-gateway>-serve-local` 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 `serve-local.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.
+
+<Infrastructure>
+<Fragment slot="cdk">
+In the stack where you instantiate the Gateways, register the target gateway as a target of the source gateway:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {5-6}
+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 <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
+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.
+</Fragment>
+<Fragment slot="terraform">
+In the Terraform file where you instantiate the Gateways, wire the gateway target in:
+
+```hcl title="packages/infra/src/main.tf" {2-5,11-15,18-36}
+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 <Link path="guides/agentcore-gateway">Writing Policies section</Link>. 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.
+
+:::note[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.
+:::
+</Fragment>
+</Infrastructure>
+
+## 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:
+
+<NxCommands commands={["<source-gateway-name>-serve-local"]} />
+
+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.
+
+:::caution[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 <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.
+:::

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-a2a.mdx

@@ -48,9 +48,12 @@ The generator creates a shared `agent_connection` Python project at `packages/co
   - \<scope>\_agent\_connection
     - \_\_init\_\_.py Re-exports per-connection clients
     - core
-      - agentcore\_a2a\_client.py Core AgentCore A2A client with SigV4 authentication
+      - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - agentcore\_a2a\_client\_config.py Framework-agnostic A2A client config (signed `ClientConfig`)
+      - agentcore\_a2a\_client\_strands.py Strands A2A client wrapping the config
+      - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
     - app
-      - \<target\_agent\_name>\_client.py Per-connection client for each A2A agent
+      - \<target\_agent\_name>\_client\_strands.py Per-connection Strands client for each A2A agent
 
 </FileTree>
 
@@ -67,11 +70,11 @@ The generator transforms your agent's `agent.py` to wrap the remote A2A agent as
 from contextlib import contextmanager
 from strands import Agent, tool
 
-from my_scope_agent_connection import RemoteAgentClient
+from my_scope_agent_connection import RemoteAgentClientStrands
 
 @contextmanager
 def get_agent(session_id: str):
-    remote_agent = RemoteAgentClient.create(session_id=session_id)
+    remote_agent = RemoteAgentClientStrands.create(session_id=session_id)
 
     @tool
     def ask_remote_agent(prompt: str) -> str:
@@ -86,7 +89,7 @@ def get_agent(session_id: str):
 
 The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
-Under the hood, `RemoteAgentClient.create(session_id=...)` returns a Strands `A2AAgent` configured with an `httpx.AsyncClient` that signs requests with SigV4 when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+Under the hood, `RemoteAgentClientStrands.create(session_id=...)` returns a Strands `A2AAgent` configured with an `httpx.AsyncClient` that signs requests with SigV4 when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
 
 ## Infrastructure