Skip to content

Commit 433daef

Browse files
aidandaly24aidandaly24
committed
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
1 parent 32064ee commit 433daef

3 files changed

Lines changed: 149 additions & 27 deletions

File tree

‎docs/commands.md‎

Lines changed: 65 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -188,21 +188,21 @@ agentcore add gateway \
188188

189189
### add gateway-target
190190

191-
Add a gateway target to the project. Targets are backend tools exposed through a gateway as an external MCP server
192-
endpoint.
191+
Add a gateway target to the project. Targets are backend tools exposed through a gateway. Supports five target types:
192+
`mcp-server`, `api-gateway`, `open-api-schema`, `smithy-model`, and `lambda-function-arn`.
193193

194194
```bash
195195
# Interactive mode (select 'Gateway Target' from the menu)
196196
agentcore add
197197

198-
# External MCP server endpoint
198+
# MCP Server endpoint
199199
agentcore add gateway-target \
200200
--name WeatherTools \
201201
--type mcp-server \
202202
--endpoint https://mcp.example.com/mcp \
203203
--gateway MyGateway
204204

205-
# External endpoint with OAuth outbound auth
205+
# MCP Server with OAuth outbound auth
206206
agentcore add gateway-target \
207207
--name SecureTools \
208208
--type mcp-server \
@@ -212,22 +212,69 @@ agentcore add gateway-target \
212212
--oauth-client-id my-client \
213213
--oauth-client-secret my-secret \
214214
--oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
215+
216+
# API Gateway REST API
217+
agentcore add gateway-target \
218+
--name PetStore \
219+
--type api-gateway \
220+
--rest-api-id abc123 \
221+
--stage prod \
222+
--tool-filter-path '/pets/*' \
223+
--tool-filter-methods GET,POST \
224+
--gateway MyGateway
225+
226+
# OpenAPI Schema (auto-derive tools from spec)
227+
agentcore add gateway-target \
228+
--name PetStoreAPI \
229+
--type open-api-schema \
230+
--schema specs/petstore.json \
231+
--gateway MyGateway \
232+
--outbound-auth oauth \
233+
--credential-name MyOAuth
234+
235+
# Smithy Model (auto-derive tools from model)
236+
agentcore add gateway-target \
237+
--name MyService \
238+
--type smithy-model \
239+
--schema models/service.json \
240+
--gateway MyGateway
241+
242+
# Lambda Function ARN
243+
agentcore add gateway-target \
244+
--name MyLambdaTools \
245+
--type lambda-function-arn \
246+
--lambda-arn arn:aws:lambda:us-east-1:123456789012:function:my-func \
247+
--tool-schema-file tools.json \
248+
--gateway MyGateway
215249
```
216250

217-
| Flag | Description |
218-
| -------------------------------- | ----------------------------------------------- |
219-
| `--name <name>` | Target name |
220-
| `--description <desc>` | Target description |
221-
| `--type <type>` | Target type (required): `mcp-server` |
222-
| `--endpoint <url>` | MCP server endpoint URL |
223-
| `--gateway <name>` | Gateway to attach target to |
224-
| `--outbound-auth <type>` | `oauth`, `api-key`, or `none` |
225-
| `--credential-name <name>` | Existing credential name for outbound auth |
226-
| `--oauth-client-id <id>` | OAuth client ID (creates credential inline) |
227-
| `--oauth-client-secret <secret>` | OAuth client secret (creates credential inline) |
228-
| `--oauth-discovery-url <url>` | OAuth discovery URL (creates credential inline) |
229-
| `--oauth-scopes <scopes>` | OAuth scopes, comma-separated |
230-
| `--json` | JSON output |
251+
| Flag | Description |
252+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
253+
| `--name <name>` | Target name |
254+
| `--description <desc>` | Target description |
255+
| `--type <type>` | Target type (required): `mcp-server`, `api-gateway`, `open-api-schema`, `smithy-model`, `lambda-function-arn` |
256+
| `--endpoint <url>` | MCP server endpoint URL (mcp-server) |
257+
| `--language <lang>` | Language hint for MCP server (mcp-server) |
258+
| `--host <host>` | Host header override (mcp-server) |
259+
| `--gateway <name>` | Gateway to attach target to |
260+
| `--outbound-auth <type>` | `oauth`, `api-key`, or `none` (mcp-server, api-gateway, open-api-schema) |
261+
| `--credential-name <name>` | Existing credential name for outbound auth |
262+
| `--oauth-client-id <id>` | OAuth client ID (creates credential inline) |
263+
| `--oauth-client-secret <secret>` | OAuth client secret (creates credential inline) |
264+
| `--oauth-discovery-url <url>` | OAuth discovery URL (creates credential inline) |
265+
| `--oauth-scopes <scopes>` | OAuth scopes, comma-separated |
266+
| `--rest-api-id <id>` | API Gateway REST API ID (api-gateway) |
267+
| `--stage <stage>` | API Gateway stage name (api-gateway) |
268+
| `--tool-filter-path <path>` | Filter API paths, supports wildcards (api-gateway) |
269+
| `--tool-filter-methods <methods>` | Comma-separated HTTP methods to expose (api-gateway) |
270+
| `--schema <path>` | Path to schema file, relative to project root (open-api-schema, smithy-model) |
271+
| `--schema-s3-account <account>` | AWS account for S3-hosted schema (open-api-schema, smithy-model) |
272+
| `--lambda-arn <arn>` | Lambda function ARN (lambda-function-arn) |
273+
| `--tool-schema-file <path>` | Tool schema file, relative to project root or absolute path (lambda-function-arn) |
274+
| `--json` | JSON output |
275+
276+
> **Note**: `smithy-model` and `lambda-function-arn` use IAM role auth and do not support `--outbound-auth`.
277+
> `open-api-schema` requires `--outbound-auth` (`oauth` or `api-key`). `api-gateway` supports `api-key` or `none`.
231278
232279
### add identity
233280

‎docs/gateway.md‎

Lines changed: 80 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,13 @@ The generated agent code includes gateway client setup, authentication, and envi
3434

3535
## Gateway Targets
3636

37-
A gateway target is a backend tool exposed through a gateway — an external MCP server endpoint that the gateway proxies
38-
requests to.
37+
A gateway target is a backend tool source exposed through a gateway. The gateway proxies requests to the target and
38+
handles tool discovery and authentication. There are five target types.
39+
40+
### MCP Server (`mcp-server`)
41+
42+
Connect to an external MCP server endpoint, or deploy a managed MCP server on Lambda/AgentCoreRuntime
43+
(Python/TypeScript).
3944

4045
```bash
4146
agentcore add gateway-target \
@@ -45,6 +50,72 @@ agentcore add gateway-target \
4550
--gateway my-gateway
4651
```
4752

53+
Supports outbound auth: `oauth`, `api-key`, or `none`.
54+
55+
### API Gateway REST API (`api-gateway`)
56+
57+
Connect to an existing Amazon API Gateway REST API. The gateway auto-discovers tools from API routes.
58+
59+
```bash
60+
agentcore add gateway-target \
61+
--type api-gateway \
62+
--name PetStore \
63+
--rest-api-id abc123 \
64+
--stage prod \
65+
--tool-filter-path '/pets/*' \
66+
--tool-filter-methods GET,POST \
67+
--gateway my-gateway
68+
```
69+
70+
Supports outbound auth: `api-key` or `none`. OAuth is not supported for API Gateway targets.
71+
72+
### OpenAPI Schema (`open-api-schema`)
73+
74+
Auto-derive tools from an OpenAPI JSON specification file.
75+
76+
```bash
77+
agentcore add gateway-target \
78+
--type open-api-schema \
79+
--name PetStoreAPI \
80+
--schema specs/petstore.json \
81+
--gateway my-gateway \
82+
--outbound-auth oauth \
83+
--credential-name MyOAuth
84+
```
85+
86+
Outbound auth is required (`oauth` or `api-key`). Schema path is relative to project root.
87+
88+
### Smithy Model (`smithy-model`)
89+
90+
Auto-derive tools from a Smithy JSON model file.
91+
92+
```bash
93+
agentcore add gateway-target \
94+
--type smithy-model \
95+
--name MyService \
96+
--schema models/service.json \
97+
--gateway my-gateway
98+
```
99+
100+
Uses IAM role auth — no outbound auth needed. Schema path is relative to project root.
101+
102+
### Lambda Function ARN (`lambda-function-arn`)
103+
104+
Connect to an existing AWS Lambda function by ARN. Tools are defined via a JSON schema file rather than code
105+
scaffolding.
106+
107+
```bash
108+
agentcore add gateway-target \
109+
--type lambda-function-arn \
110+
--name MyLambdaTools \
111+
--lambda-arn arn:aws:lambda:us-east-1:123456789012:function:my-func \
112+
--tool-schema-file tools.json \
113+
--gateway my-gateway
114+
```
115+
116+
Uses IAM role auth exclusively — no outbound auth is allowed. The tool schema file path is relative to project root (or
117+
an absolute path) and is uploaded to S3 during deployment.
118+
48119
## Authentication
49120

50121
### Inbound Authentication
@@ -75,13 +146,14 @@ credential that your agent uses to obtain Bearer tokens at runtime.
75146

76147
### Outbound Authentication
77148

78-
Controls how the gateway authenticates with upstream MCP servers. Configured per target.
149+
Controls how the gateway authenticates with upstream targets. Configured per target.
79150

80-
| Type | Description |
81-
| --------- | ------------------------------ |
82-
| `none` | No outbound authentication |
83-
| `oauth` | OAuth2 client credentials flow |
84-
| `api-key` | API key passed to upstream |
151+
| Type | Description | Supported Target Types |
152+
| --------- | ------------------------------ | --------------------------------------------- |
153+
| `none` | No outbound authentication | mcp-server, api-gateway |
154+
| `oauth` | OAuth2 client credentials flow | mcp-server, open-api-schema |
155+
| `api-key` | API key passed to upstream | mcp-server, api-gateway, open-api-schema |
156+
| IAM role | Automatic IAM role auth | smithy-model, lambda-function-arn (exclusive) |
85157

86158
#### OAuth Outbound Auth
87159

‎src/cli/primitives/GatewayTargetPrimitive.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -243,7 +243,10 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
243243
.description('Add a gateway target to the project')
244244
.option('--name <name>', 'Target name')
245245
.option('--description <desc>', 'Target description')
246-
.option('--type <type>', 'Target type (required): mcp-server, api-gateway, lambda-function-arn')
246+
.option(
247+
'--type <type>',
248+
'Target type (required): mcp-server, api-gateway, open-api-schema, smithy-model, lambda-function-arn'
249+
)
247250
.option('--endpoint <url>', 'MCP server endpoint URL')
248251
.option('--language <lang>', 'Language: Python, TypeScript, Other')
249252
.option('--gateway <name>', 'Gateway name')

0 commit comments

Comments
 (0)