From 5f5b3407e90cbe52b2361edc934aa9d3c4349e64 Mon Sep 17 00:00:00 2001 From: Aidan Daly Date: Mon, 9 Mar 2026 16:41:14 -0400 Subject: [PATCH] docs: update help text and docs for all gateway target types - Fix --type help to list all 5 types: mcp-server, api-gateway, open-api-schema, smithy-model, lambda-function-arn - Update commands.md: add examples and flags for all target types - Update gateway.md: add subsections for each target type with auth notes --- docs/commands.md | 84 +++++++++++++++---- docs/gateway.md | 88 ++++++++++++++++++-- src/cli/primitives/GatewayTargetPrimitive.ts | 5 +- 3 files changed, 150 insertions(+), 27 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 4f9816ba9..73c03d445 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -188,21 +188,21 @@ agentcore add gateway \ ### add gateway-target -Add a gateway target to the project. Targets are backend tools exposed through a gateway as an external MCP server -endpoint. +Add a gateway target to the project. Targets are backend tools exposed through a gateway. Supports five target types: +`mcp-server`, `api-gateway`, `open-api-schema`, `smithy-model`, and `lambda-function-arn`. ```bash # Interactive mode (select 'Gateway Target' from the menu) agentcore add -# External MCP server endpoint +# MCP Server endpoint agentcore add gateway-target \ --name WeatherTools \ --type mcp-server \ --endpoint https://mcp.example.com/mcp \ --gateway MyGateway -# External endpoint with OAuth outbound auth +# MCP Server with OAuth outbound auth agentcore add gateway-target \ --name SecureTools \ --type mcp-server \ @@ -212,22 +212,70 @@ agentcore add gateway-target \ --oauth-client-id my-client \ --oauth-client-secret my-secret \ --oauth-discovery-url https://auth.example.com/.well-known/openid-configuration + +# API Gateway REST API +agentcore add gateway-target \ + --name PetStore \ + --type api-gateway \ + --rest-api-id abc123 \ + --stage prod \ + --tool-filter-path '/pets/*' \ + --tool-filter-methods GET,POST \ + --gateway MyGateway + +# OpenAPI Schema (auto-derive tools from spec) +agentcore add gateway-target \ + --name PetStoreAPI \ + --type open-api-schema \ + --schema specs/petstore.json \ + --gateway MyGateway \ + --outbound-auth oauth \ + --credential-name MyOAuth + +# Smithy Model (auto-derive tools from model) +agentcore add gateway-target \ + --name MyService \ + --type smithy-model \ + --schema models/service.json \ + --gateway MyGateway + +# Lambda Function ARN +agentcore add gateway-target \ + --name MyLambdaTools \ + --type lambda-function-arn \ + --lambda-arn arn:aws:lambda:us-east-1:123456789012:function:my-func \ + --tool-schema-file tools.json \ + --gateway MyGateway ``` -| Flag | Description | -| -------------------------------- | ----------------------------------------------- | -| `--name ` | Target name | -| `--description ` | Target description | -| `--type ` | Target type (required): `mcp-server` | -| `--endpoint ` | MCP server endpoint URL | -| `--gateway ` | Gateway to attach target to | -| `--outbound-auth ` | `oauth`, `api-key`, or `none` | -| `--credential-name ` | Existing credential name for outbound auth | -| `--oauth-client-id ` | OAuth client ID (creates credential inline) | -| `--oauth-client-secret ` | OAuth client secret (creates credential inline) | -| `--oauth-discovery-url ` | OAuth discovery URL (creates credential inline) | -| `--oauth-scopes ` | OAuth scopes, comma-separated | -| `--json` | JSON output | +| Flag | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `--name ` | Target name | +| `--description ` | Target description | +| `--type ` | Target type (required): `mcp-server`, `api-gateway`, `open-api-schema`, `smithy-model`, `lambda-function-arn` | +| `--endpoint ` | MCP server endpoint URL (mcp-server) | +| `--language ` | Implementation language: Python, TypeScript, Other (mcp-server) | +| `--host ` | Compute host: Lambda or AgentCoreRuntime (mcp-server) | +| `--gateway ` | Gateway to attach target to | +| `--outbound-auth ` | `oauth`, `api-key`, or `none` (varies by target type) | +| `--credential-name ` | Existing credential name for outbound auth | +| `--oauth-client-id ` | OAuth client ID (creates credential inline) | +| `--oauth-client-secret ` | OAuth client secret (creates credential inline) | +| `--oauth-discovery-url ` | OAuth discovery URL (creates credential inline) | +| `--oauth-scopes ` | OAuth scopes, comma-separated | +| `--rest-api-id ` | API Gateway REST API ID (api-gateway) | +| `--stage ` | API Gateway stage name (api-gateway) | +| `--tool-filter-path ` | Filter API paths, supports wildcards (api-gateway) | +| `--tool-filter-methods ` | Comma-separated HTTP methods to expose (api-gateway) | +| `--schema ` | Path to schema file, relative to project root (open-api-schema, smithy-model) | +| `--schema-s3-account ` | AWS account for S3-hosted schema (open-api-schema, smithy-model) | +| `--lambda-arn ` | Lambda function ARN (lambda-function-arn) | +| `--tool-schema-file ` | Tool schema file, relative to project root or absolute path (lambda-function-arn) | +| `--json` | JSON output | + +> **Note**: `smithy-model` and `lambda-function-arn` use IAM role auth and do not support `--outbound-auth`. +> `open-api-schema` requires `--outbound-auth` (`oauth` or `api-key`). `api-gateway` supports `api-key` or `none`. +> `mcp-server` supports `oauth` or `none`. ### add identity diff --git a/docs/gateway.md b/docs/gateway.md index 4f47e72a4..a8477c5f2 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -34,8 +34,13 @@ The generated agent code includes gateway client setup, authentication, and envi ## Gateway Targets -A gateway target is a backend tool exposed through a gateway — an external MCP server endpoint that the gateway proxies -requests to. +A gateway target is a backend tool source exposed through a gateway. The gateway proxies requests to the target and +handles tool discovery and authentication. There are five target types. + +### MCP Server (`mcp-server`) + +Connect to an external MCP server endpoint, or deploy a managed MCP server on Lambda/AgentCoreRuntime +(Python/TypeScript). ```bash agentcore add gateway-target \ @@ -45,6 +50,72 @@ agentcore add gateway-target \ --gateway my-gateway ``` +Supports outbound auth: `oauth`, `api-key`, or `none`. + +### API Gateway REST API (`api-gateway`) + +Connect to an existing Amazon API Gateway REST API. The gateway auto-discovers tools from API routes. + +```bash +agentcore add gateway-target \ + --type api-gateway \ + --name PetStore \ + --rest-api-id abc123 \ + --stage prod \ + --tool-filter-path '/pets/*' \ + --tool-filter-methods GET,POST \ + --gateway my-gateway +``` + +Supports outbound auth: `api-key` or `none`. OAuth is not supported for API Gateway targets. + +### OpenAPI Schema (`open-api-schema`) + +Auto-derive tools from an OpenAPI JSON specification file. + +```bash +agentcore add gateway-target \ + --type open-api-schema \ + --name PetStoreAPI \ + --schema specs/petstore.json \ + --gateway my-gateway \ + --outbound-auth oauth \ + --credential-name MyOAuth +``` + +Outbound auth is required (`oauth` or `api-key`). Schema path is relative to project root. + +### Smithy Model (`smithy-model`) + +Auto-derive tools from a Smithy JSON model file. + +```bash +agentcore add gateway-target \ + --type smithy-model \ + --name MyService \ + --schema models/service.json \ + --gateway my-gateway +``` + +Uses IAM role auth — no outbound auth needed. Schema path is relative to project root. + +### Lambda Function ARN (`lambda-function-arn`) + +Connect to an existing AWS Lambda function by ARN. Tools are defined via a JSON schema file rather than code +scaffolding. + +```bash +agentcore add gateway-target \ + --type lambda-function-arn \ + --name MyLambdaTools \ + --lambda-arn arn:aws:lambda:us-east-1:123456789012:function:my-func \ + --tool-schema-file tools.json \ + --gateway my-gateway +``` + +Uses IAM role auth exclusively — no outbound auth is allowed. The tool schema file path is relative to project root (or +an absolute path) and is uploaded to S3 during deployment. + ## Authentication ### Inbound Authentication @@ -75,13 +146,14 @@ credential that your agent uses to obtain Bearer tokens at runtime. ### Outbound Authentication -Controls how the gateway authenticates with upstream MCP servers. Configured per target. +Controls how the gateway authenticates with upstream targets. Configured per target. -| Type | Description | -| --------- | ------------------------------ | -| `none` | No outbound authentication | -| `oauth` | OAuth2 client credentials flow | -| `api-key` | API key passed to upstream | +| Type | Description | Supported Target Types | +| --------- | ------------------------------ | --------------------------------------------- | +| `none` | No outbound authentication | mcp-server, api-gateway | +| `oauth` | OAuth2 client credentials flow | mcp-server, open-api-schema | +| `api-key` | API key passed to upstream | api-gateway, open-api-schema | +| IAM role | Automatic IAM role auth | smithy-model, lambda-function-arn (exclusive) | #### OAuth Outbound Auth diff --git a/src/cli/primitives/GatewayTargetPrimitive.ts b/src/cli/primitives/GatewayTargetPrimitive.ts index c3857a386..7f2349aaf 100644 --- a/src/cli/primitives/GatewayTargetPrimitive.ts +++ b/src/cli/primitives/GatewayTargetPrimitive.ts @@ -243,7 +243,10 @@ export class GatewayTargetPrimitive extends BasePrimitive', 'Target name') .option('--description ', 'Target description') - .option('--type ', 'Target type (required): mcp-server, api-gateway, lambda-function-arn') + .option( + '--type ', + 'Target type (required): mcp-server, api-gateway, open-api-schema, smithy-model, lambda-function-arn' + ) .option('--endpoint ', 'MCP server endpoint URL') .option('--language ', 'Language: Python, TypeScript, Other') .option('--gateway ', 'Gateway name')