Gateway Auth & Semantic Tool Search

A Gateway sits between agents and backends, and it has two independent authentication boundaries. Get them straight before touching config, because they are configured in different places and answer different questions:

• Inbound (ingress) auth answers "who is allowed to call this gateway's MCP endpoint?" It is set once per gateway as the gateway's authorizerType. The gateway is an MCP resource server — clients POST JSON-RPC over MCP Streamable HTTP to /mcp, and inbound auth gates that door.
• Outbound (egress) auth answers "how does the gateway present credentials to the backend behind a given target?" It is configured per target via AgentCore Identity (the credential provider + the gateway's IAM role), because each target may talk to a different system with a different trust model.

AWS describes Gateway as "the only solution that provides both comprehensive ingress and egress authentication in a fully-managed service." The practical consequence: a single tools/call from an agent crosses both boundaries — first the caller is authenticated against the gateway, then the gateway authenticates itself (or forwards the caller's identity) to the backend.

  Agent / MCP client                 Gateway (MCP resource server)              Backend
  ──────────────────   inbound auth   ─────────────────────────   outbound auth  ────────
  JWT | SigV4  ─────────────────────▶  authorizerType            ───────────────▶ Lambda /
                                       (one per gateway)           credentialProvider  OpenAPI /
                                                                   (per target)        MCP server / ...

Inbound auth is the gateway's authorizerType. There are four choices, set at create time:

With CUSTOM_JWT, the JWT authorizer is wired in at creation via authorizerConfiguration:

import boto3

client = boto3.client('bedrock-agentcore-control')
gw = client.create_gateway(
    name="orders-gateway",
    roleArn="arn:aws:iam::123456789012:role/orders-gateway-service-role",
    protocolType="MCP",
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration={"customJWTAuthorizer": {
        "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/<pool>/.well-known/openid-configuration",
        "allowedClients": ["clientId"]
    }})
print(gw['gatewayUrl'])
# https://{gateway-Id}.gateway.bedrock-agentcore.{Region}.amazonaws.com

The AgentCore CLI uses an --authorizer-type flag; NONE is the dev shortcut:

agentcore add gateway --name TestGateway --authorizer-type NONE --runtimes MyGatewayAgent

Outbound auth is brokered by AgentCore Identity and configured per target. The methods, roughly from least to most identity-aware:

• No auth — the backend is open (some targets only).
• Gateway service role / IAM SigV4 — the gateway calls the backend as itself using its IAM role. For MCP-server and OpenAPI targets you add an iamCredentialProvider specifying the service (e.g. bedrock-agentcore) and an optional region; Lambda, API Gateway, and Smithy targets use the basic GATEWAY_IAM_ROLE config. SigV4 outbound only works against AWS services that actually verify SigV4.
• Caller IAM (FAS) — the gateway forwards the caller's IAM identity via Forward Access Sessions. Only AgentCore Runtime (HTTP) targets support this.
• OAuth 2LO — client-credentials / machine-to-machine; the gateway authenticates as itself.
• OAuth 3LO — authorization-code; acts on behalf of a user who consents via an auth URL.
• OAuth OBO (token-exchange) — exchange the inbound user token for a scoped downstream token that carries both the user and the agent identity. Use this when the backend needs to know who the human is, but you don't want to forward the raw inbound token.
• Token passthrough — forward the inbound token unchanged. Requires AUTHENTICATE_ONLY inbound.
• API key — a static key injected at a configurable location (header or query) with an optional prefix.

A Lambda target with the gateway role looks like this (boto3 targetConfiguration shape):

client.create_gateway_target(
    gatewayIdentifier=gw['gatewayId'],
    name="orders",
    targetConfiguration={"mcp": {"lambda": {
        "lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:orders",
        "toolSchema": {"inlinePayload": [
            {"name": "get_order", "description": "Look up an order",
             "inputSchema": {"type": "object", "properties": {"id": {"type": "string"}}}}]}}}},
    credentialProviderConfigurations=[{"credentialProviderType": "GATEWAY_IAM_ROLE"}])

An OpenAPI or MCP-server target backed by API key references a credential provider instead — the AgentCore CLI exposes this as --outbound-auth:

agentcore add gateway-target --name MyOpenAPITarget --type open-api-schema \
  --schema path/to/openapi.json --outbound-auth none|api-key|oauth --gateway MyGateway

Not every target supports every outbound method. Memorize the shape of this matrix — picking an unsupported method is a silent misconfiguration that only surfaces at invocation:

Reading the matrix:

• Lambda is the simplest: gateway role only — no OAuth, no API key, no passthrough.
• MCP-server and OpenAPI are the most flexible: they support the full OAuth spread (2LO/3LO/OBO) plus API key.
• Caller IAM (FAS) and passthrough are exclusive to AgentCore Runtime HTTP targets.
• Smithy supports the gateway role and 2LO only.

The gateway service role needs explicit IAM for OAuth and API-key egress. AgentCore Identity calls the token vault on the gateway's behalf, so the role must allow:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:GetWorkloadAccessToken",
      "bedrock-agentcore:GetResourceOauth2Token",
      "secretsmanager:GetSecretValue"
    ],
    "Resource": "*"
  }]
}

For API-key targets, swap GetResourceOauth2Token for bedrock-agentcore:GetResourceApiKey. (Scope Resource down to your specific workload-identity and secret ARNs in production — * is shown only for clarity.)

A gateway can aggregate many targets, and each target can expose many tools. Push thousands of tool definitions into a model's context and two things break: the context window fills with schemas, and the model's tool-selection accuracy collapses. Semantic tool search fixes both by letting the agent search for relevant tools instead of seeing all of them.

You enable it by setting protocolConfiguration.mcp.searchType = "SEMANTIC" at gateway creation:

gw = client.create_gateway(
    name="big-tool-gateway",
    roleArn="arn:aws:iam::123456789012:role/gw-role",
    protocolType="MCP",
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration={"customJWTAuthorizer": {
        "discoveryUrl": "https://.../.well-known/openid-configuration",
        "allowedClients": ["clientId"]}},
    protocolConfiguration={"mcp": {"searchType": "SEMANTIC"}})   # enables semantic search

This adds a built-in tool named x_amz_bedrock_agentcore_search to the gateway's tool list. The agent calls it like any other MCP tool, passing a natural-language query, and gets back the matching tools (which it can then call):

{"jsonrpc": "2.0", "id": "search", "method": "tools/call",
 "params": {"name": "x_amz_bedrock_agentcore_search",
            "arguments": {"query": "find order information"}}}

Three hard constraints from the docs:

1. Creation-only. "You can't change its configuration to enable semantic search" after the fact — if a live gateway lacks it, you must recreate the gateway. There is no update path.
2. MCP targets only. Search uses vector embeddings over MCP (aggregated) targets. HTTP (proxied) targets are not searchable.
3. Sync is required. The creator needs the bedrock-agentcore:SynchronizeGatewayTargets permission so the search index reflects the current tool inventory; new/changed targets must be synchronized to appear in results.

The embedding model behind the search is not publicly documented, and the search rate limit is volatile (≈25 TPM as of writing) — treat both as implementation details to verify, not constants to design hard limits around.

Gateway has hard limits, and they move. Teach the dimension, verify the number — every figure below is [VOLATILE] and must be checked against the live AgentCore quotas page before you rely on it.

Remember the tool-naming rule when you size against the 256-char limit: gateway tools are namespaced by target with a triple underscore — ${target_name}___${tool_name} (e.g. LambdaUsingSDK___get_order_tool). The prefix counts toward the 256 characters, and your downstream Lambda receives the prefixed name — strip the ${target_name}___ prefix before dispatching.

Gotcha checklist:

• Trying to enable semantic search after creation — recreate the gateway instead.
• Token passthrough without AUTHENTICATE_ONLY inbound — it will be rejected.
• Picking an unsupported outbound method for a target type (see the matrix) — e.g. API key on a Lambda target.
• IAM/SigV4 outbound against a non-AWS backend — SigV4 outbound only works on AWS services that verify it.
• Forgetting the gateway-role IAM (GetWorkloadAccessToken, GetResourceOauth2Token/GetResourceApiKey, secretsmanager:GetSecretValue) for OAuth/API-key egress.
• Not stripping the ${target_name}___ prefix in your backend handler.