feat: add API Gateway REST API as new gateway target type (#509)

* refactor: rename McpGateway references to Gateway

* feat: add apiGateway Zod schemas and target validation

* feat: add --type api-gateway CLI support with validation and createApiGatewayTarget

* test: add apiGateway schema and validation tests

Author: aidandaly24

src/cli/cloudformation/outputs.ts

@@ -45,8 +45,8 @@ export function parseGatewayOutputs(
   const gatewayNames = Object.keys(gatewaySpecs);
   const gatewayIdMap = new Map(gatewayNames.map(name => [toPascalId(name), name]));
 
-  // Match patterns: Gateway{Name}{Type}Output or McpGateway{Name}{Type}Output
-  const outputPattern = /^(?:Mcp)?Gateway(.+?)(Id|Arn|Url)Output/;
+  // Match patterns: Gateway{Name}{Type}Output
+  const outputPattern = /^Gateway(.+?)(Id|Arn|Url)Output/;
 
   for (const [key, value] of Object.entries(outputs)) {
     const match = outputPattern.exec(key);

src/cli/commands/add/__tests__/validate.test.ts

@@ -555,6 +555,78 @@ describe('validate', () => {
       expect(result.error).toBe('--oauth-discovery-url must be a valid URL');
     });
 
+    it('accepts valid api-gateway options', async () => {
+      const result = await validateAddGatewayTargetOptions({
+        name: 'my-api',
+        type: 'api-gateway',
+        restApiId: 'abc123',
+        stage: 'prod',
+        gateway: 'my-gateway',
+      });
+      expect(result.valid).toBe(true);
+    });
+
+    it('rejects api-gateway without --rest-api-id', async () => {
+      const result = await validateAddGatewayTargetOptions({
+        name: 'my-api',
+        type: 'api-gateway',
+        stage: 'prod',
+        gateway: 'my-gateway',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('--rest-api-id is required');
+    });
+
+    it('rejects api-gateway without --stage', async () => {
+      const result = await validateAddGatewayTargetOptions({
+        name: 'my-api',
+        type: 'api-gateway',
+        restApiId: 'abc123',
+        gateway: 'my-gateway',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('--stage is required');
+    });
+
+    it('rejects --endpoint for api-gateway type', async () => {
+      const result = await validateAddGatewayTargetOptions({
+        name: 'my-api',
+        type: 'api-gateway',
+        restApiId: 'abc123',
+        stage: 'prod',
+        gateway: 'my-gateway',
+        endpoint: 'https://example.com',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('not applicable');
+    });
+
+    it('rejects --host for api-gateway type', async () => {
+      const result = await validateAddGatewayTargetOptions({
+        name: 'my-api',
+        type: 'api-gateway',
+        restApiId: 'abc123',
+        stage: 'prod',
+        gateway: 'my-gateway',
+        host: 'Lambda',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('not applicable');
+    });
+
+    it('rejects --outbound-auth for api-gateway type', async () => {
+      const result = await validateAddGatewayTargetOptions({
+        name: 'my-api',
+        type: 'api-gateway',
+        restApiId: 'abc123',
+        stage: 'prod',
+        gateway: 'my-gateway',
+        outboundAuthType: 'NONE',
+      });
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('not applicable');
+    });
+
     it('rejects --host with mcp-server type', async () => {
       const options: AddGatewayTargetOptions = {
         name: 'test-tool',

src/cli/commands/add/types.ts

@@ -59,6 +59,10 @@ export interface AddGatewayTargetOptions {
   oauthClientSecret?: string;
   oauthDiscoveryUrl?: string;
   oauthScopes?: string;
+  restApiId?: string;
+  stage?: string;
+  toolFilterPath?: string;
+  toolFilterMethods?: string;
   json?: boolean;
 }
 

src/cli/commands/add/validate.ts

@@ -220,13 +220,13 @@ export async function validateAddGatewayTargetOptions(options: AddGatewayTargetO
   }
 
   if (!options.type) {
-    return { valid: false, error: '--type is required. Valid options: mcp-server' };
+    return { valid: false, error: '--type is required. Valid options: mcp-server, api-gateway' };
   }
 
-  const typeMap: Record<string, string> = { 'mcp-server': 'mcpServer' };
+  const typeMap: Record<string, string> = { 'mcp-server': 'mcpServer', 'api-gateway': 'apiGateway' };
   const mappedType = typeMap[options.type];
   if (!mappedType) {
-    return { valid: false, error: `Invalid type: ${options.type}. Valid options: mcp-server` };
+    return { valid: false, error: `Invalid type: ${options.type}. Valid options: mcp-server, api-gateway` };
   }
   options.type = mappedType;
 
@@ -309,6 +309,35 @@ export async function validateAddGatewayTargetOptions(options: AddGatewayTargetO
     }
   }
 
+  if (mappedType === 'apiGateway') {
+    if (!options.restApiId) {
+      return { valid: false, error: '--rest-api-id is required for api-gateway type' };
+    }
+    if (!options.stage) {
+      return { valid: false, error: '--stage is required for api-gateway type' };
+    }
+    if (options.endpoint) {
+      return { valid: false, error: '--endpoint is not applicable for api-gateway type' };
+    }
+    if (options.host) {
+      return { valid: false, error: '--host is not applicable for api-gateway type' };
+    }
+    if (options.language && options.language !== 'Other') {
+      return { valid: false, error: '--language is not applicable for api-gateway type' };
+    }
+    if (options.outboundAuthType) {
+      return { valid: false, error: '--outbound-auth is not applicable for api-gateway type' };
+    }
+    if (options.credentialName) {
+      return { valid: false, error: '--credential-name is not applicable for api-gateway type' };
+    }
+    if (options.oauthClientId || options.oauthClientSecret || options.oauthDiscoveryUrl || options.oauthScopes) {
+      return { valid: false, error: 'OAuth options are not applicable for api-gateway type' };
+    }
+    options.language = 'Other';
+    return { valid: true };
+  }
+
   if (mappedType === 'mcpServer') {
     if (options.host) {
       return { valid: false, error: '--host is not applicable for MCP server targets' };

src/cli/operations/agent/generate/schema-mapper.ts

@@ -179,9 +179,9 @@ export function mapModelProviderToIdentityProviders(
 }
 
 /**
- * Maps MCP gateways to gateway providers for template rendering.
+ * Maps gateways to gateway providers for template rendering.
  */
-async function mapMcpGatewaysToGatewayProviders(): Promise<GatewayProviderRenderConfig[]> {
+async function mapGatewaysToGatewayProviders(): Promise<GatewayProviderRenderConfig[]> {
   try {
     const configIO = new ConfigIO();
     if (!configIO.configExists('mcp')) {
@@ -229,7 +229,7 @@ export async function mapGenerateConfigToRenderConfig(
   config: GenerateConfig,
   identityProviders: IdentityProviderRenderConfig[]
 ): Promise<AgentRenderConfig> {
-  const gatewayProviders = await mapMcpGatewaysToGatewayProviders();
+  const gatewayProviders = await mapGatewaysToGatewayProviders();
 
   return {
     name: config.projectName,

src/cli/primitives/GatewayTargetPrimitive.ts

@@ -236,7 +236,7 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
       .description('Add a gateway target to the project')
       .option('--name <name>', 'Target name')
       .option('--description <desc>', 'Target description')
-      .option('--type <type>', 'Target type (required): mcp-server')
+      .option('--type <type>', 'Target type (required): mcp-server, api-gateway')
       .option('--endpoint <url>', 'MCP server endpoint URL')
       .option('--language <lang>', 'Language: Python, TypeScript, Other')
       .option('--gateway <name>', 'Gateway name')
@@ -247,6 +247,10 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
       .option('--oauth-client-secret <secret>', 'OAuth client secret (creates credential inline)')
       .option('--oauth-discovery-url <url>', 'OAuth discovery URL (creates credential inline)')
       .option('--oauth-scopes <scopes>', 'OAuth scopes, comma-separated')
+      .option('--rest-api-id <id>', 'API Gateway REST API ID (required for api-gateway type)')
+      .option('--stage <stage>', 'API Gateway deployment stage (required for api-gateway type)')
+      .option('--tool-filter-path <path>', 'Tool filter path pattern, e.g. /pets/*')
+      .option('--tool-filter-methods <methods>', 'Comma-separated HTTP methods, e.g. GET,POST')
       .option('--json', 'Output as JSON')
       .action(async (rawOptions: Record<string, string | boolean | undefined>) => {
         const cliOptions = rawOptions as unknown as CLIAddGatewayTargetOptions;
@@ -273,6 +277,42 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
             none: 'NONE',
           };
 
+          // Handle API Gateway targets (no code generation)
+          if (cliOptions.type === 'apiGateway') {
+            const config: AddGatewayTargetConfig = {
+              name: cliOptions.name!,
+              description: cliOptions.description ?? `API Gateway target for ${cliOptions.name!}`,
+              sourcePath: '',
+              language: 'Other',
+              host: 'AgentCoreRuntime',
+              targetType: 'apiGateway',
+              toolDefinition: {
+                name: cliOptions.name!,
+                description: cliOptions.description ?? `API Gateway target for ${cliOptions.name!}`,
+                inputSchema: { type: 'object' },
+              },
+              gateway: cliOptions.gateway,
+              restApiId: cliOptions.restApiId,
+              stage: cliOptions.stage,
+              toolFilters: cliOptions.toolFilterPath
+                ? [
+                    {
+                      filterPath: cliOptions.toolFilterPath,
+                      methods: cliOptions.toolFilterMethods?.split(',').map(m => m.trim()) ?? ['GET'],
+                    },
+                  ]
+                : undefined,
+            };
+            const result = await this.createApiGatewayTarget(config);
+            const output = { success: true, toolName: result.toolName };
+            if (cliOptions.json) {
+              console.log(JSON.stringify(output));
+            } else {
+              console.log(`Added gateway target '${result.toolName}'`);
+            }
+            process.exit(0);
+          }
+
           // Handle MCP server targets (existing endpoint, no code generation)
           if (cliOptions.type === 'mcpServer' && cliOptions.endpoint) {
             const config: AddGatewayTargetConfig = {
@@ -450,6 +490,59 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
     return { toolName: config.name, projectPath: '' };
   }
 
+  /**
+   * Create an API Gateway target that connects to an existing Amazon API Gateway REST API.
+   * Unlike `add()` which scaffolds new code, this registers an existing REST API.
+   */
+  async createApiGatewayTarget(config: AddGatewayTargetConfig): Promise<{ toolName: string }> {
+    if (!config.restApiId) {
+      throw new Error('REST API ID is required for API Gateway targets.');
+    }
+    if (!config.stage) {
+      throw new Error('Stage is required for API Gateway targets.');
+    }
+    if (!config.gateway) {
+      throw new Error('Gateway name is required.');
+    }
+
+    const mcpSpec: AgentCoreMcpSpec = this.configIO.configExists('mcp')
+      ? await this.configIO.readMcpSpec()
+      : { agentCoreGateways: [] };
+
+    const gateway = mcpSpec.agentCoreGateways.find(g => g.name === config.gateway);
+    if (!gateway) {
+      throw new Error(`Gateway "${config.gateway}" not found.`);
+    }
+
+    if (!gateway.targets) {
+      gateway.targets = [];
+    }
+
+    if (gateway.targets.some(t => t.name === config.name)) {
+      throw new Error(`Target "${config.name}" already exists in gateway "${gateway.name}".`);
+    }
+
+    const target: AgentCoreGatewayTarget = {
+      name: config.name,
+      targetType: 'apiGateway',
+      apiGateway: {
+        restApiId: config.restApiId,
+        stage: config.stage,
+        apiGatewayToolConfiguration: {
+          toolFilters: (config.toolFilters ?? [{ filterPath: '/*', methods: ['GET'] }]) as {
+            filterPath: string;
+            methods: ('GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS')[];
+          }[],
+        },
+      },
+    };
+
+    gateway.targets.push(target);
+    await this.configIO.writeMcpSpec(mcpSpec);
+
+    return { toolName: config.name };
+  }
+
   // ═══════════════════════════════════════════════════════════════════
   // Private helpers
   // ═══════════════════════════════════════════════════════════════════

src/cli/tui/screens/mcp/types.ts

@@ -85,6 +85,9 @@ export interface AddGatewayTargetConfig {
     credentialName?: string;
     scopes?: string[];
   };
+  restApiId?: string;
+  stage?: string;
+  toolFilters?: { filterPath: string; methods: string[] }[];
 }
 
 export const MCP_TOOL_STEP_LABELS: Record<AddGatewayTargetStep, string> = {