@aws/nx-plugin-mcp 1.0.0-rc.44 → 1.0.0-rc.45

package/docs/guides/ts-dcr-proxy.mdx

@@ -0,0 +1,569 @@
+---
+title: DCR Proxy
+description: Generate an OAuth Dynamic Client Registration proxy for Cognito-authenticated MCP servers
+generator: ts#dcr-proxy
+---
+
+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';
+import Snippet from '@components/snippet.astro';
+
+The DCR Proxy generator creates an OAuth [Dynamic Client Registration (DCR)](https://datatracker.ietf.org/doc/html/rfc7591) proxy in front of an Amazon Cognito User Pool.
+
+MCP clients (such as Claude Code, Kiro CLI or the MCP Inspector) expect to authenticate against an OAuth authorization server that supports Dynamic Client Registration and metadata discovery. Amazon Cognito does not support DCR natively, and its App Client secret must never be exposed to a public client. This proxy bridges that gap: it keeps the Cognito Hosted UI flow intact, implements DCR, injects the App Client secret server-side during the token exchange, and forwards MCP traffic to your upstream MCP server.
+
+## Usage
+
+### Generate a DCR proxy
+
+<RunGenerator generator="ts#dcr-proxy" />
+
+### Options
+
+<GeneratorParameters generator="ts#dcr-proxy" />
+
+## Generator Output
+
+The generator creates a standalone <Link path="/guides/typescript-project">TypeScript project</Link> containing the Lambda handlers, and infrastructure to deploy them based on your selected `iacProvider`.
+
+<FileTree>
+
+- \<dcr-proxy-name>
+  - src/
+    - handlers/
+      - authorization-server-metadata.ts Serves `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration`
+      - protected-resource-metadata.ts Serves `/.well-known/oauth-protected-resource`
+      - register.ts RFC 7591 Dynamic Client Registration
+      - authorize.ts Redirects to the Cognito Hosted UI
+      - token.ts Injects the App Client secret and exchanges the token
+      - mcp-proxy.ts Proxies `/mcp` requests to the upstream MCP server
+
+</FileTree>
+
+The handlers are bundled independently with [Rolldown](https://rolldown.rs/), and both IaC providers reference the resulting bundle output.
+
+### Infrastructure
+
+<Snippet name="shared-constructs" />
+
+For deploying the proxy, the following files are generated:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - app
+      - dcr-proxies
+        - \<dcr-proxy-name>
+          - \<dcr-proxy-name>.ts CDK construct which deploys the proxy
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - app
+      - dcr-proxies
+        - \<dcr-proxy-name>
+          - \<dcr-proxy-name>.tf Terraform module which deploys the proxy
+</FileTree>
+</Fragment>
+</Infrastructure>
+
+The infrastructure provisions an API Gateway HTTP API with the following routes:
+
+| Route | Description |
+| --- | --- |
+| `GET /.well-known/oauth-protected-resource` | Protected resource metadata |
+| `GET /.well-known/oauth-authorization-server` | Authorization server metadata |
+| `GET /.well-known/openid-configuration` | OpenID configuration (served by the authorization server metadata handler) |
+| `POST /register` | Dynamic Client Registration |
+| `GET /authorize` | Authorization (redirects to the Cognito Hosted UI) |
+| `POST /oauth/token` | Token exchange (injects the App Client secret) |
+| `ANY /mcp` | Proxy to the upstream MCP server |
+
+Only the token handler is granted read access to the Cognito App Client secret in Secrets Manager.
+
+## Deploying the DCR Proxy
+
+The proxy does not create your Cognito resources or your MCP server. Instead, you inject the identifiers of resources managed elsewhere (whether generated by this plugin or provisioned separately), keeping the proxy decoupled from how those resources are provisioned.
+
+You provide:
+
+- The Cognito User Pool id and App Client id
+- The ARN of a Secrets Manager secret holding the App Client secret. The token handler reads this at runtime; the value is never exposed to the client.
+- The base URL of the Cognito Hosted UI domain
+- The full URL of your upstream MCP server
+
+<Infrastructure>
+<Fragment slot="cdk">
+Instantiate the generated construct in your stack, passing the required properties:
+
+```typescript
+import { DcrProxy } from ':my-scope/common-constructs';
+
+new DcrProxy(this, 'DcrProxy', {
+  userPoolId: userPool.userPoolId,
+  userPoolClientId: userPoolClient.userPoolClientId,
+  cognitoClientSecretArn: clientSecret.secretArn,
+  cognitoHostedUiBase: userPoolDomain.baseUrl(),
+  upstreamUrl: 'https://my-agentcore-runtime-url/mcp',
+});
+```
+
+The construct exposes the proxy endpoints (`proxyUrl`, `mcpUrl`, `metadataUrl`, `tokenEndpoint`, `registrationEndpoint`) as readonly properties.
+</Fragment>
+<Fragment slot="terraform">
+Reference the generated module from your Terraform configuration, passing the required variables:
+
+```hcl
+module "dcr_proxy" {
+  source = "../../common/terraform/src/app/dcr-proxies/dcr-proxy"
+
+  user_pool_id              = aws_cognito_user_pool.main.id
+  user_pool_client_id       = aws_cognito_user_pool_client.main.id
+  cognito_client_secret_arn = aws_secretsmanager_secret.client_secret.arn
+  cognito_hosted_ui_base    = "https://${aws_cognito_user_pool_domain.main.domain}.auth.${data.aws_region.current.region}.amazoncognito.com"
+  upstream_url              = "https://my-agentcore-runtime-url/mcp"
+  asset_bucket_name         = module.asset_bucket.bucket_name
+}
+```
+
+The module exposes the proxy endpoints (`proxy_url`, `mcp_url`, `metadata_url`, `token_endpoint`, `registration_endpoint`) as outputs.
+</Fragment>
+</Infrastructure>
+
+:::note
+The `/mcp` proxy uses API Gateway HTTP API integrations, which have a hard 29 second timeout. Long-running upstream requests are buffered by the proxy rather than streamed.
+:::
+
+:::tip[Reusing an existing User Pool]
+If you already have a User Pool from the <Link path="guides/react-website-auth">`ts#website#auth`</Link> generator, you can front an MCP server for the same website users. See <Link path="guides/ts-dcr-proxy#reusing-a-useridentity-user-pool">Reusing a UserIdentity User Pool</Link> below.
+:::
+
+### Fronting an MCP Server
+
+To front an MCP server generated with the <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> (or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>) generator using `--auth cognito`, pass the **same** User Pool and App Client to both the MCP server and the proxy, and use the MCP server construct's `invocationUrl` as the proxy's `upstreamUrl`.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```typescript
+import {
+  DcrProxy,
+  MyProjectMcpServer,
+  UserIdentity,
+} from ':my-scope/common-constructs';
+import { OAuthScope } from 'aws-cdk-lib/aws-cognito';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+
+const identity = new UserIdentity(this, 'Identity');
+
+// A confidential App Client the proxy uses for the token exchange. Register the
+// callback URLs your clients use (see below).
+const proxyClient = identity.userPool.addClient('DcrProxyClient', {
+  generateSecret: true,
+  oAuth: {
+    flows: { authorizationCodeGrant: true },
+    scopes: [OAuthScope.OPENID, OAuthScope.EMAIL, OAuthScope.PROFILE],
+    callbackUrls: [
+      'http://localhost:41100/callback',
+      // Callback used by Claude Desktop
+      'https://claude.ai/api/mcp/auth_callback',
+    ],
+  },
+});
+
+// Store the App Client secret in Secrets Manager for the token handler to read
+const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
+  secretStringValue: proxyClient.userPoolClientSecret,
+});
+
+// The MCP server, authorizing JWTs issued for the same App Client
+const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer', {
+  identity: {
+    userPool: identity.userPool,
+    userPoolClient: proxyClient,
+  },
+});
+
+new DcrProxy(this, 'DcrProxy', {
+  userPoolId: identity.userPool.userPoolId,
+  userPoolClientId: proxyClient.userPoolClientId,
+  cognitoClientSecretArn: clientSecret.secretArn,
+  cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
+  // Use the MCP server construct's invocation URL rather than hardcoding it
+  upstreamUrl: mcpServer.invocationUrl,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+# A confidential App Client the proxy uses for the token exchange. Register the
+# callback URLs your clients use (see below).
+resource "aws_cognito_user_pool_client" "dcr_proxy" {
+  name                                 = "dcr-proxy-client"
+  user_pool_id                         = module.user_identity.user_pool_id
+  generate_secret                      = true
+  allowed_oauth_flows                  = ["code"]
+  allowed_oauth_flows_user_pool_client = true
+  allowed_oauth_scopes                 = ["openid", "email", "profile"]
+  callback_urls = [
+    "http://localhost:41100/callback",
+    # Callback used by Claude Desktop
+    "https://claude.ai/api/mcp/auth_callback",
+  ]
+}
+
+# Store the App Client secret in Secrets Manager for the token handler to read
+resource "aws_secretsmanager_secret" "client_secret" {
+  name = "my-dcr-proxy-client-secret"
+}
+
+resource "aws_secretsmanager_secret_version" "client_secret" {
+  secret_id     = aws_secretsmanager_secret.client_secret.id
+  secret_string = aws_cognito_user_pool_client.dcr_proxy.client_secret
+}
+
+# The MCP server, authorizing JWTs issued for the same App Client
+module "my_project_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
+
+  user_pool_id              = module.user_identity.user_pool_id
+  user_pool_client_ids      = [aws_cognito_user_pool_client.dcr_proxy.id]
+  appconfig_application_id  = module.runtime_config.application_id
+  appconfig_application_arn = module.runtime_config.application_arn
+}
+
+module "dcr_proxy" {
+  source = "../../common/terraform/src/app/dcr-proxies/dcr-proxy"
+
+  user_pool_id              = module.user_identity.user_pool_id
+  user_pool_client_id       = aws_cognito_user_pool_client.dcr_proxy.id
+  cognito_client_secret_arn = aws_secretsmanager_secret.client_secret.arn
+  cognito_hosted_ui_base    = "https://${module.user_identity.user_pool_domain}.auth.${data.aws_region.current.region}.amazoncognito.com"
+  # Use the MCP server module's invocation URL rather than hardcoding it
+  upstream_url              = module.my_project_mcp_server.invocation_url
+  asset_bucket_name         = module.asset_bucket.bucket_name
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Fronting an AgentCore Gateway
+
+To front an [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) generated with the <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> generator using `--auth cognito`, pass the **same** User Pool and App Client to both the gateway and the proxy, and use the gateway construct's `gatewayUrl` as the proxy's `upstreamUrl`.
+
+:::caution
+The proxy's OAuth flow requires a Cognito-authenticated gateway. Generate the gateway with `--auth cognito`; the default IAM-authenticated gateway is not compatible with the proxy.
+:::
+
+<Infrastructure>
+<Fragment slot="cdk">
+```typescript
+import {
+  DcrProxy,
+  MyGateway,
+  UserIdentity,
+} from ':my-scope/common-constructs';
+import { OAuthScope } from 'aws-cdk-lib/aws-cognito';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+
+const identity = new UserIdentity(this, 'Identity');
+
+// A confidential App Client the proxy uses for the token exchange. Register the
+// callback URLs your clients use (see below).
+const proxyClient = identity.userPool.addClient('DcrProxyClient', {
+  generateSecret: true,
+  oAuth: {
+    flows: { authorizationCodeGrant: true },
+    scopes: [OAuthScope.OPENID, OAuthScope.EMAIL, OAuthScope.PROFILE],
+    callbackUrls: [
+      'http://localhost:41100/callback',
+      // Callback used by Claude Desktop
+      'https://claude.ai/api/mcp/auth_callback',
+    ],
+  },
+});
+
+// Store the App Client secret in Secrets Manager for the token handler to read
+const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
+  secretStringValue: proxyClient.userPoolClientSecret,
+});
+
+// The gateway, authorizing JWTs issued for the same App Client
+const gateway = new MyGateway(this, 'MyGateway', {
+  identity: {
+    userPool: identity.userPool,
+    userPoolClient: proxyClient,
+  },
+});
+
+new DcrProxy(this, 'DcrProxy', {
+  userPoolId: identity.userPool.userPoolId,
+  userPoolClientId: proxyClient.userPoolClientId,
+  cognitoClientSecretArn: clientSecret.secretArn,
+  cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
+  // Use the gateway construct's URL rather than hardcoding it
+  upstreamUrl: gateway.gateway.gatewayUrl,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+# A confidential App Client the proxy uses for the token exchange. Register the
+# callback URLs your clients use (see below).
+resource "aws_cognito_user_pool_client" "dcr_proxy" {
+  name                                 = "dcr-proxy-client"
+  user_pool_id                         = module.user_identity.user_pool_id
+  generate_secret                      = true
+  allowed_oauth_flows                  = ["code"]
+  allowed_oauth_flows_user_pool_client = true
+  allowed_oauth_scopes                 = ["openid", "email", "profile"]
+  callback_urls = [
+    "http://localhost:41100/callback",
+    # Callback used by Claude Desktop
+    "https://claude.ai/api/mcp/auth_callback",
+  ]
+}
+
+# Store the App Client secret in Secrets Manager for the token handler to read
+resource "aws_secretsmanager_secret" "client_secret" {
+  name = "my-dcr-proxy-client-secret"
+}
+
+resource "aws_secretsmanager_secret_version" "client_secret" {
+  secret_id     = aws_secretsmanager_secret.client_secret.id
+  secret_string = aws_cognito_user_pool_client.dcr_proxy.client_secret
+}
+
+# The gateway, authorizing JWTs issued for the same App Client
+module "my_gateway" {
+  source = "../../common/terraform/src/app/agentcore-gateway/my-gateway"
+
+  user_pool_id         = module.user_identity.user_pool_id
+  user_pool_client_ids = [aws_cognito_user_pool_client.dcr_proxy.id]
+}
+
+module "dcr_proxy" {
+  source = "../../common/terraform/src/app/dcr-proxies/dcr-proxy"
+
+  user_pool_id              = module.user_identity.user_pool_id
+  user_pool_client_id       = aws_cognito_user_pool_client.dcr_proxy.id
+  cognito_client_secret_arn = aws_secretsmanager_secret.client_secret.arn
+  cognito_hosted_ui_base    = "https://${module.user_identity.user_pool_domain}.auth.${data.aws_region.current.region}.amazoncognito.com"
+  # Use the gateway module's URL rather than hardcoding it
+  upstream_url              = module.my_gateway.gateway_url
+  asset_bucket_name         = module.asset_bucket.bucket_name
+}
+```
+</Fragment>
+</Infrastructure>
+
+### Allowing Client Redirect URIs
+
+Because the proxy implements Dynamic Client Registration virtually — there is no per-client Cognito App Client — every MCP client authenticates through the **single App Client** you pass to the proxy. During the OAuth flow the proxy forwards the client's `redirect_uri` to the Cognito Hosted UI unchanged, so Cognito performs the authoritative check: the callback must be registered as a **callback URL on that App Client**, otherwise Cognito rejects the login.
+
+This is a side effect of the virtual DCR design. A client can register any `redirect_uri` with the proxy, but the login only succeeds if that exact URL is one of the App Client's callback URLs. Cognito matches callback URLs exactly, including the port, so clients that listen on a random ephemeral port cannot be covered by a wildcard — you must pin each client to a fixed callback URL and register that exact URL on the App Client.
+
+Add the callback URLs your clients use when you create the App Client:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```typescript
+const userPoolClient = userPool.addClient('DcrProxyClient', {
+  generateSecret: true,
+  oAuth: {
+    flows: { authorizationCodeGrant: true },
+    callbackUrls: [
+      // Local clients: pin to a fixed, uncommon port rather than a default one
+      'http://localhost:41100/callback',
+      // Callback used by Claude Desktop
+      'https://claude.ai/api/mcp/auth_callback',
+    ],
+  },
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+resource "aws_cognito_user_pool_client" "dcr_proxy" {
+  # ...
+  generate_secret                     = true
+  allowed_oauth_flows                 = ["code"]
+  allowed_oauth_flows_user_pool_client = true
+  callback_urls = [
+    # Local clients: pin to a fixed, uncommon port rather than a default one
+    "http://localhost:41100/callback",
+    # Callback used by Claude Desktop
+    "https://claude.ai/api/mcp/auth_callback",
+  ]
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::caution
+Only register callback URLs you trust — any client that can drive a browser to one of these URLs can complete a login against your User Pool.
+:::
+
+## Consuming a Proxied MCP Server
+
+The proxy lets MCP clients authenticate against your Cognito User Pool without any client-specific configuration beyond the proxy URL. When a client connects to the `/mcp` endpoint, it discovers the OAuth metadata (via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`), dynamically registers itself, and drives the user through the Cognito Hosted UI login. The proxy injects the App Client secret during the token exchange, so the client never needs it.
+
+To connect a client, point it at the proxy's `mcpUrl` (i.e. `<proxyUrl>/mcp`). The examples below assume your proxy is deployed at `https://my-proxy.example.com`.
+
+:::note
+Each client uses a callback URL during the OAuth flow. That exact URL — including its port — must be registered as a [callback URL on your Cognito App Client](#allowing-client-redirect-uris), otherwise the login fails. Where a client would otherwise pick a random port, pin it to a fixed value and register that value.
+:::
+
+### Claude Code
+
+Add the proxied server with the [`claude mcp add`](https://code.claude.com/docs/en/mcp) command, using the HTTP transport. By default Claude Code listens on a random callback port; pass `--callback-port` to pin it to the port registered on your App Client (`41100` in the examples above). Claude Code always uses the `/callback` path, so the resulting redirect URI is `http://localhost:41100/callback`:
+
+```bash
+claude mcp add --transport http --callback-port 41100 my-proxied-server https://my-proxy.example.com/mcp
+```
+
+When you first invoke a tool from the server, Claude Code opens the Cognito Hosted UI to authenticate before the request is proxied upstream.
+
+### Kiro CLI
+
+Add the server to your [Kiro CLI](https://kiro.dev/docs/cli/mcp/) MCP configuration, using the HTTP transport. Without an explicit `oauth.redirectUri` Kiro picks a random callback port; set it to the URL registered on your App Client so the port and path match exactly:
+
+```json
+{
+  "mcpServers": {
+    "my-proxied-server": {
+      "type": "http",
+      "url": "https://my-proxy.example.com/mcp",
+      "oauth": {
+        "redirectUri": "http://localhost:41100/callback"
+      }
+    }
+  }
+}
+```
+
+Kiro CLI triggers the Cognito Hosted UI login on first use and manages the resulting tokens for subsequent requests.
+
+:::tip
+Any MCP client that supports the Streamable HTTP transport along with OAuth authorization and Dynamic Client Registration can connect to the proxy the same way — supply the `/mcp` URL and the client handles discovery, registration, and login for you.
+:::
+
+## Reusing a UserIdentity User Pool
+
+If you already have a User Pool from the <Link path="guides/react-website-auth">`ts#website#auth`</Link> generator (the `UserIdentity` construct), you can front an MCP server for the **same users** who log in to your website. Reuse its `userPool`, but add a **separate App Client** for the proxy: the website's client is a public client without a secret, whereas the DCR proxy requires a confidential client (`generateSecret: true`) whose secret the token handler injects during the token exchange.
+
+`UserIdentity` configures the User Pool domain with [Managed Login (version 2)](https://docs.aws.amazon.com/cognito/latest/developerguide/managed-login.html). Managed Login requires a **branding style per App Client**, so you must create one for the new proxy client — otherwise its hosted login page returns `403`.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```typescript
+import {
+  DcrProxy,
+  MyProjectMcpServer,
+  UserIdentity,
+} from ':my-scope/common-constructs';
+import { OAuthScope, CfnManagedLoginBranding } from 'aws-cdk-lib/aws-cognito';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+
+// The user pool created by ts#website#auth for your website users
+const identity = new UserIdentity(this, 'Identity');
+
+// A confidential App Client on the SAME user pool for the DCR proxy
+const proxyClient = identity.userPool.addClient('DcrProxyClient', {
+  generateSecret: true,
+  oAuth: {
+    flows: { authorizationCodeGrant: true },
+    scopes: [OAuthScope.OPENID, OAuthScope.EMAIL, OAuthScope.PROFILE],
+    callbackUrls: ['http://localhost:41100/callback'],
+  },
+});
+
+// Managed Login needs a branding style for the new client
+new CfnManagedLoginBranding(this, 'DcrProxyClientBranding', {
+  userPoolId: identity.userPool.userPoolId,
+  clientId: proxyClient.userPoolClientId,
+  useCognitoProvidedValues: true,
+});
+
+const clientSecret = new secretsmanager.Secret(this, 'ClientSecret', {
+  secretStringValue: proxyClient.userPoolClientSecret,
+});
+
+const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer', {
+  identity: {
+    userPool: identity.userPool,
+    userPoolClient: proxyClient,
+  },
+});
+
+new DcrProxy(this, 'DcrProxy', {
+  userPoolId: identity.userPool.userPoolId,
+  userPoolClientId: proxyClient.userPoolClientId,
+  cognitoClientSecretArn: clientSecret.secretArn,
+  // The UserIdentity construct always creates a domain
+  cognitoHostedUiBase: identity.userPoolDomain.baseUrl(),
+  upstreamUrl: mcpServer.invocationUrl,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+# The user pool module created by ts#website#auth for your website users
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+# A confidential App Client on the SAME user pool for the DCR proxy
+resource "aws_cognito_user_pool_client" "dcr_proxy" {
+  name                                 = "dcr-proxy-client"
+  user_pool_id                         = module.user_identity.user_pool_id
+  generate_secret                      = true
+  allowed_oauth_flows                  = ["code"]
+  allowed_oauth_flows_user_pool_client = true
+  allowed_oauth_scopes                 = ["openid", "email", "profile"]
+  callback_urls                        = ["http://localhost:41100/callback"]
+}
+
+# Managed Login needs a branding style for the new client
+resource "aws_cognito_managed_login_branding" "dcr_proxy" {
+  user_pool_id                = module.user_identity.user_pool_id
+  client_id                   = aws_cognito_user_pool_client.dcr_proxy.id
+  use_cognito_provided_values = true
+}
+
+resource "aws_secretsmanager_secret" "client_secret" {
+  name = "my-dcr-proxy-client-secret"
+}
+
+resource "aws_secretsmanager_secret_version" "client_secret" {
+  secret_id     = aws_secretsmanager_secret.client_secret.id
+  secret_string = aws_cognito_user_pool_client.dcr_proxy.client_secret
+}
+
+module "my_project_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
+
+  user_pool_id              = module.user_identity.user_pool_id
+  user_pool_client_ids      = [aws_cognito_user_pool_client.dcr_proxy.id]
+  appconfig_application_id  = module.runtime_config.application_id
+  appconfig_application_arn = module.runtime_config.application_arn
+}
+
+module "dcr_proxy" {
+  source = "../../common/terraform/src/app/dcr-proxies/dcr-proxy"
+
+  user_pool_id              = module.user_identity.user_pool_id
+  user_pool_client_id       = aws_cognito_user_pool_client.dcr_proxy.id
+  cognito_client_secret_arn = aws_secretsmanager_secret.client_secret.arn
+  cognito_hosted_ui_base    = "https://${module.user_identity.user_pool_domain}.auth.${data.aws_region.current.region}.amazoncognito.com"
+  upstream_url              = module.my_project_mcp_server.invocation_url
+  asset_bucket_name         = module.asset_bucket.bucket_name
+}
+```
+</Fragment>
+</Infrastructure>

package/docs/guides/ts-lambda-function.mdx

@@ -56,7 +56,7 @@ If the `functionPath` option is provided, the generator will add the handler to
 
 <Snippet name="shared-constructs" />
 
-The generator creates infrastructure as code for deploying your function based on your selected `iacProvider`:
+The generator creates infrastructure as code for deploying your function based on your selected `iac`:
 
 <Infrastructure>
 <Fragment slot="cdk">

package/docs/guides/ts-smithy-api.mdx

@@ -69,7 +69,7 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 
 ### Infrastructure
 
-Since this generator creates infrastructure as code based on your chosen `iacProvider`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
+Since this generator creates infrastructure as code based on your chosen `iac`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
 
 The common infrastructure as code project is structured as follows:
 
@@ -581,7 +581,7 @@ The local server will not only hot-reload when you make TypeScript changes to yo
 
 ## Deploying your Smithy API
 
-The generator creates CDK or Terraform infrastructure based on your selected `iacProvider`.
+The generator creates CDK or Terraform infrastructure based on your selected `iac`.
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -765,7 +765,7 @@ If you are actively working on both your CDK infrastructure and Smithy API toget
 </Fragment>
 <Fragment slot="terraform">
 :::note[Terraform Limitations]
-We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iacProvider`.
+We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iac`.
 :::
 </Fragment>
 </Infrastructure>

package/docs/guides/typescript-infrastructure.mdx

@@ -43,7 +43,7 @@ The generator will create the following project structure in the `<directory>/<n
 
 </FileTree>
 
-If you set the `enableStageConfig` option, the generator also creates two shared packages for centralized credential management (if they don't already exist):
+If you set the `stageConfig` option, the generator also creates two shared packages for centralized credential management (if they don't already exist):
 
 <FileTree>
 
@@ -99,9 +99,9 @@ new ApplicationStage(app, 'my-app-sandbox', {
 
 The `env` property tells CDK which AWS account and region to deploy to. `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are resolved automatically by the CDK CLI from your active AWS credentials. See the [CDK environments documentation](https://docs.aws.amazon.com/cdk/v2/guide/environments.html) for more details.
 
-If you generated with `enableStageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
+If you generated with `stageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
 
-```ts title="src/main.ts (with enableStageConfig)"
+```ts title="src/main.ts (with stageConfig)"
 import stagesConfig from ':my-scope/common-infra-config';
 
 const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
@@ -158,12 +158,12 @@ export class ApplicationStage extends Stage {
 ### Stage Credential Configuration
 
 :::note[Staged Configuration]
-This section applies when you generate with `enableStageConfig`. Without it, the generator produces a simpler setup where you manage AWS credentials yourself (e.g., by exporting `AWS_PROFILE` before deploying).
+This section applies when you generate with `stageConfig`. Without it, the generator produces a simpler setup where you manage AWS credentials yourself (e.g., by exporting `AWS_PROFILE` before deploying).
 :::
 
 When you have multiple stages targeting different AWS accounts, managing credentials manually can be error-prone, especially as the number of stages grows.
 
-The `enableStageConfig` option solves this by generating two shared packages:
+The `stageConfig` option solves this by generating two shared packages:
 
 - **`packages/common/infra-config`** — A single config file where you map each stage to its AWS credentials, account, and region. This is importable from any package in your workspace, so your CDK `main.ts` can read account and region from the same source of truth.
 - **`packages/common/scripts`** — `infra-deploy` and `infra-destroy` commands that wrap CDK with automatic credential resolution. When you run `deploy`, the script reads the config, sets the right AWS environment variables for the CDK child process, and runs `cdk deploy`. Your shell environment is never modified.
@@ -375,7 +375,7 @@ After a build, you can deploy your infrastructure to AWS using the `deploy` targ
 Use the `deploy-ci` target if deploying in a CI/CD pipeline. See below for more details.
 :::
 
-First, make sure you have AWS credentials configured. If you generated with `enableStageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
+First, make sure you have AWS credentials configured. If you generated with `stageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
 
 Then run the deploy target:
 

package/docs/snippets/lambda-function/deploying-your-function.mdx

@@ -3,7 +3,7 @@ title: Deploying your Function
 ---
 import Infrastructure from '@components/infrastructure.astro';
 
-This generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your function.
+This generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your function.
 
 <Infrastructure>
 <Fragment slot="cdk">

package/docs/snippets/rdb/deploying.mdx

@@ -5,7 +5,7 @@ import Infrastructure from '@components/infrastructure.astro';
 import Link from '@components/link.astro';
 import Drawer from '@components/drawer.astro';
 
-The relational database generator creates CDK or Terraform infrastructure based on your selected `iacProvider`.
+The relational database generator creates CDK or Terraform infrastructure based on your selected `iac`.
 
 <Infrastructure>
 <Fragment slot="cdk">