Skip to content

Commit ec41be7

Browse files
aidandaly24aidandaly24
authored
docs: add gateway documentation for commands, configuration, and local development (#474)
1 parent 3539236 commit ec41be7

5 files changed

Lines changed: 499 additions & 15 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@ Projects use JSON schema files in the `agentcore/` directory:
131131
- [CLI Commands Reference](docs/commands.md) - Full command reference for scripting and CI/CD
132132
- [Configuration](docs/configuration.md) - Schema reference for config files
133133
- [Frameworks](docs/frameworks.md) - Supported frameworks and model providers
134+
- [Gateway](docs/gateway.md) - Gateway setup, targets, and authentication
134135
- [Memory](docs/memory.md) - Memory strategies and sharing
135136
- [Local Development](docs/local-development.md) - Dev server and debugging
136137

‎docs/commands.md‎

Lines changed: 113 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -151,21 +151,114 @@ agentcore add memory \
151151
| `--expiry <days>` | Event expiry (default: 30) |
152152
| `--json` | JSON output |
153153

154+
### add gateway
155+
156+
Add a gateway to the project. Gateways act as MCP-compatible proxies that route agent requests to backend tools.
157+
158+
```bash
159+
# Interactive mode (select 'Gateway' from the menu)
160+
agentcore add
161+
162+
# No authorization (development/testing)
163+
agentcore add gateway --name MyGateway
164+
165+
# CUSTOM_JWT authorization (production)
166+
agentcore add gateway \
167+
--name MyGateway \
168+
--authorizer-type CUSTOM_JWT \
169+
--discovery-url https://idp.example.com/.well-known/openid-configuration \
170+
--allowed-audience my-api \
171+
--allowed-clients my-client-id \
172+
--agent-client-id agent-client-id \
173+
--agent-client-secret agent-client-secret
174+
```
175+
176+
| Flag | Description |
177+
| -------------------------------- | ------------------------------------------------------------ |
178+
| `--name <name>` | Gateway name |
179+
| `--description <desc>` | Gateway description |
180+
| `--authorizer-type <type>` | `NONE` (default) or `CUSTOM_JWT` |
181+
| `--discovery-url <url>` | OIDC discovery URL (required for CUSTOM_JWT) |
182+
| `--allowed-audience <values>` | Comma-separated allowed audiences (required for CUSTOM_JWT) |
183+
| `--allowed-clients <values>` | Comma-separated allowed client IDs (required for CUSTOM_JWT) |
184+
| `--allowed-scopes <scopes>` | Comma-separated allowed scopes (optional for CUSTOM_JWT) |
185+
| `--agent-client-id <id>` | Agent OAuth client ID for Bearer token auth (CUSTOM_JWT) |
186+
| `--agent-client-secret <secret>` | Agent OAuth client secret (CUSTOM_JWT) |
187+
| `--json` | JSON output |
188+
189+
### add gateway-target
190+
191+
Add a gateway target to the project. Targets are backend tools exposed through a gateway as an external MCP server
192+
endpoint.
193+
194+
```bash
195+
# Interactive mode (select 'Gateway Target' from the menu)
196+
agentcore add
197+
198+
# External MCP server endpoint
199+
agentcore add gateway-target \
200+
--name WeatherTools \
201+
--source existing-endpoint \
202+
--endpoint https://mcp.example.com/mcp \
203+
--gateway MyGateway
204+
205+
# External endpoint with OAuth outbound auth
206+
agentcore add gateway-target \
207+
--name SecureTools \
208+
--source existing-endpoint \
209+
--endpoint https://api.example.com/mcp \
210+
--gateway MyGateway \
211+
--outbound-auth oauth \
212+
--oauth-client-id my-client \
213+
--oauth-client-secret my-secret \
214+
--oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
215+
```
216+
217+
| Flag | Description |
218+
| -------------------------------- | ----------------------------------------------- |
219+
| `--name <name>` | Target name |
220+
| `--description <desc>` | Target description |
221+
| `--source <source>` | `existing-endpoint` |
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 |
231+
154232
### add identity
155233

156-
Add a credential provider (API key). Credentials are top-level resources in the flat resource model.
234+
Add a credential to the project. Supports API key and OAuth credential types.
157235

158236
```bash
237+
# API key credential
159238
agentcore add identity \
160239
--name OpenAI \
161240
--api-key sk-...
241+
242+
# OAuth credential
243+
agentcore add identity \
244+
--name MyOAuthProvider \
245+
--type oauth \
246+
--discovery-url https://idp.example.com/.well-known/openid-configuration \
247+
--client-id my-client-id \
248+
--client-secret my-client-secret \
249+
--scopes read,write
162250
```
163251

164-
| Flag | Description |
165-
| ----------------- | --------------- |
166-
| `--name <name>` | Credential name |
167-
| `--api-key <key>` | API key value |
168-
| `--json` | JSON output |
252+
| Flag | Description |
253+
| -------------------------- | -------------------------------- |
254+
| `--name <name>` | Credential name |
255+
| `--type <type>` | `api-key` (default) or `oauth` |
256+
| `--api-key <key>` | API key value (api-key type) |
257+
| `--discovery-url <url>` | OAuth discovery URL (oauth type) |
258+
| `--client-id <id>` | OAuth client ID (oauth type) |
259+
| `--client-secret <secret>` | OAuth client secret (oauth type) |
260+
| `--scopes <scopes>` | OAuth scopes, comma-separated |
261+
| `--json` | JSON output |
169262

170263
### remove
171264

@@ -175,6 +268,8 @@ Remove resources from project.
175268
agentcore remove agent --name MyAgent --force
176269
agentcore remove memory --name SharedMemory
177270
agentcore remove identity --name OpenAI
271+
agentcore remove gateway --name MyGateway
272+
agentcore remove gateway-target --name WeatherTools
178273

179274
# Reset everything
180275
agentcore remove all --force
@@ -281,6 +376,18 @@ agentcore add memory --name SharedMemory --strategies SEMANTIC
281376
agentcore deploy -y
282377
```
283378

379+
### Gateway Setup
380+
381+
```bash
382+
agentcore add gateway --name MyGateway
383+
agentcore add gateway-target \
384+
--name WeatherTools \
385+
--source existing-endpoint \
386+
--endpoint https://mcp.example.com/mcp \
387+
--gateway MyGateway
388+
agentcore deploy -y
389+
```
390+
284391
### JSON Output for Automation
285392

286393
All commands with `--json` output structured data:

‎docs/configuration.md‎

Lines changed: 154 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ AgentCore projects use JSON configuration files in the `agentcore/` directory.
77
| File | Purpose |
88
| --------------------- | ------------------------------------------- |
99
| `agentcore.json` | Project, agents, memories, and credentials |
10+
| `mcp.json` | Gateways, gateway targets, and MCP tools |
1011
| `aws-targets.json` | Deployment targets |
1112
| `deployed-state.json` | Runtime state (auto-managed, do not edit) |
1213
| `.env.local` | API keys for local development (gitignored) |
@@ -43,6 +44,12 @@ Main project configuration using a **flat resource model**. Agents, memories, an
4344
{
4445
"type": "ApiKeyCredentialProvider",
4546
"name": "OpenAI"
47+
},
48+
{
49+
"type": "OAuthCredentialProvider",
50+
"name": "MyOAuthProvider",
51+
"discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
52+
"scopes": ["read", "write"]
4653
}
4754
]
4855
}
@@ -56,7 +63,9 @@ Main project configuration using a **flat resource model**. Agents, memories, an
5663
| `version` | Yes | Schema version (integer, currently `1`) |
5764
| `agents` | Yes | Array of agent specifications |
5865
| `memories` | Yes | Array of memory resources |
59-
| `credentials` | Yes | Array of credential providers |
66+
| `credentials` | Yes | Array of credential providers (API key or OAuth) |
67+
68+
> Gateway configuration is stored separately in `mcp.json`. See [mcp.json](#mcpjson) below.
6069
6170
---
6271

@@ -142,6 +151,8 @@ Strategy configuration:
142151

143152
## Credential Resource
144153

154+
### API Key Credential
155+
145156
```json
146157
{
147158
"type": "ApiKeyCredentialProvider",
@@ -154,8 +165,142 @@ Strategy configuration:
154165
| `type` | Yes | Always `"ApiKeyCredentialProvider"` |
155166
| `name` | Yes | Credential name (3-255 chars) |
156167

157-
The actual API key is stored in `.env.local` for local development and in AgentCore Identity service for deployed
158-
environments.
168+
### OAuth Credential
169+
170+
```json
171+
{
172+
"type": "OAuthCredentialProvider",
173+
"name": "MyOAuthProvider",
174+
"discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
175+
"scopes": ["read", "write"]
176+
}
177+
```
178+
179+
| Field | Required | Description |
180+
| -------------- | -------- | ------------------------------------------------------ |
181+
| `type` | Yes | Always `"OAuthCredentialProvider"` |
182+
| `name` | Yes | Credential name (3-255 chars) |
183+
| `discoveryUrl` | Yes | OIDC discovery URL (must be a valid URL) |
184+
| `scopes` | No | Array of OAuth scopes |
185+
| `vendor` | No | Credential provider vendor (default: `"CustomOauth2"`) |
186+
| `managed` | No | Whether auto-created by the CLI (do not edit) |
187+
| `usage` | No | `"inbound"` or `"outbound"` |
188+
189+
The actual secrets (API keys, client IDs, client secrets) are stored in `.env.local` for local development and in
190+
AgentCore Identity service for deployed environments.
191+
192+
---
193+
194+
## mcp.json
195+
196+
Gateway and MCP tool configuration. Gateways, their targets, and standalone MCP runtime tools are defined here.
197+
198+
```json
199+
{
200+
"agentCoreGateways": [
201+
{
202+
"name": "MyGateway",
203+
"description": "My gateway",
204+
"authorizerType": "NONE",
205+
"targets": [
206+
{
207+
"name": "WeatherTools",
208+
"targetType": "mcpServer",
209+
"endpoint": "https://mcp.example.com/mcp"
210+
}
211+
]
212+
}
213+
],
214+
"unassignedTargets": []
215+
}
216+
```
217+
218+
### Top-Level Fields
219+
220+
| Field | Required | Description |
221+
| ------------------- | -------- | ------------------------------------- |
222+
| `agentCoreGateways` | Yes | Array of gateway definitions |
223+
| `unassignedTargets` | No | Targets not yet assigned to a gateway |
224+
225+
### Gateway
226+
227+
| Field | Required | Description |
228+
| ------------------------- | -------- | ------------------------------------------------------------ |
229+
| `name` | Yes | Gateway name (alphanumeric, hyphens, 1-63 chars) |
230+
| `description` | No | Gateway description |
231+
| `targets` | Yes | Array of gateway targets |
232+
| `authorizerType` | No | `"NONE"` (default), `"AWS_IAM"`, or `"CUSTOM_JWT"` |
233+
| `authorizerConfiguration` | No | Required when `authorizerType` is `"CUSTOM_JWT"` (see below) |
234+
235+
### CUSTOM_JWT Authorizer Configuration
236+
237+
```json
238+
{
239+
"authorizerType": "CUSTOM_JWT",
240+
"authorizerConfiguration": {
241+
"customJwtAuthorizer": {
242+
"discoveryUrl": "https://idp.example.com/.well-known/openid-configuration",
243+
"allowedAudience": ["my-api"],
244+
"allowedClients": ["my-client-id"],
245+
"allowedScopes": ["read", "write"]
246+
}
247+
}
248+
}
249+
```
250+
251+
| Field | Required | Description |
252+
| ----------------- | -------- | ---------------------------------------------------------------------- |
253+
| `discoveryUrl` | Yes | OIDC discovery URL (must end with `/.well-known/openid-configuration`) |
254+
| `allowedAudience` | Yes | Array of allowed audience values |
255+
| `allowedClients` | Yes | Array of allowed client IDs (at least 1) |
256+
| `allowedScopes` | No | Array of allowed scopes |
257+
258+
### Gateway Target
259+
260+
A target is a backend tool exposed through a gateway. Targets can be external MCP server endpoints or compute-backed
261+
implementations.
262+
263+
**External MCP server endpoint:**
264+
265+
```json
266+
{
267+
"name": "WeatherTools",
268+
"targetType": "mcpServer",
269+
"endpoint": "https://mcp.example.com/mcp"
270+
}
271+
```
272+
273+
**External endpoint with outbound auth:**
274+
275+
```json
276+
{
277+
"name": "SecureTools",
278+
"targetType": "mcpServer",
279+
"endpoint": "https://api.example.com/mcp",
280+
"outboundAuth": {
281+
"type": "OAUTH",
282+
"credentialName": "MyOAuthProvider",
283+
"scopes": ["tools:read"]
284+
}
285+
}
286+
```
287+
288+
| Field | Required | Description |
289+
| ----------------- | -------- | -------------------------------------------------------------------- |
290+
| `name` | Yes | Target name |
291+
| `targetType` | Yes | `"mcpServer"` or `"lambda"` |
292+
| `endpoint` | Cond. | MCP server URL (required for external `mcpServer` targets) |
293+
| `compute` | Cond. | Compute configuration (required for `lambda` and scaffolded targets) |
294+
| `toolDefinitions` | Cond. | Array of tool definitions (required for `lambda` targets) |
295+
| `outboundAuth` | No | Outbound authentication configuration |
296+
297+
### Outbound Auth
298+
299+
| Field | Required | Description |
300+
| ---------------- | -------- | ---------------------------------------------------- |
301+
| `type` | Yes | `"OAUTH"`, `"API_KEY"`, or `"NONE"` (default) |
302+
| `credentialName` | Cond. | Credential name (required when type is not `"NONE"`) |
303+
| `scopes` | No | OAuth scopes (for `"OAUTH"` type) |
159304

160305
---
161306

@@ -190,12 +335,17 @@ current list.
190335

191336
## .env.local
192337

193-
API keys for local development. This file is gitignored.
338+
Secrets for local development. This file is gitignored.
194339

195340
```bash
341+
# API key credentials
196342
AGENTCORE_CREDENTIAL_{projectName}OPENAI=sk-...
197343
AGENTCORE_CREDENTIAL_{projectName}ANTHROPIC=sk-ant-...
198344
AGENTCORE_CREDENTIAL_{projectName}GEMINI=...
345+
346+
# OAuth credentials
347+
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_ID=my-client-id
348+
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_SECRET=my-client-secret
199349
```
200350

201351
Environment variable names should match the credential names in your configuration.

0 commit comments

Comments
 (0)