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

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/docs/guides/py-agent.mdx

@@ -351,19 +351,58 @@ This command uses `uv run` to execute your Agent using the [Bedrock AgentCore Py
 
 ### Chat with Your Agent
 
-The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
+The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
+
+The chat target runs standalone. By default it connects to your locally running agent, so start `<your-agent-name>-serve-local` first (in a separate terminal):
+
+<NxCommands commands={['run your-project:agent-serve-local']} />
+
+Then, in another terminal, start the chat:
 
 <NxCommands commands={['run your-project:agent-chat']} />
 
-For **HTTP** agents, the generator also emits:
+The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. It connects to the local agent by default, or to your deployed agent when `RUNTIME_CONFIG_APP_ID` is set (see [Chat with your deployed agent](#chat-with-your-deployed-agent) below).
+
+For **HTTP** agents, the chat script uses a type-safe TypeScript client generated from the agent's OpenAPI spec. The generator also emits:
 
 - `scripts/<your-agent-name>_openapi.py` — a small script that exports the agent's OpenAPI spec
 - An `<your-agent-name>-openapi` Nx target that runs it
 - An `<your-agent-name>-generate-client` Nx target that produces a type-safe TypeScript client under `scripts/<your-agent-name>/generated/`
-- `scripts/<your-agent-name>/chat.ts` — a thin wrapper around the generated client
 
 When you customize the agent's input shape (e.g. add new fields to `InvokeInput`), update `chat.ts` to pass the new fields when invoking the agent and the rest works automatically.
 
+<OptionFilter when={{ infra: 'agentcore' }} description="Deployed agent chat details">
+#### Chat with your deployed agent
+
+To chat with your agent deployed to Bedrock AgentCore, set the `RUNTIME_CONFIG_APP_ID` environment variable to the AppConfig application id of the deployment (output as `RuntimeConfigApplicationId` by the deployed stack). The chat script resolves your agent's runtime ARN from runtime configuration and connects to the deployed endpoint:
+
+<Tabs syncKey="auth">
+<TabItem label="IAM" _filter={{ auth: 'iam' }}>
+For IAM-authenticated agents, requests are signed with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>' }} />
+</TabItem>
+
+<TabItem label="Cognito" _filter={{ auth: 'cognito' }}>
+For Cognito-authenticated agents, provide a Cognito access token via the `AGENT_ACCESS_TOKEN` environment variable, which is sent as a bearer token:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>', AGENT_ACCESS_TOKEN: '<access-token>' }} />
+
+You can obtain an access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
+
+```bash
+aws cognito-idp admin-initiate-auth \
+  --user-pool-id <user-pool-id> \
+  --client-id <user-pool-client-id> \
+  --auth-flow ADMIN_NO_SRP_AUTH \
+  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
+  --query 'AuthenticationResult.AccessToken' \
+  --output text
+```
+</TabItem>
+</Tabs>
+</OptionFilter>
+
 <OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your Agent to Bedrock AgentCore Runtime
 

package/docs/guides/ts-agent.mdx

@@ -269,11 +269,49 @@ This command uses `tsx --watch` to automatically restart the server when files c
 
 ### Chat with Your Agent
 
-The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
+The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
+
+The chat target runs standalone. By default it connects to your locally running agent, so start `<your-agent-name>-serve-local` first (in a separate terminal):
+
+<NxCommands commands={['run your-project:agent-serve-local']} />
+
+Then, in another terminal, start the chat:
 
 <NxCommands commands={['run your-project:agent-chat']} />
 
-For **HTTP** (tRPC over WebSocket) agents, the generator also emits a tiny `scripts/<your-agent-name>/chat.ts` that wraps the generated `<Agent>Client.local({ url })` so you can customize it as you evolve the agent's input shape.
+The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. You can customize it as you evolve the agent's input shape. It connects to the local agent by default, or to your deployed agent when `RUNTIME_CONFIG_APP_ID` is set (see [Chat with your deployed agent](#chat-with-your-deployed-agent) below).
+
+<OptionFilter when={{ infra: 'agentcore' }} description="Deployed agent chat details">
+#### Chat with your deployed agent
+
+To chat with your agent deployed to Bedrock AgentCore, set the `RUNTIME_CONFIG_APP_ID` environment variable to the AppConfig application id of the deployment (output as `RuntimeConfigApplicationId` by the deployed stack). The chat script resolves your agent's runtime ARN from runtime configuration and connects to the deployed endpoint:
+
+<Tabs syncKey="auth">
+<TabItem label="IAM" _filter={{ auth: 'iam' }}>
+For IAM-authenticated agents, requests are signed with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>' }} />
+</TabItem>
+
+<TabItem label="Cognito" _filter={{ auth: 'cognito' }}>
+For Cognito-authenticated agents, provide a Cognito access token via the `AGENT_ACCESS_TOKEN` environment variable, which is sent as a bearer token:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>', AGENT_ACCESS_TOKEN: '<access-token>' }} />
+
+You can obtain an access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
+
+```bash
+aws cognito-idp admin-initiate-auth \
+  --user-pool-id <user-pool-id> \
+  --client-id <user-pool-client-id> \
+  --auth-flow ADMIN_NO_SRP_AUTH \
+  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
+  --query 'AuthenticationResult.AccessToken' \
+  --output text
+```
+</TabItem>
+</Tabs>
+</OptionFilter>
 
 <OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your Agent to Bedrock AgentCore Runtime

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.13",
   "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"]
+}