@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

package/docs/guides/connection/react-ts-agent.mdx

@@ -2,7 +2,7 @@
 title: React to TypeScript Agent
 description: Connect a React website to a TypeScript Agent
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: ts#agent
   protocol: http
 ---
@@ -64,13 +64,13 @@ Additionally, it installs the required dependencies:
 The generated client connects to your Agent via tRPC over WebSocket. The agent exposes a tRPC router (including the `invoke` subscription for streaming agent responses) over a WebSocket endpoint.
 
 - **Deployed**: The agent runtime ARN is loaded from <Link path="guides/runtime-config">Runtime Configuration</Link>. Running this connection generator also patches the agent's generated CDK/Terraform construct to publish its ARN to the website's `runtime-config.json` (under the `connection` namespace), so only agents you explicitly connect are exposed to the frontend. The ARN is converted to a WebSocket URL following the Bedrock AgentCore Runtime WebSocket protocol: `wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/ws`
-- **Local development**: When running with `serve-local`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
+- **Local development**: When running with `dev`, the runtime config override sets the value to a local `ws://` URL (e.g., `ws://localhost:8081/ws`), and the client connects directly
 
 ### Authentication
 
 The generated code handles authentication depending on your agent's configuration:
 
-- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `serve-local` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+- **IAM** (default): Uses AWS SigV4 presigned URLs to authenticate the WebSocket connection. Credentials are obtained from the Cognito Identity Pool configured with your website's auth. In `dev` mode, signing is automatically skipped when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
 - **Cognito**: Embeds the JWT access token in the `Sec-WebSocket-Protocol` header as a base64url-encoded bearer token, following the [AgentCore WebSocket auth protocol](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html)
 
 
@@ -93,7 +93,7 @@ function ChatComponent() {
 
   const subscription = useSubscription(
     trpc.invoke.subscriptionOptions(
-      { message: 'What can you help me with?' },
+      { prompt: 'What can you help me with?' },
       {
         enabled: true,
         onStarted: () => {
@@ -135,9 +135,9 @@ function ChatComponent() {
   const client = useMyAgentAgentClient();
   const [messages, setMessages] = useState<string[]>([]);
 
-  const sendMessage = (message: string) => {
+  const sendMessage = (prompt: string) => {
     const subscription = client.invoke.subscribe(
-      { message },
+      { prompt },
       {
         onData: (token) => {
           setMessages((prev) => [...prev, token]);
@@ -174,11 +174,11 @@ For more details on the vanilla tRPC client, see the [tRPC Vanilla Client docume
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration for your react website:
+The connection generator automatically configures `dev` integration for your react website:
 
-1. Running `nx serve-local <website>` will also start the agent's local server
+1. Running `nx dev <website>` will also start the agent's local server
 2. The runtime config is overridden to point to the local WebSocket URL (e.g., `ws://localhost:8081/ws`)
-3. Like with connected APIs, authentication is skipped in `serve-local` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
+3. Like with connected APIs, authentication is skipped in `dev` mode when <Link path="guides/react-website#runtime-configuration">`runtime-config.json`</Link> is not present
 
 :::tip[Hot Reloading]
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.

package/docs/guides/connection/smithy-dynamodb.mdx

@@ -1,8 +1,8 @@
 ---
 title: Smithy API to DynamoDB
-description: Connect a Smithy API to a DynamoDB table
+description: Connect a Smithy API to a TypeScript DynamoDB project
 when:
-  sourceType: smithy
+  sourceType: ts#smithy-api
   targetType: ts#dynamodb
 ---
 import { FileTree } from '@astrojs/starlight/components';
@@ -12,13 +12,13 @@ import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Snippet from '@components/snippet.astro';
 
-The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/ts-smithy-api">`ts#smithy-api`</Link> project (TypeScript backend)
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
 2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
 
 ## Usage
@@ -35,14 +35,14 @@ Select your Smithy API backend project as the source and your DynamoDB project a
 
 ## Generator Output
 
-The generator updates your Smithy API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
+The generator updates your Smithy API's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target. No source files are modified.
 
 ## Using DynamoDB in Operations
 
 Import entity factories from the DynamoDB package and use them inside your operation implementations:
 
 ```ts title="packages/api/src/operations/list-examples.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 import {
   ListExamplesOperationInput,
   ListExamplesOperationOutput,

package/docs/guides/connection/smithy-rdb.mdx

@@ -2,7 +2,7 @@
 title: Smithy API to Relational Database
 description: Connect a Smithy API to a Relational Database
 when:
-  sourceType: smithy
+  sourceType: ts#smithy-api
   targetType: ts#rdb
 ---
 import { FileTree } from '@astrojs/starlight/components';
@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API<
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/ts-smithy-api">`ts#smithy-api`</Link> project (TypeScript backend)
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
 2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
 
 ## Usage
@@ -46,7 +46,7 @@ The generator modifies three existing files in your Smithy API backend:
 
 </FileTree>
 
-Additionally, it updates the API's `serve-local` target to start the database automatically.
+Additionally, it updates the API's `dev` target to start the database automatically.
 
 ## How It Works
 
@@ -55,7 +55,7 @@ Additionally, it updates the API's `serve-local` target to start the database au
 The generator adds a typed `db` property to `ServiceContext` in `context.ts`:
 
 ```ts title="packages/api/src/context.ts" {1,7}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export interface ServiceContext {
   tracer: Tracer;
@@ -69,8 +69,8 @@ export interface ServiceContext {
 
 The Prisma client is instantiated inside `lambdaHandler` and passed through the service context:
 
-```ts title="packages/api/src/handler.ts" {1,10}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+```ts title="packages/api/src/handler.ts" {1,5,10}
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export const lambdaHandler = async (event: APIGatewayProxyEvent) => {
   const httpRequest = convertEvent(event);
@@ -134,14 +134,14 @@ const httpResponse = await serviceHandler.handle(httpRequest, {
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development
 
 The generator applies the same Prisma client injection inside the request handler in `local-server.ts`:
 
 ```ts title="packages/api/src/local-server.ts" {1,5,10}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 const server = createServer(async function (req, res) {
   const httpRequest = convertRequest(req);
@@ -156,6 +156,6 @@ const server = createServer(async function (req, res) {
 });
 ```
 
-<NxCommands commands={["serve-local <api-project-name>"]} />
+<NxCommands commands={["dev <api-project-name>"]} />
 
-This starts both the API and the local database. The `SERVE_LOCAL=true` environment variable is set automatically, so the Prisma client connects to the local Docker database instead of Aurora.
+This starts both the API and the local database. The `LOCAL_DEV=true` environment variable is set automatically, so the Prisma client connects to the local Docker database instead of Aurora.

package/docs/guides/connection/trpc-dynamodb.mdx

@@ -1,6 +1,6 @@
 ---
 title: tRPC API to DynamoDB
-description: Connect a tRPC API to a DynamoDB table
+description: Connect a tRPC API to a TypeScript DynamoDB project
 when:
   sourceType: ts#trpc-api
   targetType: ts#dynamodb
@@ -12,13 +12,13 @@ import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Snippet from '@components/snippet.astro';
 
-The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/trpc">`ts#trpc-api`</Link> project
+1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
 2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
 
 ## Usage
@@ -35,14 +35,14 @@ Select your tRPC API project as the source and your DynamoDB project as the targ
 
 ## Generator Output
 
-The generator updates your tRPC API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
+The generator updates your tRPC API's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target. No source files are modified.
 
 ## Using DynamoDB in Procedures
 
 Import entity factories from the DynamoDB package and use them inside your tRPC procedures:
 
 ```ts title="packages/api/src/procedures/example.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 import { publicProcedure } from '../init.js';
 
 export const listExamples = publicProcedure

package/docs/guides/connection/trpc-rdb.mdx

@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/trpc">`ts#trpc-api`</Link> project
+1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
 2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
 
 ## Usage
@@ -45,7 +45,7 @@ The generator creates a middleware file in your tRPC API project:
 
 </FileTree>
 
-Additionally, it updates your tRPC API's `serve-local` target to start the database automatically when running locally.
+Additionally, it updates your tRPC API's `dev` target to start the database automatically when running locally.
 
 ## Using the Middleware
 
@@ -65,7 +65,7 @@ export const authenticatedProcedure = t.procedure
 
 The plugin merges `IMyDbContext` into your procedure context, making `myDb` available as an optional property:
 
-```ts title="packages/api/src/procedures/users.ts" {8,12}
+```ts title="packages/api/src/procedures/users.ts" {7-8}
 import { z } from 'zod';
 import { authenticatedProcedure } from '../router.js';
 
@@ -116,12 +116,12 @@ export const dbProcedure = t.procedure
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development
 
-The generator configures your tRPC API's `serve-local` target to depend on the database's `serve-local` target, so running:
+The generator configures your tRPC API's `dev` target to depend on the database's `dev` target, so running:
 
-<NxCommands commands={["serve-local <api-project-name>"]} />
+<NxCommands commands={["dev <api-project-name>"]} />
 
 will automatically start the local database alongside your API.

package/docs/guides/connection/ts-agent-a2a.mdx

@@ -23,7 +23,7 @@ The generator sets up all the necessary wiring so your agent can discover and in
 Before using this generator, ensure you have:
 
 1. A TypeScript project with a <Link path="guides/ts-agent">Strands Agent</Link> component (any protocol)
-2. A project with an Agent component generated with `--protocol=A2A` and `--auth=IAM` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
+2. A project with an Agent component generated with `--protocol=a2a` and `--auth=iam` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
 3. Both components created with `infra: agentcore`
 
 ## Usage
@@ -47,9 +47,12 @@ The generator creates a shared `agent-connection` package and modifies your agen
 - packages/common/agent-connection
   - src
     - app
-      - \<target-agent-name>-client.ts High-level client for the connected A2A agent
+      - \<target-agent-name>-client-strands.ts High-level Strands client for the connected A2A agent
     - core
-      - agentcore-a2a-client.ts Low-level AgentCore A2A client with SigV4 authentication
+      - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-a2a-client-config.ts Framework-agnostic A2A client config (signed `clientFactory`)
+      - agentcore-a2a-client-strands.ts Strands A2A client wrapping the config
     - index.ts Exports all clients
   - project.json
   - tsconfig.json
@@ -58,20 +61,20 @@ The generator creates a shared `agent-connection` package and modifies your agen
 
 Additionally, it:
 - Transforms your agent's `agent.ts` to register the remote A2A agent as a Strands `tool`
-- Updates the agent's `serve-local` target to depend on the target agent's `serve-local` target
+- Updates the agent's `dev` target to depend on the target agent's `dev` target
 - Installs required dependencies
 
 ## Using the Connected A2A Agent
 
 The generator transforms your agent's `agent.ts` to wrap the remote A2A agent as a tool:
 
-```ts title="packages/example/src/my-agent/agent.ts" {2,5-11,14}
+```ts title="packages/example/src/my-agent/agent.ts" {2,5-12,15}
 import { Agent, tool } from '@strands-agents/sdk';
-import { RemoteAgentClient } from ':my-scope/agent-connection';
+import { RemoteAgentClientStrands } from '@my-scope/agent-connection';
 import { z } from 'zod';
 
 export const getAgent = async (sessionId: string) => {
-  const remoteAgent = await RemoteAgentClient.create(sessionId);
+  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
   const remoteAgentTool = tool({
     name: 'askRemoteAgent',
     description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
@@ -87,7 +90,7 @@ export const getAgent = async (sessionId: string) => {
 
 The `sessionId` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
-Under the hood, `RemoteAgentClient.create(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+Under the hood, `RemoteAgentClientStrands.create(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `LOCAL_DEV=true`. The signing and endpoint resolution live in the framework-agnostic `agentcore-a2a-client-config.ts`; only the thin `agentcore-a2a-client-strands.ts` depends on Strands.
 
 ## Infrastructure
 
@@ -95,12 +98,12 @@ Under the hood, `RemoteAgentClient.create(sessionId)` returns a Strands `A2AAgen
 
 ## Local Development
 
-The generator configures the host agent's `serve-local` target to:
+The generator configures the host agent's `dev` target to:
 1. Start the connected A2A agent(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the host agent and all connected A2A agents, with the host agent calling the remote agents over plain HTTP on their assigned local ports.

package/docs/guides/connection/ts-agent-dynamodb.mdx

@@ -1,6 +1,6 @@
 ---
 title: TypeScript Agent to DynamoDB
-description: Connect a TypeScript Agent to a DynamoDB table
+description: Connect a TypeScript Agent to a TypeScript DynamoDB project
 when:
   sourceType: ts#agent
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ import NxCommands from '@components/nx-commands.astro';
 import Infrastructure from '@components/infrastructure.astro';
 import Snippet from '@components/snippet.astro';
 
-The `connection` generator wires a <Link path="guides/ts-agent">TypeScript Agent</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+The `connection` generator wires a <Link path="guides/ts-agent">TypeScript Agent</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 
@@ -35,14 +35,14 @@ Select your Agent project as the source and your DynamoDB project as the target.
 
 ## Generator Output
 
-The generator updates the agent's `<agent-name>-serve-local` target in `project.json` to depend on the DynamoDB project's `serve-local` target. No source files are modified.
+The generator updates the agent's `<agent-name>-dev` target in `project.json` to depend on the DynamoDB project's `dev` target. No source files are modified.
 
 ## Using DynamoDB in Agents
 
 Import entity factories from the DynamoDB package and use them inside your agent definition:
 
 ```ts title="packages/my-service/src/my-agent/agent.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 
 export const getAgent = async () => {
   // ...
@@ -70,7 +70,7 @@ To allow the agent's Lambda function to access the DynamoDB table, grant the nec
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table');
 const myAgent = new MyAgent(this, 'MyAgent');

package/docs/guides/connection/ts-agent-gateway.mdx

@@ -0,0 +1,147 @@
+---
+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 with `protocol: mcp` and `auth: iam`
+
+The Gateway must serve the `mcp` protocol — the agent reaches it as an MCP client, so its targets are exposed as tools. The Gateway must also use IAM authentication: the agent signs its requests with SigV4 using its own execution role. The generator rejects Cognito-authenticated gateways.
+
+:::note[One direction per Gateway]
+A single Gateway cannot both be called by an agent and front one. Fronting agent runtimes needs `protocol: http` (see <Link path="guides/connection/agentcore-gateway-agent">Gateway to Agent</Link>), whereas being called by an agent needs `protocol: mcp`. Use a separate Gateway for each direction.
+:::
+
+## 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-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
+      - agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
+    - app/
+      - \<gateway-kebab>-client-strands.ts Per-Gateway Strands 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>ClientStrands.create()`, and register the returned client in the `tools` array
+- Wires the agent's `<agent>-dev` target to depend on the Gateway's `dev` target
+- 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 { MyGatewayClientStrands } from '@my-scope/agent-connection';
+
+export const getAgent = async () => {
+  const myGateway = await MyGatewayClientStrands.create();
+  return new Agent({
+    systemPrompt: '...',
+    tools: [myGateway],
+  });
+};
+```
+
+When deployed (`LOCAL_DEV` unset), the client points at the Gateway's MCP endpoint and authenticates with SigV4. When `LOCAL_DEV=true`, it points at the local gateway started by the Gateway project's `dev` 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" {8-13}
+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
+  additional_iam_policy_statements = [{
+    Effect   = "Allow"
+    Action   = ["bedrock-agentcore:InvokeGateway"]
+    Resource = [module.my_gateway.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 `dev` target to:
+
+1. Start the connected Gateway's local gateway and every attached MCP server
+2. Set `LOCAL_DEV=true` so the generated client points at the local gateway instead of the deployed Gateway
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-dev <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 `LOCAL_DEV` 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/ts-agent-mcp.mdx

@@ -47,9 +47,12 @@ The generator creates a shared `agent-connection` package and modifies your agen
 - packages/common/agent-connection
   - src
     - app
-      - \<mcp-server-name>-client.ts High-level client for the connected MCP server
+      - \<mcp-server-name>-client-strands.ts High-level Strands client for the connected MCP server
     - core
-      - agentcore-mcp-client.ts Low-level AgentCore MCP client with SigV4/JWT authentication
+      - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-mcp-transport.ts Framework-agnostic MCP transport
+      - agentcore-mcp-client-strands.ts Strands MCP client wrapping the transport
     - index.ts Exports all clients
   - project.json
   - tsconfig.json
@@ -58,7 +61,7 @@ The generator creates a shared `agent-connection` package and modifies your agen
 
 Additionally, it:
 - Transforms your agent's `agent.ts` to import and use the MCP server's tools
-- Updates the agent's `serve-local` target to depend on the MCP server's serve target
+- Updates the agent's `dev` target to depend on the MCP server's serve target
 - Installs required dependencies
 
 ## Using the Connected MCP Server
@@ -67,10 +70,10 @@ The generator transforms your agent's `agent.ts` to use the MCP server's tools:
 
 ```ts title="packages/example/src/my-agent/agent.ts" {2,5,8}
 import { Agent, tool } from '@strands-agents/sdk';
-import { MyMcpServerClient } from ':my-scope/agent-connection';
+import { MyMcpServerClientStrands } from '@my-scope/agent-connection';
 
 export const getAgent = async (sessionId: string) => {
-  const myMcpServerClient = await MyMcpServerClient.create(sessionId);
+  const myMcpServerClient = await MyMcpServerClientStrands.create(sessionId);
   return new Agent({
     systemPrompt: '...',
     tools: [myMcpServerClient],
@@ -99,7 +102,7 @@ The MCP server's AgentCore runtime ARN is automatically registered in the `agent
 <Fragment slot="terraform">
 After running the connection generator, you need to grant the agent permission to invoke the MCP server in your Terraform configuration:
 
-```hcl title="packages/infra/src/main.tf" {12-24}
+```hcl title="packages/infra/src/main.tf" {9-25}
 module "inventory_mcp_server" {
   source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
 }
@@ -133,12 +136,12 @@ The MCP server's AgentCore runtime ARN is automatically registered in the `agent
 
 ## Local Development
 
-The generator configures the agent's `serve-local` target to:
+The generator configures the agent's `dev` target to:
 1. Start the connected MCP server(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client uses direct HTTP transport instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client uses direct HTTP transport instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.