AgentCore Gateway, one URL.

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.

01One 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.

02The six target types

Targets are configured under targetConfiguration.mcp, with one sub-key per target type. From the Define the gateway target configuration page:

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.

03Inbound: 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 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.

04MCP 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 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.

05MCP 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 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 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:

From the semantic-search reference

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.

06Limits worth knowing

From the official quotas page:

• 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.

07Try it in five minutes

The CLI path from zero to a working Gateway with a Lambda target:

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.