--- title: "AgentCore Gateway — every REST API, Lambda, and MCP server becomes one MCP endpoint" date: 2026-05-30 service: "Amazon Bedrock AgentCore" component: "Gateway" tags: [agentcore, gateway, mcp, targets, lambda, api-gateway, openapi, smithy, http-runtime, mcp-server, semantic-search, sigv4, oauth2, listing-mode] source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building.html verified_on: 2026-05-30 url: https://vanemmerik.ai/aws-ai/2026-05-30.html --- # AWS Bedrock & AgentCore · Tip of the Day · 2026-05-30 ## AgentCore Gateway — every REST API, Lambda, and MCP server becomes one MCP endpoint Yesterday we covered AgentCore Identity — how the agent proves *who it is* and gets *outbound credentials* on demand. Today we plug the other end of that pipe in. AgentCore Gateway is the **unified connectivity layer** that takes a Lambda, an API Gateway REST stage, an OpenAPI spec, a Smithy model, an HTTP runtime, or an external MCP server, and exposes the whole collection as **one MCP server URL** your agent can speak to. agentcore add gateway-target \ --name MyLambdaTarget \ --type lambda-function-arn \ --lambda-arn arn:aws:lambda:us-east-1:111122223333:function:MyFunction \ --tool-schema-file tools.json \ --gateway MyGateway agentcore deploy ≈ 9 min read · Bedrock AgentCore · Gateway --- ## 01 · One URL, every tool From the docs: *"Amazon Bedrock AgentCore Gateway provides a unified connectivity layer between agents and the tools and resources they need to interact with."* The shape is opinionated: - You create a **Gateway endpoint** — an MCP server hosted by AWS. - You attach one or more **targets**. Each target is a backend (Lambda, REST API, OpenAPI spec, Smithy model, HTTP runtime, or MCP server) plus the schema describing its tools. - The Gateway exposes everything under a single URL of the form `https://{gateway-Id}.gateway.bedrock-agentcore.{Region}.amazonaws.com/mcp`. - Your agent connects with any MCP client (the Strands client, the reference `mcp` Python package, anything that speaks streamable HTTP MCP) and discovers all tools across all targets in one `tools/list` call. > **The shift.** You stop running a tool router. The "this prompt > wants the inventory API, this one wants the Slack API" decision > isn't your problem — Gateway publishes them all to MCP, and your > agent (or the model) picks. The Gateway also does inbound JWT > validation, outbound credential vending, semantic tool search, > and pagination for the tool list, so the surface your code talks > to stays small. --- ## 02 · The six target types Targets are configured under `targetConfiguration.mcp`, with one sub-key per target type. From the [Define the gateway target configuration](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-api-target-config.html) page: | Target type | What it adapts | How tools are defined | | --- | --- | --- | | **Lambda** | An AWS Lambda function ARN. The Gateway invokes the function for each tool call and passes the MCP arguments. | Inline `toolSchema` with `inlinePayload` describing one tool per logical operation. | | **API Gateway stage** | A REST API stage by `restApiId` + `stage`. Path-level `toolFilters` decide which methods are exposed; `toolOverrides` rename and re-describe them. | Derived from the API definition; refined with filters and overrides. | | **OpenAPI** | An OpenAPI 3 spec, either inline (≤ 1 MB) or referenced from S3 (≤ 10 MB). | Every operation in the spec becomes a tool. | | **Smithy** | A Smithy model — the same schema language AWS SDKs are generated from. | Each Smithy operation becomes a tool. | | **HTTP runtime** | An arbitrary HTTP endpoint that doesn't fit the above. | Provided as a tool schema in the target payload. | | **MCP server** | An *external* MCP server you already run, brought under the Gateway's roof. | The Gateway speaks MCP to it on your behalf. | Every non-MCP target needs **outbound auth** — how the Gateway should call the backend. The options on `credentialProviderConfigurations` are: - `GATEWAY_IAM_ROLE` — sign with SigV4 using the Gateway's execution role. The default for Lambda and API Gateway stages. - `API_KEY` — pluck a key from an AgentCore Identity API-key provider and add it as a header. - `OAUTH` — vend a token from a 2LO or 3LO OAuth2 provider that Identity already manages. That's why Identity matters so much for Gateway: the Gateway never holds secrets. It asks Identity for whatever the target wants. --- ## 03 · Inbound: who can call this gateway Inbound auth is set on the gateway itself, not on individual targets, and the docs enumerate four shapes via the [Create an AgentCore gateway using the API](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-create-api.html) page: - **Custom JWT** — point at one or more OIDC issuers, the Gateway validates the inbound bearer token, extracts `iss` and `sub`, and forwards a workload access token to your tool handler. - **IAM** — clients sign with SigV4. Use this for service-to-service callers inside AWS. - **AUTHENTICATE_ONLY** — validates the token but skips the authorization step. Useful when downstream Cedar policies do the authorization instead. - **NONE** — no inbound auth. The docs flag this as not recommended. --- ## 04 · MCP server targets and the listing-mode trap External MCP server targets are the newest target type and the one with the most footguns. Two facts from the [MCP servers targets](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-MCPservers.html) page that surprise people: - **ListingMode** can be `DEFAULT` or `DYNAMIC`. In `DEFAULT` mode, the Gateway calls `tools/list`, `prompts/list`, `resources/list`, and `resources/templates/list` on your MCP server at target-creation time and again whenever you call `SynchronizeGatewayTargets`. The Gateway then serves those cached capabilities to clients without round-tripping. In `DYNAMIC` mode, every client request is proxied through to the upstream MCP server. - **`DYNAMIC` mode is not interoperable with semantic search or outbound three-legged OAuth (3LO).** If you want either of those, you're on `DEFAULT` and you're responsible for calling `SynchronizeGatewayTargets` after your upstream server changes its toolset. Outbound auth for MCP targets adds two options on top of the non-MCP set: - **IAM SigV4** — only works if the MCP server is hosted behind a service that natively verifies SigV4. The docs list the exact set: *Amazon Bedrock AgentCore Gateway, Amazon Bedrock AgentCore Runtime, Amazon API Gateway, and Lambda Function URLs.* An ALB in front of EC2 won't work because ALB doesn't verify SigV4. - **OAuth — both 2LO and 3LO.** 3LO requires `DEFAULT` listing mode (see above) and goes through the Identity authorization code flow with the inbound user's workload access token as the binding. --- ## 05 · MCP wire and semantic search The Gateway speaks streamable-HTTP MCP. The Gateway versions of MCP currently supported are `2025-03-26`, `2025-06-18`, and `2025-11-25` — the latter being the spec version the Gateway is written against. The full operation list from the [Use an AgentCore gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-using.html) page is `tools/call`, `tools/list`, `prompts/list`, `prompts/get`, `resources/list`, `resources/read`, `resources/templates/list`, plus the server-initiated `elicitation/create`, `sampling/createMessage`, `notifications/progress`, and `notifications/message`. The interesting tool that only Gateway adds is **semantic search**. If you turn on `protocolConfiguration.mcp.searchType = SEMANTIC` at create time, the Gateway pre-computes vector embeddings for every tool's name and description and exposes a synthetic tool called `x_amz_bedrock_agentcore_search`. Your agent calls it like any other tool: POST /mcp HTTP/1.1 Host: ${GatewayEndpoint} Content-Type: application/json Authorization: Bearer ${access_token} { "jsonrpc": "2.0", "id": "search-request", "method": "tools/call", "params": { "name": "x_amz_bedrock_agentcore_search", "arguments": { "query": "find order information" } } } The response is a ranked list of tools relevant to the query — which is how you avoid stuffing 800 tools into a model's context window. Semantic search is bound by a **25 transactions per minute** account quota, so use it to narrow the list, then call `tools/list` or `tools/call` directly. --- ## 06 · Limits worth knowing From the [official quotas page](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/bedrock-agentcore-limits.html#gateway-endpoints-quotas): - **1,000 gateways per account per Region.** Adjustable. - **100 targets per gateway**, **1,000 tools per target.** Both adjustable, but plan ahead — the schema-size budget is the real constraint. - **1 MB inline schema, 10 MB S3-referenced schema** per target. If your OpenAPI spec is bigger than 1 MB, you must host it in S3. - **6 MB max payload** for `tools/call`, `tools/list`, or `tools/search`. Large file responses go through pre-signed S3 URLs, not the MCP envelope. - **Tool name ≤ 256 characters.** Tool names also have to be unique across all targets attached to one gateway, so prefix liberally. - **1,000 concurrent connections** per gateway *and* per account. Both adjustable. Concurrency, not RPS — long-lived MCP sessions count. - **15-minute invocation timeout.** Adjustable. SSE streams that go longer than 15 minutes idle out. - **5 concurrent target operations** (Create/Update/Delete) on the same gateway. Adjustable. Bulk schema rollouts need to be serialised. - **25 TPM for semantic tool-search.** Adjustable, but this is the one to plan around — agents that fan out per turn will hit it. Two non-quota gotchas from the docs: - **MCP-server-target `DYNAMIC` mode disables both semantic search and 3LO.** Pick listing mode at target creation deliberately. - **`SynchronizeGatewayTargets` is asynchronous.** It returns 202 immediately; you poll `GetGatewayTarget` until the synchronization status moves out of `IN_PROGRESS`. Large MCP server inventories can take minutes. --- ## 07 · Try it in five minutes The CLI path from zero to a working Gateway with a Lambda target: # 1. Create the gateway (Custom JWT inbound, semantic search on) agentcore create gateway \ --name MyGateway \ --authorizer-type jwt \ --discovery-url https://cognito-idp.us-east-1.amazonaws.com/$POOL_ID/.well-known/openid-configuration \ --allowed-clients $COGNITO_CLIENT_ID \ --search-type SEMANTIC agentcore deploy # 2. Add a Lambda target. tools.json is an MCP-style inlinePayload # with one entry per logical operation in your Lambda. cat > tools.json <<'JSON' [ { "name": "get_weather", "description": "Get the current weather for a US city.", "inputSchema": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } ] JSON agentcore add gateway-target \ --name WeatherLambda \ --type lambda-function-arn \ --lambda-arn $WEATHER_LAMBDA_ARN \ --tool-schema-file tools.json \ --gateway MyGateway agentcore deploy # 3. Connect any MCP client to the URL the CLI prints. python - <<'PY' import asyncio from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client URL = "https://.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp" TOKEN = "" async def main(): async with streamablehttp_client(URL, headers={"Authorization": f"Bearer {TOKEN}"}) as (r, w, _): async with ClientSession(r, w) as s: await s.initialize() print(await s.list_tools()) print(await s.call_tool("get_weather", {"city": "seattle"})) asyncio.run(main()) PY The first `list_tools` will show both `get_weather` and the synthetic `x_amz_bedrock_agentcore_search` (because we turned semantic search on). Add more targets — an OpenAPI spec, a Smithy model, an external MCP server — and they all surface in the same `tools/list` call. Your agent code doesn't change. Tomorrow we'll look at **AgentCore Observability** — CloudWatch Transaction Search, OTEL spans, and how the per-tool traces show up in the AgentCore inspector when the agent fans out across this exact Gateway. --- **Verified against the official AWS docs on 2026-05-30.** Sources: , , , , , , . If the docs change, this lesson is a snapshot of that day — check the sources for current behaviour. --- > **This page — research, writing, verification, and deployment — was built by > Claude Cowork.** No human touched the prose, the layout, or the upload > pipeline. The lesson was generated this morning, cross-checked against the > official AWS docs by an independent verification pass, and published > to Cloudflare R2 on a schedule. > > A daily experiment by Monty van Emmerik · — AWS Bedrock & AgentCore · Tip of the Day · No. 005 · vanemmerik.ai