@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71

package/docs/guides/agentcore-gateway.mdx

@@ -0,0 +1,490 @@
+---
+title: AgentCore Gateway
+description: Create an AgentCore Gateway project
+generator: agentcore-gateway
+---
+
+import { FileTree, CardGrid } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
+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 in front of your MCP servers or agents, authenticating inbound requests (IAM or Cognito) and signing outbound traffic to its targets with IAM SigV4.
+
+The `protocol` option selects what the Gateway fronts:
+
+- **`mcp`** (default) — aggregates one or more MCP server targets behind a single MCP endpoint, and evaluates every tool call against a [Cedar policy engine](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy.html).
+- **`http`** — proxies requests directly to [AgentCore Runtime targets](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-http-runtime.html) (your agents) via path-based routing (`/<targetName>/invocations`), without aggregation or protocol translation. Use this to front agents with a single governed endpoint — for example so a website can reach agents that are deployed inside a VPC through the Gateway.
+
+## 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 (`mcp` protocol only; omitted when `cedarPolicy: false`)
+      - permit-all.cedar Default Cedar policy that permits authenticated callers
+      - README.md Reference for writing Cedar policies
+    - local-dev.ts Local gateway for local development — aggregates attached MCP servers (`mcp`) or proxies attached agents (`http`)
+    - project.json Adds the `serve` and `dev` 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` with inbound IAM authentication (default) or Cognito JWT authentication (see <a href="#authentication">Authentication</a>). An `mcp` gateway is configured for the MCP protocol; an `http` gateway has no protocol type, which AgentCore requires for its runtime targets
+- An `AgentCore::PolicyEngine` running in `ENFORCE` mode, attached to the Gateway (`mcp` gateways only; omitted when `cedarPolicy: false`)
+- One `AgentCore::Policy` per `.cedar` file in `policies/` (`mcp` gateways only)
+- An AWS WAFv2 Web ACL associated with the Gateway, with request logging to CloudWatch (enabled by default — see <a href="#aws-waf">AWS WAF</a>)
+
+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.
+
+#### Architecture
+
+The deployed Gateway has the following architecture, with an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL in front of the Gateway, which routes on to its downstream MCP server targets:
+
+```d2 inline=true
+direction: right
+
+client: Client {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+waf: WAF {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/waf.svg
+}
+
+gateway: AgentCore Gateway\n(MCP, IAM or Cognito auth) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-gateway.svg
+}
+
+targets: Downstream MCP Servers\n(Gateway targets) {
+  shape: rectangle
+}
+
+client -> waf
+waf -> gateway
+gateway -> targets
+```
+
+## Authentication
+
+The `auth` option configures how the Gateway authenticates inbound requests. Choose between `iam` (default) and `cognito`.
+
+### IAM
+
+By default, the Gateway is configured with `GatewayAuthorizer.usingAwsIam()`. Callers sign requests with SigV4, and the caller's IAM identity is available to Cedar policies as an `AgentCore::IamEntity` principal. This is the recommended option when your callers are agents or services running in AWS — for example an <Link path="/guides/ts-agent">agent</Link> connected via the <Link path="guides/connection/ts-agent-gateway">agent to Gateway connection generator</Link>, which signs its calls with its own execution role.
+
+### Cognito
+
+When you select `cognito`, the Gateway is configured with a Custom JWT authorizer pointing at a Cognito user pool. Callers authenticate by presenting a JWT bearer token, and the token's `sub` claim is available to Cedar policies as an `AgentCore::OAuthUser` principal. Use this when your callers authenticate through Cognito — for example a website or a coding agent connecting via the <Link path="guides/ts-dcr-proxy">`ts#dcr-proxy` generator</Link>.
+
+The generated infrastructure consumes an existing Cognito user pool and client — it does not create them. You can generate a `UserIdentity` using the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>, or provide your own.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The generated construct requires an `identity` prop supplying the user pool and client:
+
+```ts {7,9-11} title="packages/infra/src/stacks/application-stack.ts"
+import { MyGateway, UserIdentity } from ':my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const identity = new UserIdentity(this, 'Identity');
+
+    new MyGateway(this, 'MyGateway', {
+      identity,
+    });
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+The generated module requires `user_pool_id` and `user_pool_client_ids` variables:
+
+```hcl {7-8} title="packages/infra/src/main.tf"
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+module "my_gateway" {
+  source               = "../../common/terraform/src/app/gateways/my-gateway"
+  user_pool_id         = module.user_identity.user_pool_id
+  user_pool_client_ids = [module.user_identity.user_pool_client_id]
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::note[Custom OIDC providers]
+To authenticate with a non-Cognito OIDC provider, modify the generated Gateway construct or Terraform module directly — swap the authorizer's discovery URL and allowed clients for your provider's. Agent to Gateway connection generators only support `IAM`-authenticated gateways, since agents sign their calls with SigV4.
+:::
+
+## 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 {5-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 scoped to the Gateway's authentication type.
+
+For an **IAM** Gateway, it 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 %>:*"
+};
+```
+
+For a **Cognito** Gateway, it permits any authenticated OAuth user (the JWT authorizer has already validated the token's user pool and client before policies are evaluated):
+
+```cedar title="packages/<name>/policies/permit-all.cedar"
+permit (
+  principal is AgentCore::OAuthUser,
+  action,
+  resource == AgentCore::Gateway::"<%= gatewayArn %>"
+);
+```
+
+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
+
+The principal type depends on how the Gateway authenticates callers (see <a href="#authentication">Authentication</a>).
+
+For an **IAM** Gateway, callers are IAM principals:
+
+```
+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`.
+
+For a **Cognito** Gateway, callers are OAuth users built from the JWT token's `sub` claim, and JWT claims (username, scope, etc.) are available as principal tags:
+
+```
+principal is AgentCore::OAuthUser
+```
+
+Match individual claims in `when` clauses — for example to require a scope:
+
+```cedar
+permit (
+  principal is AgentCore::OAuthUser,
+  action,
+  resource == AgentCore::Gateway::"<%= gatewayArn %>"
+) when {
+  principal.scope == "gateway/invoke"
+};
+```
+
+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 `dev` target to the Gateway project, which runs `local-dev.ts`. Running it starts the local gateway and every attached target together:
+
+<NxCommands commands={["dev <name>"]} />
+
+<OptionFilter when={{ protocol: 'mcp' }} description="MCP aggregator local gateway">
+The local gateway exposes 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.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'http' }} description="Path-routing proxy local gateway">
+The local gateway proxies `/<targetName>/...` paths to each attached agent's local server (connected via the <Link path="guides/connection/agentcore-gateway-agent">`agentcore-gateway#agent-connection` generator</Link>), matching the deployed Gateway's path-based routing.
+</OptionFilter>
+
+See the connection guides for the full local development story.
+
+## Deploying your AgentCore Gateway
+
+The AgentCore Gateway generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your Gateway.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The CDK construct for deploying your Gateway lives in the `common/constructs` folder. You can consume this in a CDK application, for example:
+
+```ts {7} title="packages/infra/src/stacks/application-stack.ts"
+import { MyGateway } from '@my-scope/common-constructs';
+
+export class ApplicationStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    new MyGateway(this, 'MyGateway');
+  }
+}
+```
+
+This sets up your Gateway infrastructure, including the `AgentCore::Gateway`, its Cedar `PolicyEngine`, and the AWS WAF Web ACL (see [AWS WAF](#aws-waf) below). Register MCP server targets with `gateway.addMcpServer(...)` — see the <Link path="guides/connection/agentcore-gateway-mcp">MCP server connection guide</Link>.
+</Fragment>
+<Fragment slot="terraform">
+The Terraform module for deploying your Gateway is in the `common/terraform` folder. You can use this in a Terraform configuration, for example:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+}
+```
+
+This sets up your Gateway infrastructure, including the `aws_bedrockagentcore_gateway`, its Cedar policy engine, and the AWS WAF Web ACL (see [AWS WAF](#aws-waf) below). Register MCP server targets with an `aws_bedrockagentcore_gateway_target` resource — see the <Link path="guides/connection/agentcore-gateway-mcp">MCP server connection guide</Link>.
+</Fragment>
+</Infrastructure>
+
+### AWS WAF
+
+By default, the generated construct associates an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL with the Gateway. AWS WAF inspects every inbound request inline _before_ it reaches a target, protecting your Gateway from web exploits, bot traffic, and volumetric attacks. The Web ACL uses the AWS managed default ruleset ([`AWSManagedRulesCommonRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-crs) and [`AWSManagedRulesKnownBadInputsRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-known-bad-inputs)), providing protection against common web exploits including the OWASP Top 10. WAF request logs are written to a CloudWatch Logs group.
+
+The Web ACL is `REGIONAL` and created in the Gateway's region, as required for AgentCore Gateway associations.
+
+:::caution[SizeRestrictions_BODY deviation from defaults]
+The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for typical MCP tool payloads. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details.
+:::
+
+You can edit the generated Gateway construct to add, remove, or adjust rules (for example, to add [rate-based rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-type-rate-based.html) or additional managed rule groups).
+
+<Infrastructure>
+<Fragment slot="cdk">
+To opt out (for example, to attach your own Web ACL), set `enableWaf` to `false` when you instantiate the Gateway construct:
+
+```ts {2}
+new MyGateway(this, 'MyGateway', {
+  enableWaf: false,
+});
+```
+
+The construct exposes the created Web ACL as `webAcl` for further configuration.
+</Fragment>
+<Fragment slot="terraform">
+To opt out (for example, to attach your own Web ACL), set `enable_waf` to `false` on the Gateway module:
+
+```hcl {2}
+module "my_gateway" {
+  enable_waf = false
+}
+```
+
+The module outputs the created Web ACL ARN as `waf_web_acl_arn` for further configuration.
+</Fragment>
+</Infrastructure>
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <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="AgentCore Gateway to AgentCore Gateway"
+    description="Aggregate an AgentCore Gateway behind another AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-gateway`}
+    source="agentcore"
+    target="agentcore"
+  />
+  <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"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to Agent"
+    description="Front an agent with an AgentCore Gateway as a runtime target"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-agent`}
+    source="agentcore"
+    target="strands"
+  />
+  <ConnectionCard
+    title="React Website to AgentCore Gateway"
+    description="Connect a React website to agents through an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agentcore-gateway`}
+    source="react"
+    target="agentcore"
+  />
+</CardGrid>