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

package/src/utils/agent-core-constructs/files/cdk/core/agentcore-gateway/agentcore-gateway.ts.template

@@ -0,0 +1,293 @@
+import * as cdk from 'aws-cdk-lib';
+import * as agentcore from 'aws-cdk-lib/aws-bedrockagentcore';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as triggers from 'aws-cdk-lib/triggers';
+import { Construct } from 'constructs';
+import ejs from 'ejs';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as url from 'node:url';
+
+/**
+ * Props for the AgentCoreGateway construct.
+ */
+export interface AgentCoreGatewayProps {
+  /**
+   * Directory of Cedar policy files (`.cedar`, nested folders supported).
+   * When set, a `PolicyEngine` running in `ENFORCE` mode is attached to the
+   * gateway, with one `Policy` per file. Files are EJS templates rendered at
+   * synth time with `gatewayArn` and `accountId` in scope.
+   */
+  readonly cedarPolicyPath?: string;
+  /**
+   * Additional variables available to the Cedar policy EJS templates.
+   */
+  readonly cedarPolicyVariables?: Record<string, string>;
+}
+
+/**
+ * AgentCore Gateway wired for MCP protocol with IAM inbound auth, exposing
+ * attached MCP servers' tools under `<targetName>___<toolName>` names.
+ */
+export class AgentCoreGateway extends Construct implements iam.IGrantable {
+  public readonly gateway: agentcore.Gateway;
+  public readonly policyEngine?: agentcore.CfnPolicyEngine;
+  private readonly policies: agentcore.CfnPolicy[] = [];
+  private targetReadinessProbe?: triggers.TriggerFunction;
+  private readonly targetRuntimeArns: string[] = [];
+
+  constructor(scope: Construct, id: string, props?: AgentCoreGatewayProps) {
+    super(scope, id);
+
+    this.gateway = new agentcore.Gateway(this, 'Gateway', {
+      protocolConfiguration: new agentcore.McpProtocolConfiguration({
+        searchType: agentcore.McpGatewaySearchType.SEMANTIC,
+        supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
+      }),
+      authorizerConfiguration: agentcore.GatewayAuthorizer.usingAwsIam(),
+    });
+
+    if (props?.cedarPolicyPath) {
+      this.policyEngine = new agentcore.CfnPolicyEngine(this, 'PolicyEngine', {
+        name: cdk.Names.uniqueResourceName(this, { maxLength: 48 }),
+        description: `Cedar policy engine for ${id}`,
+      });
+
+      // The stable Gateway L2 does not yet expose policy engine
+      // configuration, so attach it via the underlying CloudFormation
+      // resource.
+      const cfnGateway = this.gateway.node.defaultChild as agentcore.CfnGateway;
+      cfnGateway.policyEngineConfiguration = {
+        arn: this.policyEngine.attrPolicyEngineArn,
+        mode: 'ENFORCE',
+      };
+
+      // Permissions the gateway role needs to evaluate policies, including
+      // CheckAuthorizePermissions, which the CloudFormation handler's
+      // readiness probe requires during gateway creation. Authorization
+      // actions are evaluated against both the policy engine ARN and the
+      // gateway's own ARN (which cannot be referenced here without a circular
+      // dependency, so it is scoped to this account and region's gateways).
+      // The gateway must depend on the policy update — access is validated at
+      // creation.
+      const policyGrant = this.gateway.role.addToPrincipalPolicy(
+        new iam.PolicyStatement({
+          actions: [
+            'bedrock-agentcore:GetPolicyEngine',
+            'bedrock-agentcore:AuthorizeAction',
+            'bedrock-agentcore:PartiallyAuthorizeActions',
+            'bedrock-agentcore:CheckAuthorizePermissions',
+          ],
+          resources: [
+            this.policyEngine.attrPolicyEngineArn,
+            cdk.Stack.of(this).formatArn({
+              service: 'bedrock-agentcore',
+              resource: 'gateway',
+              resourceName: '*',
+            }),
+          ],
+        }),
+      );
+      if (policyGrant.policyDependable) {
+        cfnGateway.node.addDependency(policyGrant.policyDependable);
+      }
+
+      const policiesDir = props.cedarPolicyPath;
+      if (fs.existsSync(policiesDir)) {
+        for (const file of fs
+          .readdirSync(policiesDir, { recursive: true, encoding: 'utf-8' })
+          .filter((f) => f.endsWith('.cedar'))) {
+          const raw = fs.readFileSync(path.join(policiesDir, file), 'utf-8');
+          const statement = cdk.Lazy.string({
+            produce: () =>
+              ejs.render(raw, {
+                gatewayArn: cdk.Token.asString(this.gateway.gatewayArn),
+                accountId: cdk.Token.asString(cdk.Stack.of(this).account),
+                ...props.cedarPolicyVariables,
+              }),
+          });
+          const policyId = `Policy-${file.replace(/\.cedar$/, '').replace(/[\\/]/g, '-')}`;
+          const policy = new agentcore.CfnPolicy(this, policyId, {
+            name: policyId,
+            policyEngineId: this.policyEngine.attrPolicyEngineId,
+            definition: { cedar: { statement } },
+            description: `Policy loaded from ${file}`,
+            // The Cedar analyzer rejects legitimate policies as findings
+            // (e.g. a forbid disabling one tool for every caller is "Overly
+            // Restrictive"), so deploy regardless and rely on the engine's
+            // ENFORCE mode.
+            validationMode: 'IGNORE_ALL_FINDINGS',
+          });
+          // Policy names are unique account-wide, so derive the name from
+          // the construct path to avoid collisions with other gateways.
+          policy.name = cdk.Names.uniqueResourceName(policy, {
+            maxLength: 48,
+          });
+          this.policies.push(policy);
+        }
+      }
+    }
+  }
+
+  /**
+   * The principal to grant permissions to.
+   */
+  public get grantPrincipal(): iam.IPrincipal {
+    return this.gateway.role.grantPrincipal;
+  }
+
+  /**
+   * Grants an IAM principal permission to invoke this gateway.
+   */
+  public grantInvokeAccess(grantee: iam.IGrantable) {
+    this.gateway.grantInvoke(grantee);
+  }
+
+  /**
+   * Add an MCP server construct as a target of this Gateway.
+   *
+   * The target name defaults to the MCP server construct's `mcpServerName`
+   * (its project's class name in kebab-case, e.g. `TsMcp` -> `ts-mcp`),
+   * which is stable across stacks and unique across projects in the
+   * workspace. It prefixes Cedar action names
+   * (`AgentCore::Action::"<targetName>___<toolName>"`) and the gateway's
+   * tool names (`<targetName>___<toolName>`), so renaming it later is a
+   * breaking change for consumers.
+   */
+  public addMcpServer(
+    server: Construct & {
+      readonly agentCoreRuntime: agentcore.Runtime;
+      readonly mcpServerName: string;
+    },
+    props?: {
+      gatewayTargetName?: string;
+    },
+  ): agentcore.CfnGatewayTarget {
+    return this.addMcpServerTarget({
+      gatewayTargetName: props?.gatewayTargetName ?? server.mcpServerName,
+      mcpServerRuntimeArn: server.agentCoreRuntime.agentRuntimeArn,
+    });
+  }
+
+  /**
+   * Register an MCP server runtime ARN as a Gateway target. Prefer
+   * {@link addMcpServer} when the construct is in scope.
+   */
+  public addMcpServerTarget(props: {
+    gatewayTargetName: string;
+    mcpServerRuntimeArn: string;
+  }): agentcore.CfnGatewayTarget {
+    const region = cdk.Stack.of(this).region;
+    // The endpoint must URL-encode the runtime ARN (':' -> '%3A', '/' -> '%2F').
+    // The ARN is a CDK token, so encode at deploy time via Fn.join/Fn.split.
+    const arn = props.mcpServerRuntimeArn;
+    const encodedArn = cdk.Fn.join(
+      '%2F',
+      cdk.Fn.split('/', cdk.Fn.join('%3A', cdk.Fn.split(':', arn))),
+    );
+    const endpoint = `https://bedrock-agentcore.${region}.amazonaws.com/runtimes/${encodedArn}/invocations?qualifier=DEFAULT`;
+    // The construct id is derived from the target name so the two change
+    // together — target names are unique per gateway, and replacing a target
+    // under an unchanged name fails with AlreadyExists.
+    const target = new agentcore.CfnGatewayTarget(
+      this,
+      `Target-${props.gatewayTargetName}`,
+      {
+        gatewayIdentifier: this.gateway.gatewayId,
+        name: props.gatewayTargetName,
+        targetConfiguration: {
+          mcp: {
+            mcpServer: {
+              endpoint,
+            },
+          },
+        },
+        credentialProviderConfigurations: [
+          {
+            credentialProviderType: 'GATEWAY_IAM_ROLE',
+            credentialProvider: {
+              iamCredentialProvider: {
+                service: 'bedrock-agentcore',
+              },
+            },
+          },
+        ],
+      },
+    );
+
+    // Grant the gateway role invoke access to the target runtime before the
+    // target is created — AgentCore probes the target during creation, which
+    // stalls if the permission is not yet in place.
+    const grant = this.gateway.role.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: [
+          'bedrock-agentcore:InvokeAgentRuntime',
+          'bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream',
+        ],
+        resources: [
+          props.mcpServerRuntimeArn,
+          `${props.mcpServerRuntimeArn}/*`,
+        ],
+      }),
+    );
+    if (grant.policyDependable) {
+      target.node.addDependency(grant.policyDependable);
+    }
+
+    // Create the target only after the readiness probe has confirmed the
+    // runtime serves MCP.
+    this.targetRuntimeArns.push(props.mcpServerRuntimeArn);
+    const probe = this.getOrCreateTargetReadinessProbe();
+    const probeGrant = probe.grantPrincipal.addToPrincipalPolicy(
+      new iam.PolicyStatement({
+        actions: ['bedrock-agentcore:InvokeAgentRuntime'],
+        resources: [
+          props.mcpServerRuntimeArn,
+          `${props.mcpServerRuntimeArn}/*`,
+        ],
+      }),
+    );
+    if (probeGrant.policyDependable) {
+      probe.trigger.node.addDependency(probeGrant.policyDependable);
+    }
+    target.node.addDependency(probe.trigger);
+
+    // Policies referencing this target's actions (e.g.
+    // AgentCore::Action::"<targetName>___<tool>") only validate once the
+    // target has registered them, so create policies after targets.
+    for (const policy of this.policies) {
+      policy.node.addDependency(target);
+    }
+
+    return target;
+  }
+
+  /**
+   * AgentCore fetches each target's tools during target creation, which can
+   * race the MCP runtime's first cold start on a fresh deploy and fail the
+   * target. This trigger probes each runtime until it serves MCP, and targets
+   * are created after it succeeds.
+   */
+  private getOrCreateTargetReadinessProbe(): triggers.TriggerFunction {
+    this.targetReadinessProbe ??= new triggers.TriggerFunction(
+      this,
+      'TargetReadinessProbe',
+      {
+        runtime: lambda.Runtime.NODEJS_22_X,
+        handler: 'index.handler',
+        timeout: cdk.Duration.seconds(210),
+        code: lambda.Code.fromAsset(
+          url.fileURLToPath(new URL('./readiness-probe', import.meta.url)),
+        ),
+        environment: {
+          RUNTIME_ARNS: cdk.Lazy.string({
+            produce: () => this.targetRuntimeArns.join(','),
+          }),
+        },
+      },
+    );
+    return this.targetReadinessProbe;
+  }
+}
+

package/src/utils/agent-core-constructs/files/cdk/core/agentcore-gateway/readiness-probe/index.js.template

@@ -0,0 +1,55 @@
+/**
+ * Readiness probe for AgentCore Gateway MCP targets.
+ *
+ * AgentCore fetches each target's tools during target creation, which can
+ * race the MCP runtime's first cold start on a fresh deploy. This handler
+ * invokes each runtime with an MCP initialize request — the invocation
+ * blocks through the cold start — retrying for up to 3 minutes.
+ */
+const {
+  BedrockAgentCoreClient,
+  InvokeAgentRuntimeCommand,
+} = require('@aws-sdk/client-bedrock-agentcore');
+
+const client = new BedrockAgentCoreClient();
+
+const DEADLINE_MS = 3 * 60 * 1000;
+const RETRY_INTERVAL_MS = 5 * 1000;
+
+const INITIALIZE_REQUEST = JSON.stringify({
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: {
+    protocolVersion: '2025-03-26',
+    capabilities: {},
+    clientInfo: { name: 'readiness-probe', version: '1.0' },
+  },
+});
+
+const probe = async (agentRuntimeArn) => {
+  const deadline = Date.now() + DEADLINE_MS;
+  for (;;) {
+    try {
+      return await client.send(
+        new InvokeAgentRuntimeCommand({
+          agentRuntimeArn,
+          runtimeSessionId: 'readiness-probe-' + crypto.randomUUID(),
+          contentType: 'application/json',
+          accept: 'application/json, text/event-stream',
+          payload: Buffer.from(INITIALIZE_REQUEST),
+        }),
+      );
+    } catch (e) {
+      if (Date.now() >= deadline) {
+        throw e;
+      }
+      await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL_MS));
+    }
+  }
+};
+
+exports.handler = async () => {
+  const arns = (process.env.RUNTIME_ARNS ?? '').split(',').filter(Boolean);
+  await Promise.all(arns.map(probe));
+};

package/src/utils/agent-core-constructs/files/terraform/app/agentcore-gateway/__nameKebabCase__/__nameKebabCase__.tf.template

@@ -0,0 +1,242 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 6.50"
+    }
+<%_ if (cedarPolicy) { _%>
+    external = {
+      source  = "hashicorp/external"
+      version = ">= 2.0"
+    }
+<%_ } _%>
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
+  }
+}
+
+variable "additional_iam_policy_statements" {
+  description = "Additional IAM policy statements to attach to the gateway service role. Connection generators (e.g. agentcore-gateway#mcp-connection) append `InvokeAgentRuntime*` entries here."
+  type = list(object({
+    Effect   = string
+    Action   = list(string)
+    Resource = list(string)
+  }))
+  default = []
+}
+<%_ if (cedarPolicy) { _%>
+
+variable "policy_dependencies" {
+  description = "Values the Cedar policies must wait for, e.g. gateway target ids. Policies referencing a target's actions only validate once the target has registered them."
+  type        = list(string)
+  default     = []
+}
+<%_ } _%>
+
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}
+
+locals {
+  aws_account_id = data.aws_caller_identity.current.account_id
+  aws_region     = data.aws_region.current.id
+<%_ if (cedarPolicy) { _%>
+  policies_dir   = "${path.module}/../../../../../../../<%- projectDirectory %>/policies"
+<%_ } _%>
+}
+
+resource "random_id" "unique_suffix" {
+  byte_length = 4
+}
+
+# IAM role for the gateway service
+resource "aws_iam_role" "gateway_role" {
+  name = "<%- nameClassName %>-GatewayRole-${random_id.unique_suffix.hex}"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Sid    = "AgentCoreGatewayAssumeRolePolicy"
+        Effect = "Allow"
+        Principal = {
+          Service = "bedrock-agentcore.amazonaws.com"
+        }
+        Action = "sts:AssumeRole"
+        Condition = {
+          StringEquals = {
+            "aws:SourceAccount" = local.aws_account_id
+          }
+          ArnLike = {
+            "aws:SourceArn" = "arn:aws:bedrock-agentcore:${local.aws_region}:${local.aws_account_id}:*"
+          }
+        }
+      }
+    ]
+  })
+}
+
+<%_ if (cedarPolicy) { _%>
+# Inline policy giving the gateway role the permissions it needs:
+#   - Policy evaluation permissions, including CheckAuthorizePermissions
+#     which the gateway readiness probe requires during creation.
+#     Authorization actions are evaluated against both the policy engine ARN
+#     and the gateway's own ARN (which cannot be referenced here without a
+#     dependency cycle, so it is scoped to this account and region's gateways)
+#   - Additional statements appended by connection generators (e.g. InvokeAgentRuntime*)
+resource "aws_iam_role_policy" "gateway_role_policy" {
+  name = "<%- nameClassName %>-GatewayPolicy"
+  role = aws_iam_role.gateway_role.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = concat([
+      {
+        Sid    = "PolicyEvaluation"
+        Effect = "Allow"
+        Action = [
+          "bedrock-agentcore:GetPolicyEngine",
+          "bedrock-agentcore:AuthorizeAction",
+          "bedrock-agentcore:PartiallyAuthorizeActions",
+          "bedrock-agentcore:CheckAuthorizePermissions",
+        ]
+        Resource = [
+          aws_bedrockagentcore_policy_engine.this.policy_engine_arn,
+          "arn:aws:bedrock-agentcore:${local.aws_region}:${local.aws_account_id}:gateway/*",
+        ]
+      }
+    ], var.additional_iam_policy_statements)
+  })
+}
+<%_ } else { _%>
+# Inline policy for statements appended by connection generators
+# (e.g. InvokeAgentRuntime*)
+resource "aws_iam_role_policy" "gateway_role_policy" {
+  count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
+  name  = "<%- nameClassName %>-GatewayPolicy"
+  role  = aws_iam_role.gateway_role.id
+
+  policy = jsonencode({
+    Version   = "2012-10-17"
+    Statement = var.additional_iam_policy_statements
+  })
+}
+<%_ } _%>
+<%_ if (cedarPolicy) { _%>
+
+# Policy engine (name must match ^[A-Za-z][A-Za-z0-9_]*$ — no hyphens)
+resource "aws_bedrockagentcore_policy_engine" "this" {
+  name        = "<%- nameClassName %>_PolicyEngine_${random_id.unique_suffix.hex}"
+  description = "Cedar policy engine for <%- nameClassName %>"
+}
+<%_ } _%>
+
+resource "aws_bedrockagentcore_gateway" "this" {
+  name        = "<%- nameClassName %>-${random_id.unique_suffix.hex}"
+  description = "AgentCore Gateway for <%- nameClassName %>"
+  role_arn    = aws_iam_role.gateway_role.arn
+
+  protocol_type = "MCP"
+  protocol_configuration {
+    mcp {
+      search_type        = "SEMANTIC"
+      supported_versions = ["2025-03-26"]
+    }
+  }
+
+  authorizer_type = "AWS_IAM"
+<%_ if (cedarPolicy) { _%>
+
+  policy_engine_configuration {
+    arn  = aws_bedrockagentcore_policy_engine.this.policy_engine_arn
+    mode = "ENFORCE"
+  }
+
+  depends_on = [aws_iam_role_policy.gateway_role_policy]
+<%_ } _%>
+}
+<%_ if (cedarPolicy) { _%>
+
+# Anchor for the policy_dependencies variable — depends_on only accepts
+# static references, so the policies depend on this resource instead.
+resource "terraform_data" "policy_dependencies" {
+  input = var.policy_dependencies
+}
+
+# Policies are EJS templates rendered by render-cedar.cjs with `gatewayArn`
+# and `accountId` in scope.
+data "external" "rendered_policies" {
+  for_each = fileset(local.policies_dir, "**/*.cedar")
+
+  program = ["node", "${path.module}/render-cedar.cjs"]
+  query = {
+    template   = "${local.policies_dir}/${each.value}"
+    gatewayArn = aws_bedrockagentcore_gateway.this.gateway_arn
+    accountId  = local.aws_account_id
+  }
+}
+
+# One Policy per .cedar file in the project's policies/ directory.
+#
+# Policy resource names are derived from the file basename and normalised
+# to PascalCase. The AgentCore Policy resource `name` regex requires
+# `^[A-Za-z][A-Za-z0-9_]*$` — no hyphens — so the join() reassembles the
+# basename with each segment Title-cased.
+resource "aws_bedrockagentcore_policy" "policies" {
+  for_each = fileset(local.policies_dir, "**/*.cedar")
+
+  policy_engine_id = aws_bedrockagentcore_policy_engine.this.policy_engine_id
+  # Policy names are unique account-wide, so append this gateway's unique
+  # suffix to avoid collisions with other gateways.
+  name = join("", concat([
+    for word in split("-", replace(replace(trimsuffix(each.value, ".cedar"), "_", "-"), "/", "-")) :
+    "${upper(substr(word, 0, 1))}${substr(word, 1, length(word))}"
+  ], ["_${random_id.unique_suffix.hex}"]))
+  description = "Policy loaded from ${each.value}"
+  # The Cedar analyzer rejects legitimate policies as findings (e.g. a forbid
+  # disabling one tool for every caller is "Overly Restrictive"), so deploy
+  # regardless and rely on the engine's ENFORCE mode.
+  validation_mode = "IGNORE_ALL_FINDINGS"
+  definition {
+    cedar {
+      statement = data.external.rendered_policies[each.value].result.rendered
+    }
+  }
+
+  depends_on = [terraform_data.policy_dependencies]
+}
+<%_ } _%>
+
+# Add gateway URL to runtime config
+module "add_gateway_url_to_runtime_config" {
+  source = "../../../core/runtime-config/entry"
+
+  namespace = "agentcore"
+  key       = "gateways"
+  value     = { "<%- nameClassName %>" = aws_bedrockagentcore_gateway.this.gateway_url }
+
+  depends_on = [aws_bedrockagentcore_gateway.this]
+}
+
+output "gateway_id" {
+  description = "ID of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_id
+}
+
+output "gateway_arn" {
+  description = "ARN of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_arn
+}
+
+output "gateway_url" {
+  description = "MCP endpoint URL of the Bedrock AgentCore Gateway"
+  value       = aws_bedrockagentcore_gateway.this.gateway_url
+}
+
+output "gateway_role_arn" {
+  description = "ARN of the IAM role assumed by the gateway service"
+  value       = aws_iam_role.gateway_role.arn
+}

package/src/utils/agent-core-constructs/files/terraform/app/agentcore-gateway/__nameKebabCase__/render-cedar.cjs.template

@@ -0,0 +1,13 @@
+// Renders a Cedar policy EJS template for the <%- nameClassName %> Terraform
+// module. Invoked by the `external` data source with JSON on stdin:
+//   { "template": "<path>", "gatewayArn": "...", "accountId": "..." }
+const ejs = require('ejs');
+const fs = require('fs');
+
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  const { template, ...vars } = JSON.parse(input);
+  const rendered = ejs.render(fs.readFileSync(template, 'utf-8'), vars);
+  process.stdout.write(JSON.stringify({ rendered }));
+});

package/src/utils/agent-core-constructs/files/terraform/core/agent-core/runtime.tf.template

@@ -335,6 +335,59 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   ]
 }
 
+# MCP consumers (e.g. gateway targets, which fetch tools at creation) can race
+# the runtime's first cold start, so probe it until it serves MCP. The ARN
+# output is routed through this resource so consumers wait for readiness.
+resource "null_resource" "runtime_ready" {
+  count = var.server_protocol == "MCP" ? 1 : 0
+
+  triggers = {
+    runtime_arn = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      uv run --with boto3 python -c "
+import boto3
+import json
+import time
+import uuid
+
+runtime_arn = '${self.triggers.runtime_arn}'
+client = boto3.client('bedrock-agentcore')
+initialize_request = json.dumps({
+    'jsonrpc': '2.0',
+    'id': 1,
+    'method': 'initialize',
+    'params': {
+        'protocolVersion': '2025-03-26',
+        'capabilities': {},
+        'clientInfo': {'name': 'readiness-probe', 'version': '1.0'},
+    },
+})
+
+deadline = time.time() + 3 * 60
+while True:
+    try:
+        client.invoke_agent_runtime(
+            agentRuntimeArn=runtime_arn,
+            runtimeSessionId=f'readiness-probe-{uuid.uuid4()}',
+            contentType='application/json',
+            accept='application/json, text/event-stream',
+            payload=initialize_request,
+        )
+        break
+    except Exception:
+        if time.time() >= deadline:
+            raise
+        time.sleep(5)
+
+print(f'Runtime {runtime_arn} is serving MCP')
+"
+    EOT
+  }
+}
+
 # Outputs
 output "agent_core_runtime_role_arn" {
   description = "ARN of the Agent Core Runtime IAM role"
@@ -352,8 +405,8 @@ output "agent_runtime_name" {
 }
 
 output "agent_core_runtime_arn" {
-  description = "ARN of the Bedrock Agent Core runtime"
-  value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  description = "ARN of the Bedrock Agent Core runtime. For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = var.server_protocol == "MCP" ? null_resource.runtime_ready[0].triggers.runtime_arn : aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
 }
 
 output "agent_runtime_id" {

package/src/utils/agent-core-constructs/files/terraform/core/agentcore-gateway/gateway.tf.template

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 6.50"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
+  }
+}