Description

Add full Custom JWT inbound authorization support for MCP gateways, including custom claim validations matching the CFN CustomClaimValidationType structure.

Summary

• Add Custom JWT authorizer type to the gateway TUI wizard with a dynamic constraint picker, custom claims manager (add/edit/delete), and optional OAuth client credential flow
• Add --custom-claims <json>, --client-id, --client-secret CLI flags (renaming from --agent-client-id/--agent-client-secret)
• Relax validation: allowedClients is no longer required — at least one of allowedAudience, allowedClients, allowedScopes, or customClaims must be provided
• Enforce HTTPS on OIDC discovery URLs in both schema validation and CLI/TUI input
• Add custom claims Zod schemas: ClaimMatchOperatorSchema, ClaimMatchValueSchema, InboundTokenClaimValueTypeSchema, CustomClaimValidationSchema

Changes by Category

Schema

• src/schema/schemas/mcp.ts — Custom claims Zod schemas; refactor CustomJwtAuthorizerConfigSchema with optional fields, .strict(), .superRefine() enforcing at-least-one constraint, HTTPS enforcement
• src/schema/schemas/deployed-state.ts — Make allowedAudience/allowedClients optional; add allowedScopes and customClaims fields

CLI Flags / Validation

• src/cli/commands/add/types.ts — Replace agentClientId/agentClientSecret with clientId/clientSecret; add customClaims
• src/cli/commands/add/validate.ts — At-least-one-constraint validation, --custom-claims JSON parsing, HTTPS check, renamed flags
• src/cli/primitives/GatewayPrimitive.ts — Renamed flags, custom claims JSON parsing, conditional field spreading

TUI Wizard

• src/cli/tui/screens/mcp/AddGatewayScreen.tsx — Major rewrite: typed JwtSubStep union, constraint picker multi-select, CustomClaimsManager component with add/edit/delete, CustomClaimForm tabbed form (Tab cycles, Left/Right cycles selects), HTTPS validation, disable raw Escape exit
• src/cli/tui/screens/mcp/types.ts — Updated jwtConfig type for optional fields and custom claims
• src/cli/tui/screens/mcp/useAddGatewayWizard.ts — Updated setJwtConfig parameter types
• src/cli/tui/hooks/useCreateMcp.ts — Pass customClaims directly; rename credential fields
• src/cli/tui/App.tsx — Remove dead PlaceholderScreen route
• src/cli/tui/screens/PlaceholderScreen.tsx — Deleted (unused)
• src/cli/tui/screens/index.ts — Remove PlaceholderScreen re-export

Tests

• src/schema/schemas/__tests__/mcp.test.ts — ClaimMatchValueSchema, CustomClaimValidationSchema, HTTPS, strict, scope-only, all-empty-constraints tests
• src/cli/commands/add/__tests__/validate.test.ts — Rewritten JWT validation: at-least-one-constraint, custom claims JSON, renamed flags
• src/cli/commands/add/__tests__/add-gateway.test.ts — Updated flag names
• src/cli/primitives/__tests__/GatewayPrimitive.test.ts — customClaims pipeline test suite (4 tests)
• src/cli/tui/screens/mcp/__tests__/AddGatewayJwtConfig.test.tsx — New 652-line test: 7 groups covering full JWT wizard TUI interactions
• src/cli/tui/screens/mcp/__tests__/finishJwtConfig.test.ts — New: validates TUI data mapping produces shapes accepted by CustomJwtAuthorizerConfigSchema
• src/cli/tui/screens/mcp/__tests__/useAddGatewayWizard.test.tsx — Extended wizard hook tests for JWT flow, navigation, targets
• integ-tests/tui/add-gateway-jwt.test.ts — New 415-line TUI integration test: full JWT wizard path
• integ-tests/tui/setup.ts — New TUI integration test setup

Bug Fix

• src/cli/cloudformation/outputs.ts — Updated comment documenting hash-suffixed output key pattern (companion CDK PR fixes the actual CfnOutput scope)

Screenshots

Related Issue

N/A — internal feature development

Documentation PR

N/A

Companion PR

CDK constructs: https://github.com/aws/agentcore-l3-cdk-constructs/pull/93

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots
• E2E deploy test: deployed CUSTOM_JWT gateway with audiences + custom claims, verified deployed-state.json populates correctly

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.