@aws/nx-plugin-mcp 1.0.0-rc.91 → 1.0.0-rc.93

package/docs/get_started/tutorials/dungeon-game/1.mdx

@@ -454,7 +454,6 @@ The `py#agent` generates these files:
         - session.py resolves a SessionManager for persisting conversation state
         - middleware/
           - session_id_middleware.py binds the inbound AgentCore session ID for the request
-        - Dockerfile defines the docker image for deployment to AgentCore Runtime
   - common/constructs/
     - src
       - app/agents/story-agent/
@@ -616,7 +615,6 @@ This is the entrypoint for the agent. Because we selected `--protocol=ag-ui`, th
 ```ts
 // common/constructs/src/app/agents/story-agent/story-agent.ts
 import { Fn, Lazy, Names, RemovalPolicy, Stack } from 'aws-cdk-lib';
-import { Platform } from 'aws-cdk-lib/aws-ecr-assets';
 import { Connections, IConnectable } from 'aws-cdk-lib/aws-ec2';
 import {
   BlockPublicAccess,
@@ -635,6 +633,7 @@ import { Construct } from 'constructs';
 import * as path from 'path';
 import * as url from 'url';
 import {
+  AgentCoreRuntime,
   AgentRuntimeArtifact,
   ProtocolType,
   Runtime,
@@ -678,7 +677,7 @@ export type StoryAgentProps = Omit<
 };
 
 export class StoryAgent extends Construct implements IGrantable, IConnectable {
-  public readonly dockerImage: AgentRuntimeArtifact;
+  public readonly code: AgentRuntimeArtifact;
   public readonly agentCoreRuntime: Runtime;
   /** Default Gateway target name for this agent. */
   public readonly agentName = 'story-agent';
@@ -690,14 +689,19 @@ export class StoryAgent extends Construct implements IGrantable, IConnectable {
 
     const rc = RuntimeConfig.ensure(this);
 
-    // Resolve the bundle output directory containing the Dockerfile and built artifacts
+    // Resolve the packaged code directory, uploaded as a zip asset
     const bundleDir = path.join(
       findWorkspaceRoot(url.fileURLToPath(new URL(import.meta.url))),
-      'dist/packages/story/docker/story-agent',
+      'dist/packages/story/package/story-agent',
     );
 
-    this.dockerImage = AgentRuntimeArtifact.fromAsset(bundleDir, {
-      platform: Platform.LINUX_ARM64,
+    // The `opentelemetry-instrument` prefix auto-instruments with the AWS Distro
+    // for OpenTelemetry packaged alongside the code.
+    // https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html
+    this.code = AgentRuntimeArtifact.fromCodeAsset({
+      path: bundleDir,
+      runtime: AgentCoreRuntime.PYTHON_3_14,
+      entrypoint: ['opentelemetry-instrument', 'main.py'],
     });
 
     const {
@@ -817,7 +821,7 @@ export class StoryAgent extends Construct implements IGrantable, IConnectable {
           Names.uniqueResourceName(this.agentCoreRuntime, { maxLength: 40 }),
       }),
       protocolConfiguration: ProtocolType.HTTP,
-      agentRuntimeArtifact: this.dockerImage,
+      agentRuntimeArtifact: this.code,
       authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito(
         identity.userPool,
         [identity.userPoolClient],

package/docs/get_started/tutorials/dungeon-game/overview.mdx

@@ -138,7 +138,7 @@ Before you proceed, you will need the following global dependencies:
 
 <Snippet name="required-prerequisites" />
 - [AWS Credentials](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) configured to your target AWS account, since this tutorial deploys the application and invokes Amazon Bedrock
-- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development and for building the AgentCore components
+- [Docker](https://www.docker.com/) (or [Finch](https://github.com/runfinch/finch)) is required for local DynamoDB development
 
 :::tip[AI Assistant Setup]
 If you use an AI Assistant such as Kiro, Kiro CLI, Cursor, Claude Code or Cline, refer to the <Link path="/get_started/building-with-ai">install the Nx Plugin for AWS MCP server</Link> page.

package/docs/guides/docker-bundling.mdx

@@ -379,10 +379,12 @@ Use the `DockerImageAsset` with any AWS construct that accepts a container image
 Terraform's AWS provider does not have a first-class "build and push a Docker image" resource. The pattern used by the generators is:
 
 1. The project's `build` target runs `docker build`, producing a local image tagged `my-scope-my-project:latest`.
-2. An `aws_ecr_repository` to hold the image.
+2. A shared ECR repository using the `core/asset-ecr` module
 3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image with its content digest, and pushes it.
 4. The downstream resource (e.g. `aws_ecs_task_definition`) references the image by its immutable, digest-based tag.
 
+Because one repository holds every image, each tag is namespaced by the image's owner as well as its digest, so images sharing the registry never collide.
+
 ```d2
 direction: down
 
@@ -407,7 +409,7 @@ app: Application {
 infra: Infrastructure {
   direction: right
   publish: "null_resource\nlocal-exec: docker push"
-  repo: aws_ecr_repository
+  repo: "core/asset-ecr\n(shared)"
   publish -> repo: tag + push
 }
 
@@ -421,10 +423,8 @@ infra.repo -> ecr
 
 
 ```hcl
-resource "aws_ecr_repository" "repo" {
-  name                 = "my-project-repository"
-  image_tag_mutability = "IMMUTABLE"
-  force_delete         = true
+module "asset_ecr" {
+  source = "../../common/terraform/src/core/asset-ecr"
 }
 
 # Invalidate the push whenever the locally-built image digest changes
@@ -433,14 +433,15 @@ data "external" "docker_digest" {
 }
 
 locals {
-  # Content-based, immutable image tag derived from the local image digest
-  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+  # Content-based, immutable image tag derived from the local image digest, and
+  # namespaced by owner so images sharing the registry never collide
+  image_tag = "my-project-${replace(data.external.docker_digest.result.digest, "sha256:", "")}"
 }
 
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest  = data.external.docker_digest.result.digest
-    repository_url = aws_ecr_repository.repo.repository_url
+    repository_url = module.asset_ecr.repository_url
     image_tag      = local.image_tag
   }
 
@@ -455,7 +456,7 @@ resource "null_resource" "docker_publish" {
 }
 ```
 
-The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change. The image is pushed under an immutable, content-based tag derived from its digest, so the ECR repository can use `IMMUTABLE` tag mutability and reject any attempt to overwrite an existing tag.
+The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change. The image is pushed under an immutable, content-based tag derived from its digest, so the shared repository uses `IMMUTABLE` tag mutability and rejects any attempt to overwrite an existing tag.
 
 :::note[Running bundle before apply]
 `nx apply <project>` requires the image tag `my-scope-my-project:latest` to already exist locally. Run `nx build my-project` (or `nx docker my-project`) before `nx apply <project>`.

package/docs/guides/py-agent.mdx

@@ -55,7 +55,7 @@ The generator will add the following files to your existing Python project. The
           - \_\_init\_\_.py Python package initialization
           - session_id_middleware.py Binds the inbound AgentCore session ID for the request
         - main.py FastAPI entry point for Bedrock AgentCore Runtime
-        - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - pyproject.toml Updated with Strands dependencies
     - project.json Updated with agent serve targets
 </FileTree>
@@ -77,7 +77,7 @@ The entry point exposes your agent over the A2A protocol (Strands uses the [Stra
           - \_\_init\_\_.py Python package initialization
           - session_id_middleware.py Binds the inbound AgentCore session ID for the request
         - main.py A2A server entry point
-        - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - pyproject.toml Updated with framework and A2A dependencies
     - project.json Updated with agent serve targets
 </FileTree>
@@ -99,7 +99,7 @@ The entry point exposes your agent via the [AG-UI](https://docs.ag-ui.com/) prot
           - \_\_init\_\_.py Python package initialization
           - session_id_middleware.py Binds the inbound AgentCore session ID for the request
         - main.py AG-UI server entry point
-        - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - pyproject.toml Updated with framework and AG-UI dependencies
     - project.json Updated with agent serve targets
 </FileTree>
@@ -111,7 +111,9 @@ AG-UI agents can be connected to a React frontend using the <Link path="/guides/
 
 ### Infrastructure
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="agentcore-hosting" />
+
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment">
 <Snippet name="shared-constructs" />
 
 For deploying your Agent, the following files are generated:
@@ -136,6 +138,10 @@ For deploying your Agent, the following files are generated:
     - core
       - agent-core
         - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
+      - agent-core-code (when `infra` is `agentcore`)
+        - runtime.tf Packages your agent's code and delegates to `agent-core`
+      - agent-core-container (when `infra` is `agentcore-ecr`)
+        - runtime.tf Builds and publishes your agent's image and delegates to `agent-core`
 </FileTree>
 </Fragment>
 </Infrastructure>
@@ -296,7 +302,7 @@ Your agent's server protocol determines how it communicates. All options are ser
 
 The server entry point differs by framework (Strands yields a context-managed `Agent`, while LangChain drives a compiled `create_agent` graph), but the external contract for each protocol is the same.
 
-All protocols expose `/ping` for the AgentCore runtime health check contract. A2A agents listen on port `9000`; HTTP and AG-UI agents listen on port `8080`. The generated Dockerfile and infrastructure are configured for you.
+All protocols expose `/ping` for the AgentCore runtime health check contract. A2A agents listen on port `9000`; HTTP and AG-UI agents listen on port `8080`. The generated infrastructure is configured for you.
 
 <OptionFilter when={{ protocol: 'http' }} description="FastAPI HTTP server details">
 ## FastAPI Server (HTTP protocol)
@@ -441,7 +447,7 @@ For **HTTP** agents, the chat script uses a type-safe TypeScript client generate
 
 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">
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} 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:
@@ -473,7 +479,7 @@ aws cognito-idp admin-initiate-auth \
 </Tabs>
 </OptionFilter>
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your Agent to Bedrock AgentCore Runtime
 
 <Snippet name="agent/bedrock-deployment" parentHeading="Deploying Your Agent to Bedrock AgentCore Runtime" />
@@ -485,15 +491,21 @@ In order to build your Agent for Bedrock AgentCore Runtime, a `bundle` target is
 - Exports your Python dependencies to a `requirements.txt` file using `uv export`
 - Installs dependencies for the target platform (`aarch64-manylinux_2_28`) using `uv pip install`
 
+<OptionFilter when={{ infra: 'agentcore' }} description="Code package target">
+A `<your-agent-name>-package` target is also added, which assembles the deployable code package: the `aarch64` dependency bundle, your Python module tree, and a root `main.py` entry point. The generated infrastructure uploads this directory as a `.zip` — via `AgentRuntimeArtifact.fromCodeAsset` under CDK, or archived into the shared asset bucket under Terraform.
+</OptionFilter>
+
+<OptionFilter when={{ infra: 'agentcore-ecr' }} description="Container image build and scan">
 A `docker` target specific to your Agent is also added, which copies the `Dockerfile` and bundled artifacts into a docker context directory. This co-locates the `Dockerfile` with the built output, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
 
 ### Image Scanning
 
 <Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+</OptionFilter>
 
 ### Observability
 
-Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.
+Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT).
 
 You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
 

package/docs/guides/py-mcp-server.mdx

@@ -51,14 +51,16 @@ The generator will add the following files to your existing Python project:
         - server.py Main server definition with sample tools and resources
         - stdio.py Entry point for STDIO transport, useful for simple local MCP servers
         - http.py Entry point for Streamable HTTP transport, useful for hosting your MCP server
-        - Dockerfile Entry point for hosting your MCP server (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - pyproject.toml Updated with MCP dependencies
     - project.json Updated with MCP server serve targets
 </FileTree>
 
 ### Infrastructure
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="agentcore-hosting" />
+
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment">
 <Snippet name="shared-constructs" />
 
 <Snippet name="mcp/shared-constructs" />
@@ -157,7 +159,7 @@ If you would like to run your MCP server locally using [Streamable HTTP transpor
 
 This command uses `uv run uvicorn --reload` to run your MCP server with HTTP transport (typically on port `8000`), and automatically restarts when files change.
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your MCP Server to Bedrock AgentCore Runtime
 
 <Snippet name="mcp/bedrock-deployment" parentHeading="Deploying Your MCP Server to Bedrock AgentCore Runtime" />
@@ -169,11 +171,17 @@ In order to build your MCP server for Bedrock AgentCore Runtime, a `bundle` targ
 - Exports your Python dependencies to a `requirements.txt` file using `uv export`
 - Installs dependencies for the target platform (`aarch64-manylinux_2_28`) using `uv pip install`
 
+<OptionFilter when={{ infra: 'agentcore' }} description="Code package target">
+A `<your-server-name>-package` target is also added, which assembles the deployable code package: the `aarch64` dependency bundle, your Python module tree, and a root `main.py` entry point. The generated infrastructure uploads this directory as a `.zip` — via `AgentRuntimeArtifact.fromCodeAsset` under CDK, or archived into the shared asset bucket under Terraform.
+</OptionFilter>
+
+<OptionFilter when={{ infra: 'agentcore-ecr' }} description="Container image build and scan">
 A `docker` target specific to your MCP server is also added, which copies the `Dockerfile` and bundled artifacts into a docker context directory. This co-locates the `Dockerfile` with the built output, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
 
 ### Image Scanning
 
 <Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+</OptionFilter>
 
 ### Observability
 

package/docs/guides/react-website-auth.mdx

@@ -235,7 +235,7 @@ The user identity module automatically adds the necessary <Link path="guides/rea
 </Infrastructure>
 
 :::caution[Remove localhost callback URLs for production]
-The generated User Pool client allows your CloudFront distribution URL (and any custom domain names configured on it) as OAuth callback/logout URLs, plus `http://localhost:4200` and `http://localhost:4300` for local development against the deployed pool.
+The generated User Pool client allows your CloudFront distribution URL (and any custom domain names configured on it) as OAuth callback/logout URLs, plus each connected website's own local dev-server and preview URLs (e.g. `http://localhost:4200` and `http://localhost:4300` for the first website generated in a workspace) for local development against the deployed pool. Each website generated with `ts#website` is assigned its own distinct ports, so a workspace with multiple websites will have more than one `http://localhost:<port>` pair allow-listed here.
 
 It is recommended to **remove the `http://localhost` callback/logout URLs for production stages**, keeping the allowlist limited to your real application origins.
 

package/docs/guides/ts-agent.mdx

@@ -63,7 +63,7 @@ The generator will add the following files to your existing TypeScript project.
         - session.ts Resolves the SessionManager used to persist conversation state
         - client.ts Vended client for invoking your agent
         - agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
-        - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - package.json Updated with Strands dependencies
     - project.json Updated with agent serve targets
 </FileTree>
@@ -81,7 +81,7 @@ The entry point uses the [Strands A2A Express Server](https://strandsagents.com/
         - index.ts A2A Express server entry point
         - agent.ts Main agent definition with sample tools
         - session.ts Resolves the SessionManager used to persist conversation state
-        - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - package.json Updated with Strands and Express dependencies
     - project.json Updated with agent serve targets
 </FileTree>
@@ -99,7 +99,7 @@ The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui
         - index.ts AG-UI server entry point (Express + SSE)
         - agent.ts Main agent definition with sample tools
         - session.ts Resolves the SessionManager used to persist conversation state
-        - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - package.json Updated with Strands and AG-UI dependencies
     - project.json Updated with agent serve targets
 </FileTree>
@@ -107,7 +107,9 @@ The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui
 
 ### Infrastructure
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="agentcore-hosting" />
+
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment">
 <Snippet name="shared-constructs" />
 
 For deploying your Agent, the following files are generated:
@@ -132,6 +134,10 @@ For deploying your Agent, the following files are generated:
     - core
       - agent-core
         - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
+      - agent-core-code (when `infra` is `agentcore`)
+        - runtime.tf Packages your agent's code and delegates to `agent-core`
+      - agent-core-container (when `infra` is `agentcore-ecr`)
+        - runtime.tf Builds and publishes your agent's image and delegates to `agent-core`
 </FileTree>
 </Fragment>
 </Infrastructure>
@@ -249,7 +255,7 @@ For a more in-depth guide to writing Strands agents, refer to the [Strands docum
 
 The generated `index.ts` mounts the [Strands A2A Express Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) onto an Express app so the generated agent exposes the A2A protocol endpoints alongside a `/ping` health check. The URL advertised in the agent card comes from the `AGENTCORE_RUNTIME_URL` environment variable, falling back to `http://localhost:<port>/` for local development.
 
-Most users will not need to modify this file — edit `agent.ts` to change tools or the system prompt. A2A agents listen on port `9000` (vs `8080` for HTTP), which the generated Dockerfile and infrastructure are already configured for.
+Most users will not need to modify this file — edit `agent.ts` to change tools or the system prompt. A2A agents listen on port `9000` (vs `8080` for HTTP), which the generated infrastructure is already configured for.
 </OptionFilter>
 
 <OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI server details">
@@ -259,7 +265,7 @@ The generated `index.ts` wraps your Strands `Agent` in an [`@ag-ui/aws-strands`]
 
 AG-UI agents are designed to be consumed directly by a frontend. Use the <Link path="/guides/connection/react-agui">`connection` generator</Link> to wire your React website up to the agent with a [CopilotKit](https://docs.copilotkit.ai/aws-strands) provider and [AG-UI HttpAgent](https://docs.ag-ui.com/) client.
 
-Most users will not need to modify `index.ts` — edit `agent.ts` to change tools or the system prompt. AG-UI agents listen on port `8080` (same as HTTP), which the generated Dockerfile and infrastructure are already configured for.
+Most users will not need to modify `index.ts` — edit `agent.ts` to change tools or the system prompt. AG-UI agents listen on port `8080` (same as HTTP), which the generated infrastructure is already configured for.
 </OptionFilter>
 
 ## Running Your Agent
@@ -290,7 +296,7 @@ Then, in another terminal, start the chat:
 
 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">
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} 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:
@@ -322,7 +328,7 @@ aws cognito-idp admin-initiate-auth \
 </Tabs>
 </OptionFilter>
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your Agent to Bedrock AgentCore Runtime
 
 <Snippet name="agent/bedrock-deployment" parentHeading="Deploying Your Agent to Bedrock AgentCore Runtime" />
@@ -333,6 +339,13 @@ aws cognito-idp admin-initiate-auth \
 
 The bundle target uses `index.ts` as the entrypoint for the WebSocket server to host on Bedrock AgentCore Runtime.
 
+<OptionFilter when={{ infra: 'agentcore' }} description="Code package target">
+### Package Target
+
+The generator configures a `<your-agent-name>-package` target which assembles the deployable code package: the bundled `index.js` plus a vendored install of the AWS Distro for OpenTelemetry, which AgentCore requires to be present in the package. The generated infrastructure uploads this directory as a `.zip` — via `AgentRuntimeArtifact.fromCodeAsset` under CDK, or archived into the shared asset bucket under Terraform.
+</OptionFilter>
+
+<OptionFilter when={{ infra: 'agentcore-ecr' }} description="Container image build and scan">
 ### Docker Target
 
 The generator configures a `<your-agent-name>-docker` target which copies the `Dockerfile` from your agent source directory into the bundle output directory. This co-locates the `Dockerfile` with the bundled artifacts, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
@@ -342,10 +355,11 @@ A `docker` target is also generated which prepares the docker context for all ag
 ### Image Scanning
 
 <Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+</OptionFilter>
 
 ### Observability
 
-Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.
+Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT).
 
 You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
 

package/docs/guides/ts-mcp-server.mdx

@@ -55,13 +55,15 @@ The generator will add the following files to your existing TypeScript project:
           - divide.ts Sample tool
         - resources/
           - sample-guidance.ts Sample resource
-        - Dockerfile Entry point for hosting your MCP server (excluded when `infra` is set to `None`)
+        - Dockerfile Container image definition (only when `infra` is `agentcore-ecr`)
     - project.json Updated with MCP server serve target
 </FileTree>
 
 ### Infrastructure
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="agentcore-hosting" />
+
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment">
 <Snippet name="shared-constructs" />
 
 <Snippet name="mcp/shared-constructs" />
@@ -184,7 +186,7 @@ If you would like to run your MCP server locally using [Streamable HTTP transpor
 
 This command uses `tsx --watch` to automatically restart the server when files change.
 
-<OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
+<OptionFilter when={{ infra: ['agentcore', 'agentcore-ecr'] }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your MCP Server to Bedrock AgentCore Runtime
 
 <Snippet name="mcp/bedrock-deployment" parentHeading="Deploying Your MCP Server to Bedrock AgentCore Runtime" />
@@ -195,6 +197,13 @@ This command uses `tsx --watch` to automatically restart the server when files c
 
 The bundle target uses `http.ts` as the entrypoint for the Streamable HTTP MCP server to host on Bedrock AgentCore Runtime.
 
+<OptionFilter when={{ infra: 'agentcore' }} description="Code package target">
+### Package Target
+
+The generator configures a `<your-server-name>-package` target which assembles the deployable code package: the bundled `index.js` plus a vendored install of the AWS Distro for OpenTelemetry, which AgentCore requires to be present in the package. The generated infrastructure uploads this directory as a `.zip` — via `AgentRuntimeArtifact.fromCodeAsset` under CDK, or archived into the shared asset bucket under Terraform.
+</OptionFilter>
+
+<OptionFilter when={{ infra: 'agentcore-ecr' }} description="Container image build and scan">
 ### Docker Target
 
 The generator configures a `<your-server-name>-docker` target which copies the `Dockerfile` from your MCP server source directory into the bundle output directory. This co-locates the `Dockerfile` with the bundled artifacts, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
@@ -204,6 +213,7 @@ A `docker` target is also generated which prepares the docker context for all MC
 ### Image Scanning
 
 <Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+</OptionFilter>
 
 ### Observability
 

package/docs/snippets/agent/bedrock-deployment.mdx

@@ -6,7 +6,7 @@ import Infrastructure from '@components/infrastructure.astro';
 
 ### Infrastructure as Code
 
-If you selected `agentcore` for `infra`, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Agent to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html).
+If you selected `agentcore` or `agentcore-ecr` for `infra`, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Agent to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html).
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -31,14 +31,39 @@ This construct uses the [`aws-cdk-lib/aws-bedrockagentcore` module](https://docs
 <Fragment slot="terraform">
 A Terraform module is generated for you, named based on the `name` you chose when running the generator, or `<ProjectName>-agent` by default.
 
-Pass the shared <Link path="/guides/runtime-config#writing-configuration">`runtime_config_appconfig`</Link> module's outputs into the agent module:
+Pass the shared <Link path="/guides/runtime-config#writing-configuration">`runtime_config_appconfig`</Link> module's outputs into the agent module, along with the shared artefact store its packaging uses. Under the default `agentcore` packaging the agent's code is staged in the shared asset bucket, so instantiate the `core/asset-bucket` module once per deployment, as the Lambda and API modules already do:
 
 ```terraform
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
+module "my_project_agent" {
+  source = "../../common/terraform/src/app/agents/my-project-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+  asset_bucket_arn  = module.asset_bucket.bucket_arn
+}
+```
+
+Under `agentcore-ecr` the agent's image is published to the shared asset registry instead, so pass `core/asset-ecr`'s outputs rather than the bucket's. One registry serves every container in the workspace, so no agent needs a repository of its own:
+
+```terraform
+module "asset_ecr" {
+  source = "../../common/terraform/src/core/asset-ecr"
+}
+
 module "my_project_agent" {
   source = "../../common/terraform/src/app/agents/my-project-agent"
 
   appconfig_application_id  = module.runtime_config_appconfig.application_id
   appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  asset_ecr_repository_url = module.asset_ecr.repository_url
+  asset_ecr_repository_arn = module.asset_ecr.repository_arn
 }
 ```
 </Fragment>
@@ -50,14 +75,6 @@ The generated agent construct grants permission to invoke all Bedrock foundation
 You may wish to scope this down to the specific model(s) your agent uses. You can find the default model used by Strands agents in the [Strands documentation](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/amazon-bedrock/#default-model); see the [Strands model providers guide](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/model-providers/) for configuring a different model.
 :::
 
-:::caution[Docker Required]
-[Docker](https://www.docker.com/) is required to build and deploy your Agent. Make sure you have installed and launched Docker to avoid errors such as:
-
-```
-ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.
-```
-:::
-
 ### Authentication
 
 The generator provides an `auth` option to configure authentication for your Agent. You can choose between `IAM` (default) or `Cognito` authentication when generating your agent.
@@ -94,7 +111,11 @@ export class ExampleStack extends Stack {
 ```
 </Fragment>
 <Fragment slot="terraform">
-```terraform {5-6}
+```terraform {9-10}
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
 # Agent
 module "my_project_agent" {
   # Relative path to the generated module in the common/terraform project
@@ -102,6 +123,10 @@ module "my_project_agent" {
 
   appconfig_application_id  = module.runtime_config_appconfig.application_id
   appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  # Under `agentcore-ecr`, pass `core/asset-ecr`'s outputs instead.
+  asset_bucket_name = module.asset_bucket.bucket_name
+  asset_bucket_arn  = module.asset_bucket.bucket_arn
 }
 ```
 

package/docs/snippets/agentcore-hosting.mdx

@@ -0,0 +1,9 @@
+---
+title: AgentCore Runtime Hosting
+---
+
+The `infra` option selects how your code is packaged and hosted on [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html):
+
+- **`agentcore`** (default) uses [direct code deployment](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-code-deploy-node.html): your built code is packaged as a `.zip`, uploaded to S3, and run on an AgentCore managed language runtime. There is no container image to build, no ECR repository to manage, and no image to push, which makes for a substantially faster build and deploy cycle.
+- **`agentcore-ecr`** builds an `arm64` container image from a vended `Dockerfile` and hosts it from the shared `core/asset-ecr` registry, alongside every other container in the workspace. Choose this when you need control over the operating system image — for example to install native system libraries — or when you have an established container pipeline. This option additionally vends a Trivy image scan target (see Image Scanning below).
+- **`none`** generates no infrastructure at all, so the project can only be run locally.

package/docs/snippets/api/cors-configuration-cdk-note.mdx

@@ -16,10 +16,10 @@ export class ExampleStack extends Stack {
       integrations: MyApi.defaultIntegrations(this).build(),
     });
     const website = new MyWebsite(this, 'MyWebsite');
-    api.restrictCorsTo(website, 'http://localhost:4200');
+    api.restrictCorsTo(website, 'http://localhost:4200', 'http://localhost:4300');
   }
 }
 ```
 
-The `MyWebsite` construct can be generated using the <Link path="/guides/react-website">`ts#website` generator</Link>
+The `MyWebsite` construct can be generated using the <Link path="/guides/react-website">`ts#website` generator</Link>. This example assumes the website's local dev-server and preview ports are `4200`/`4300` - check its `project.json` (or `vite.config.mts`) for the ports actually assigned to it, since each website generated this way gets its own.
 :::

package/docs/snippets/api/cors-configuration-terraform-note.mdx

@@ -24,5 +24,5 @@ module "my_api" {
   }
 }
 ```
-The `MyWebsite` construct can be generated using the <Link path="/guides/react-website">`ts#website` generator</Link>
+The `MyWebsite` construct can be generated using the <Link path="/guides/react-website">`ts#website` generator</Link>. This example assumes the website's local ports are `4200`/`4300` - check its `project.json` (or `vite.config.mts`) for the ports actually assigned to it, since each website generated this way gets its own.
 :::

package/docs/snippets/mcp/bedrock-deployment.mdx

@@ -6,7 +6,7 @@ import Infrastructure from '@components/infrastructure.astro';
 
 ### Infrastructure as Code
 
-If you selected `agentcore` for `infra`, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your MCP server to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html).
+If you selected `agentcore` or `agentcore-ecr` for `infra`, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your MCP server to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html).
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -32,26 +32,43 @@ This construct uses the [`aws-cdk-lib/aws-bedrockagentcore` module](https://docs
 <Fragment slot="terraform">
 A Terraform module is generated for you, named based on the `name` you chose when running the generator, or `<ProjectName>-mcp-server` by default.
 
-Pass the shared <Link path="/guides/runtime-config#writing-configuration">`runtime_config_appconfig`</Link> module's outputs into the MCP server module:
+Pass the shared <Link path="/guides/runtime-config#writing-configuration">`runtime_config_appconfig`</Link> module's outputs into the MCP server module, along with the shared artefact store its packaging uses. Under the default `agentcore` packaging the server's code is staged in the shared asset bucket, so instantiate the `core/asset-bucket` module once per deployment, as the Lambda and API modules already do:
 
 ```terraform
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
 module "my_project_mcp_server" {
   source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
 
   appconfig_application_id  = module.runtime_config_appconfig.application_id
   appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+  asset_bucket_arn  = module.asset_bucket.bucket_arn
 }
 ```
-</Fragment>
-</Infrastructure>
 
-:::caution[Docker Required]
-[Docker](https://www.docker.com/) is required to build and deploy your MCP server. Make sure you have installed and launched Docker to avoid errors such as:
+Under `agentcore-ecr` the server's image is published to the shared asset registry instead, so pass `core/asset-ecr`'s outputs rather than the bucket's. One registry serves every container in the workspace, so no MCP server needs a repository of its own:
 
+```terraform
+module "asset_ecr" {
+  source = "../../common/terraform/src/core/asset-ecr"
+}
+
+module "my_project_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  asset_ecr_repository_url = module.asset_ecr.repository_url
+  asset_ecr_repository_arn = module.asset_ecr.repository_arn
+}
 ```
-ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.
-```
-:::
+</Fragment>
+</Infrastructure>
 
 ### Authentication
 

package/docs/snippets/mcp/shared-constructs.mdx

@@ -26,6 +26,10 @@ For deploying your MCP Server, the following files are generated:
     - core
       - agent-core
         - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
+      - agent-core-code (when `infra` is `agentcore`)
+        - runtime.tf Packages your MCP Server's code and delegates to `agent-core`
+      - agent-core-container (when `infra` is `agentcore-ecr`)
+        - runtime.tf Builds and publishes your MCP Server's image and delegates to `agent-core`
 </FileTree>
 </Fragment>
 </Infrastructure>

package/docs/snippets/rdb/deploying.mdx

@@ -37,7 +37,13 @@ The generated infrastructure creates two database users:
 <Fragment slot="terraform">
 The Terraform module is created in `common/terraform`. Example usage:
 
+The migration Lambda is deployed as a container image, published to the shared asset registry. Instantiate the `core/asset-ecr` module once per deployment and pass its `repository_url` into every database module:
+
 ```hcl title="packages/infra/src/main.tf"
+module "asset_ecr" {
+  source = "../../common/terraform/src/core/asset-ecr"
+}
+
 module "my_database" {
   source = "../../common/terraform/src/app/dbs/my-database"
 
@@ -46,11 +52,13 @@ module "my_database" {
   database_subnet_ids = aws_subnet.database[*].id
   lambda_subnet_ids   = aws_subnet.private[*].id
 
+  asset_ecr_repository_url = module.asset_ecr.repository_url
+
   tags = local.common_tags
 }
 ```
 
-This provisions an Aurora cluster with RDS Proxy, admin credentials, create-db-user Lambda, runtime config registration, migration Lambda, and container registry resources.
+This provisions an Aurora cluster with RDS Proxy, admin credentials, create-db-user Lambda, runtime config registration, and migration Lambda.
 
 The database module registers its connection details under the `database` <Link path="guides/runtime-config">runtime configuration</Link> namespace, which the shared runtime configuration AppConfig application exposes by default.
 

package/package.json

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

package/src/py/agent/schema.json

@@ -55,9 +55,9 @@
     },
     "infra": {
       "type": "string",
-      "description": "The type of infrastructure to host your Agent.",
+      "description": "The type of infrastructure to host your Agent. agentcore deploys your code as a zip to an AgentCore managed runtime for the fastest build and deploy cycle. agentcore-ecr builds and hosts a container image instead, for OS-level control or an established container pipeline.",
       "x-prompt": "How would you like to host your Agent server?",
-      "enum": ["agentcore", "none"],
+      "enum": ["agentcore", "agentcore-ecr", "none"],
       "default": "agentcore",
       "x-priority": "important"
     },

package/src/py/mcp-server/schema.json

@@ -39,9 +39,9 @@
     },
     "infra": {
       "type": "string",
-      "description": "The type of infrastructure to host your MCP server. Select none for no hosting.",
+      "description": "The type of infrastructure to host your MCP server. agentcore deploys your code as a zip to an AgentCore managed runtime for the fastest build and deploy cycle. agentcore-ecr builds and hosts a container image instead, for OS-level control or an established container pipeline. Select none for no hosting.",
       "x-prompt": "How would you like to host your MCP server?",
-      "enum": ["agentcore", "none"],
+      "enum": ["agentcore", "agentcore-ecr", "none"],
       "default": "agentcore",
       "x-priority": "important"
     },

package/src/ts/agent/schema.json

@@ -55,9 +55,9 @@
     },
     "infra": {
       "type": "string",
-      "description": "The type of infrastructure to host your Agent.",
+      "description": "The type of infrastructure to host your Agent. agentcore deploys your code as a zip to an AgentCore managed runtime for the fastest build and deploy cycle. agentcore-ecr builds and hosts a container image instead, for OS-level control or an established container pipeline.",
       "x-prompt": "How would you like to host your Agent server?",
-      "enum": ["agentcore", "none"],
+      "enum": ["agentcore", "agentcore-ecr", "none"],
       "default": "agentcore",
       "x-priority": "important"
     },

package/src/ts/mcp-server/schema.json

@@ -39,9 +39,9 @@
     },
     "infra": {
       "type": "string",
-      "description": "The type of infrastructure to host your MCP server. Select none for no hosting.",
+      "description": "The type of infrastructure to host your MCP server. agentcore deploys your code as a zip to an AgentCore managed runtime for the fastest build and deploy cycle. agentcore-ecr builds and hosts a container image instead, for OS-level control or an established container pipeline. Select none for no hosting.",
       "x-prompt": "How would you like to host your MCP server?",
-      "enum": ["agentcore", "none"],
+      "enum": ["agentcore", "agentcore-ecr", "none"],
       "default": "agentcore",
       "x-priority": "important"
     },