Skip to content

feat: implement gateway integration#472

Merged
aidandaly24 merged 28 commits intomainfrom
feat/gateway-integration
Mar 2, 2026
Merged

feat: implement gateway integration#472
aidandaly24 merged 28 commits intomainfrom
feat/gateway-integration

Conversation

@aidandaly24
Copy link
Contributor

Description

Adds MCP Gateway integration to the AgentCore CLI, enabling users to create gateways, configure gateway targets (external MCP server endpoints or compute-backed), manage outbound authentication credentials (OAuth2, API Key), and deploy gateway infrastructure via CDK.

Gateway Management

  • agentcore add gateway — create gateways with NONE, AWS_IAM, or CUSTOM_JWT authorization
  • agentcore add gateway-target — create targets pointing to external MCP server endpoints or compute-backed implementations
  • agentcore remove gateway / agentcore remove gateway-target — remove resources with smart cascade (targets move to unassigned rather than being deleted)

Authentication

  • Outbound auth: OAuth2 (client credentials flow) and API Key credential providers for gateway targets to authenticate with upstream MCP servers
  • Inbound auth: CUSTOM_JWT authorization with OIDC discovery, allowing gateways to validate Bearer tokens from calling agents
  • Managed credential auto-creation: CUSTOM_JWT gateways automatically create an OAuth credential for agent M2M authentication

Identity & Credentials

  • agentcore add identity — create OAuth2 or API Key credentials via CLI or TUI wizard
  • Inline credential creation during the gateway target wizard flow
  • Credentials stored in .env.local with AWS credential providers created via SDK
  • Managed credential protection to prevent accidental deletion

Agent Templates

  • All four frameworks (Strands, LangChain, OpenAI, Google ADK) receive gateway auth code via Handlebars template injection
  • AWS_IAM → SigV4 auth using mcp-proxy-for-aws
  • CUSTOM_JWT → Bearer token auth with OAuth token fetch from managed credential
  • Multi-gateway support: per-gateway client functions generated for agents connecting to multiple gateways

TUI Wizards

  • Gateway creation wizard with CUSTOM_JWT sub-flow (discovery URL → audience → clients)
  • Gateway target wizard: name → source → endpoint → language → gateway → outbound-auth → confirm
  • Identity wizard reusable as standalone or inline sub-flow during target creation

Deploy & Dev

  • Gateway target sync status displayed after agentcore deploy
  • agentcore dev injects AGENTCORE_GATEWAY_{NAME}_URL and AGENTCORE_GATEWAY_{NAME}_AUTH_TYPE environment variables from deployed state for local development against real gateways

Cleanup & Refactors

  • Renamed "MCP Tool" → "Gateway Target" across all UI labels, CLI output, and code comments
  • Removed dead MCP Runtime bind flow from add gateway TUI
  • Removed dead agent binding step from add gateway wizard
  • Wired existing-endpoint routing for gateway targets

Related Issues

Documentation PR

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 typecheck
  • I ran npm run lint

Unit tests added for:

  • Schema validation (gateway configs, JWT authorizers, CUSTOM_JWT, tool definitions)
  • Gateway operations (create, remove, preview, cascade deletion)
  • Credential providers (OAuth2, API Key creation and management)
  • Deploy status tracking (gateway target sync status)
  • TUI components (AddScreen/RemoveScreen gateway options, ResourceGraph)
  • CUSTOM_JWT CLI validation and managed credential protection

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.

aidandaly24 and others added 26 commits March 2, 2026 14:56
…s) (#375)

* ci: add feat/gateway-integration branch to workflow triggers (#376)

* feat: mcp gateway schema types (auth, outbound auth, OAuth credentials)

* fix: address CR feedback — scopes optional, specific validation errors
* feat: add OAuth credential provider creation during deploy

* fix: address review comments — add clarifying comments for vendor config, race condition, and ARN inconsistency

* fix: use typed SDK responses instead of Record<string, unknown> casts

* fix: on conflict, update OAuth provider instead of GET to avoid silently ignoring new credentials
#414)

* refactor: remove exposure/mcp-runtime mode from gateway-target command

All gateway targets are now behind-gateway only. The mcp-runtime
exposure mode was disabled and never used by customers.

- Remove ExposureMode type, EXPOSURE_MODE_OPTIONS, --exposure and --agents CLI flags
- Simplify wizard flow: name → source → language → gateway → host → confirm
- Remove mcp-runtime code paths from create-mcp, remove-gateway-target, McpGuidedEditor
- Remove existingAgents prop chain (only used for mcp-runtime agent selection)
- Clean up unused imports (ViewMode, AgentCoreMcpRuntimeTool, WizardMultiSelect)

* test: update tests for exposure removal

- Remove mcp-runtime validation tests and fixtures
- Remove mcp-runtime integration tests (add and remove)
- Simplify gateway target test fixtures to behind-gateway only

* style: fix formatting
Comprehensive test coverage for MCP Gateway Phase 1 Batches 1-3:

- Schema validation: gateway targets, outbound auth, credentials, deployed state
- OAuth credential provider: CRUD operations, conflict handling, error paths
- Pre-deploy identity: OAuth setup, credential collection, env var mapping
- CLI validation: existing-endpoint path, credential validation
- Deploy outputs: buildDeployedState with credentials, parseGatewayOutputs
- External target creation: assignment, unassigned, duplicates, outboundAuth
- Gateway target removal: listing, preview, removal operations
- Preflight: gateway-only deploy validation
- Credential references: cross-gateway warning on removal
- Add command actions: buildGatewayTargetConfig mapping
- UI: AddScreen/RemoveScreen enablement, ResourceGraph unassigned targets
- Types: constants validation (AUTHORIZER_TYPE_OPTIONS, SKIP_FOR_NOW, SOURCE_OPTIONS)

Adds 86 new test cases across 17 files.
…emoval (#410)

* feat: assign unassigned targets to gateways and preserve targets on removal

* test: add unit tests for unassigned target assignment and gateway removal

- getUnassignedTargets: returns targets, empty when no config, empty when field missing
- createGatewayFromWizard: moves selected targets to new gateway, removes from unassigned
- removeGateway: preserves targets as unassigned on removal, no-op for empty gateways
- previewRemoveGateway: shows 'will become unassigned' warning

* style: fix formatting and merge duplicate imports

* docs: add comment explaining unassigned targets preservation
…CLI flags (#416)

* feat: add OAuth credential support to add identity and outbound auth CLI flags

Extend createCredential to support OAuth credentials alongside API keys:
- CreateCredentialConfig is now a discriminated union (ApiKey vs OAuth)
- OAuth writes CLIENT_ID and CLIENT_SECRET to .env.local
- OAuth writes OAuthCredentialProvider config to agentcore.json

Add CLI flags for non-interactive workflows:
- add identity: --type oauth, --discovery-url, --client-id, --client-secret, --scopes
- add gateway-target: --outbound-auth, --credential-name, --oauth-client-id,
  --oauth-client-secret, --oauth-discovery-url, --oauth-scopes
- Inline OAuth credential creation when --oauth-* fields provided without --credential-name

Adds 15 new tests covering OAuth credential creation, validation, and edge cases.

* fix: use || instead of ?? for empty string handling and add discoveryUrl validation

* fix: sanitize hyphens in credential env var names for POSIX compliance

* test: update env var expectations for hyphen-to-underscore sanitization
Fix ESLint prefer-nullish-coalescing errors.
…ploy flow (#411)

* feat: add OAuth credential setup and gateway output parsing to TUI deploy flow

* refactor: rename hasOwned* to has* identity provider helpers

* fix: log gateway config errors instead of silently catching
Query ListGatewayTargets after successful deployment and display
sync status for each target:
- READY: ✓ synced
- SYNCHRONIZING: ⟳ syncing...
- FAILED: ✗ failed

Integrated into both CLI and TUI deploy paths. TUI uses React state
for proper rendering. API errors are non-blocking — deploy succeeds
regardless of status query result.
Gateways are project-level in Phase 1 — all agents get all gateways
automatically via CDK env vars. The bind-agent-to-gateway flow was
pre-Phase 1 code that is no longer needed.

Add gateway now goes straight to the create wizard.
…427)

* feat: add gateway auth support to agent templates

Add SigV4 authentication to MCP client templates so agents can
authenticate with AWS_IAM gateways. Each framework's client.py
uses Handlebars conditionals to include auth when gateways exist.

SigV4HTTPXAuth class signs HTTP requests using botocore SigV4Auth,
passed to the MCP client via httpx.AsyncClient. Templates read
gateway URLs from AGENTCORE_GATEWAY_{NAME}_URL env vars and handle
missing vars gracefully (warn, don't crash).

Updated all 5 frameworks: Strands, LangChain, OpenAI Agents,
Google ADK, AutoGen. Schema mapper reads mcp.json to populate
gateway config for template rendering. All gateways are auto-
included when creating an agent.

* feat: add multi-gateway support and fix template rendering

Replace single-gateway [0] indexing with {{#each gatewayProviders}}
loops. Each gateway gets its own client function (Strands) or entry
in the servers dict (LangChain/OpenAI/AutoGen/ADK).

Add snakeCase Handlebars helper for gateway function names.
Add gatewayAuthTypes array for conditional SigV4 imports.
Fix @index parse error by using plain variable names.

* fix: update main.py files with gateway conditional imports

All 5 framework main.py files now use Handlebars conditionals to
import the correct MCP client function based on hasGateway flag.
Fix snakeCase helper to handle all special characters.

* style: fix formatting

* refactor: use mcp-proxy-for-aws for gateway auth, remove AutoGen gateway support

Replace custom SigV4HTTPXAuth class with official mcp-proxy-for-aws package:
- Strands: aws_iam_streamablehttp_client factory pattern
- LangChain: SigV4HTTPXAuth via auth param in MultiServerMCPClient config
- OpenAI Agents: SigV4HTTPXAuth via httpx_client_factory param
- Google ADK: SigV4HTTPXAuth via httpx_client_factory in StreamableHTTPConnectionParams

Revert AutoGen to original upstream — SDK doesn't support custom
httpx auth (no httpx_client_factory param).

* fix: pass AWS region to aws_iam_streamablehttp_client in Strands template
* feat: wire existing-endpoint flow for gateway targets

* test: add routing and validation tests for existing-endpoint flow

* refactor: remove source/language/host steps, existing-endpoint is the only flow
…ploy (#432)

* fix: correct CDK template type names and prop names

The CDK stack template used McpSpec (doesn't exist) instead of
AgentCoreMcpSpec, and passed wrong prop names to AgentCoreMcp:
- spec → mcpSpec
- application → agentCoreApplication
- Added missing projectName prop

* fix: collect API key credential ARNs and write to deployed state before CDK synth

API key credential providers were created during deploy but their ARNs
were not stored in deployed state, causing CDK to fail with 'Credential
not found in deployed state' for gateway targets with API key auth.

- Return credentialProviderArn from create/update API key providers
- Unify API key and OAuth credential ARNs into single deployed state map
- Move credential setup before CDK synth so template can read ARNs
- Write partial deployed state with credentials before synth

* fix: pass credential ARNs from deployed state to CDK gateway construct

CDK template now reads deployed-state.json and extracts credential
provider ARNs per target, passing them to AgentCoreMcp so gateway
targets can reference outbound auth credentials.

* fix: reorder TUI preflight to create credentials before CDK synth

* fix: fetch OAuth credential ARN via Get after create/update

* fix: handle Mcp prefix in gateway output key parsing

* fix: bump CDK version to 2.239.0 in project template

* fix: lint errors in deploy actions and preflight hook
Read deployed-state.json for gateway URLs and mcp.json for auth types,
then set AGENTCORE_GATEWAY_{NAME}_URL and AGENTCORE_GATEWAY_{NAME}_AUTH_TYPE
env vars when running agentcore dev locally.

- New gateway-env.ts helper iterates all deployment targets
- Integrated in both CLI dev command and TUI dev hook
- .env.local values take precedence over gateway env vars
- Graceful fallback when no deployed state exists
- Fixed parseGatewayOutputs to parse Id, Arn, and Url outputs separately
- Added gatewayUrl field to deployed-state schema (optional, backward compat)
…#459)

* refactor: remove mode selection and bind flow from gateway target wizard

* fix: rename 'MCP Tool' to 'Gateway Target' in UI labels, CLI output, and comments

* fix: update CDK asset snapshot for cdk/bin/cdk.ts

* fix: prettier formatting for AddGatewayTargetFlow.tsx
* fix: require gateway when creating a gateway target

A gateway target must always be attached to a gateway. Previously it was
possible to create unassigned targets via "Skip for now" in the TUI or
by omitting --gateway in non-interactive mode.

- Validation now requires --gateway and verifies the gateway exists
- TUI removes the "Skip for now" option from gateway selection
- createExternalGatewayTarget rejects missing gateway at operations layer
- Updated tests to cover all new validation paths

* style: fix prettier formatting
* feat: add OAuth credential type to add identity TUI wizard

* fix: add OIDC well-known suffix validation to identity TUI discovery URL

* refactor: reuse identity screen for OAuth credential creation in gateway target flow

* fix: correct deploy step ordering and credential count display

* fix: allow identity creation without existing agents

* fix: rename MCP gateway references to gateway in UI text

* fix: add missing newline to identity types
* feat: extend JWT wizard with allowedScopes and agent OAuth credential inputs

* feat: auto-create managed OAuth credential for CUSTOM_JWT gateway

* feat: add CLI flags for CUSTOM_JWT agent OAuth credentials

* feat: add CUSTOM_JWT Bearer token auth to agent templates (Strands, LangChain, OpenAI, Google ADK)

* feat: protect managed credentials from accidental deletion

* test: add tests for CUSTOM_JWT CLI validation and managed credential protection

* fix: resolve httpx import collision between AWS_IAM and CUSTOM_JWT templates

* fix: use placeholder instead of initialValue for gateway discovery URL

* feat: wire CUSTOM_JWT inbound auth through AgentCore identity system
@aidandaly24 aidandaly24 requested a review from a team March 2, 2026 20:08
@github-actions github-actions bot added the size/xl PR size: XL label Mar 2, 2026
@github-actions
Copy link
Contributor

github-actions bot commented Mar 2, 2026

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 46.28% 3397 / 7340
🔵 Statements 45.88% 3576 / 7794
🔵 Functions 47.91% 679 / 1417
🔵 Branches 50.54% 2223 / 4398
Generated in workflow #796 for commit 81379a3 by the Vitest Coverage Report Action

@github-actions github-actions bot added size/xl PR size: XL and removed size/xl PR size: XL labels Mar 2, 2026
@github-actions github-actions bot added size/xl PR size: XL and removed size/xl PR size: XL labels Mar 2, 2026
Copy link
Contributor

@jesseturner21 jesseturner21 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

send it

@aidandaly24 aidandaly24 merged commit 3cf1342 into main Mar 2, 2026
25 of 28 checks passed
@aidandaly24 aidandaly24 deleted the feat/gateway-integration branch March 2, 2026 20:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/xl PR size: XL

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants