AgentCore Gateway: The M×N Tool Problem

An agent is only as useful as the tools it can reach. The moment you go past a single demo, you hit an integration explosion. You have M agents (a support bot, an ops agent, a sales assistant) and N backends (an internal orders API, a couple of Lambda functions, Salesforce, a Jira instance). Wired naively, every agent has to learn how to talk to every backend — its auth scheme, its request shape, its error semantics. That's M×N integrations, and each one is bespoke glue you write, secure, and maintain.

AgentCore Gateway collapses M×N to M+N. It is a fully managed service that converts APIs, Lambda functions, and existing services into MCP-compatible tools exposed to agents through a single Gateway endpoint — per the AWS docs, "with just a few lines of code." Each backend is registered with the Gateway once (the N side). Each agent connects to the one Gateway endpoint as a standard MCP client (the M side). Agents no longer know or care that one tool is a Lambda, another is an OpenAPI service, and a third is Salesforce — they all arrive as MCP tools over one connection.

The AWS write-up frames Gateway as "the only solution that provides both comprehensive ingress and egress authentication in a fully-managed service." That phrase encodes the two halves of the problem Gateway owns:

• Ingress (inbound) — who is allowed to call the Gateway? Authenticating and authorizing the agent or caller hitting the MCP endpoint.
• Egress (outbound) — how does the Gateway authenticate to each backend? Injecting the right credential per target without that secret ever touching your agent code or the model's context.

We go deep on both auth directions in a later lesson. For now, hold the shape: many backends in, one MCP endpoint out, with auth managed on both sides.

Gateway is more than a protocol shim. AWS breaks its job into six capabilities — read them as the list of plumbing you would otherwise hand-build per integration:

On top of these, Gateway ships "1-click" built-in integration templates for common SaaS backends: Salesforce, Slack, Jira, Asana, and Zendesk. These let you stand up a working tool target for those services without authoring a schema by hand.

Map the capabilities back to the M×N problem: Translation and Composition are the M+N collapse; Security Guard and Secure Credential Exchange are the ingress/egress auth halves; Semantic Tool Selection keeps a large catalog usable; Infrastructure Manager is the "fully managed, serverless" promise.

Everything you configure in Gateway is one of five resources. Pin these names down — the rest of the Gateway module builds on them.

• Gateway — the single MCP access point. Agents connect here; it exposes one MCP surface regardless of how many backends sit behind it.
• Gateway Target — a backend the Gateway connects to. Targets come in two categories: MCP targets (aggregated — Lambda, OpenAPI, Smithy, API Gateway stages, remote MCP servers, the built-in SaaS templates) and HTTP targets (proxied — e.g. fronting an AgentCore Runtime agent as a tool).
• Authorizer — the required inbound authorization config, exactly one per gateway. This is the ingress side: it decides who may invoke the Gateway. Options include OAuth/JWT, IAM SigV4, AUTHENTICATE_ONLY, or none (dev/test).
• Credential Provider — the outbound credentials the Gateway uses to call a backend. This is the egress side, backed by AgentCore Identity.
• Workload Identity — auto-created when you create a gateway. You don't manage it directly; it's the agent/workload identity the Gateway operates under.

A useful mental model: the Authorizer is the bouncer at the door (inbound), the Credential Provider is the valet that fetches the right key for each backend (outbound), the Targets are the backends themselves, and the Gateway is the single front desk every agent talks to.

The MCP endpoint a Gateway exposes has a fixed shape:

https://{gateway-Id}.gateway.bedrock-agentcore.{Region}.amazonaws.com

This URL is returned to you as gatewayUrl from CreateGateway. Clients POST JSON-RPC over MCP Streamable HTTP to the /mcp path. The Gateway's ARN follows the standard pattern arn:${Partition}:bedrock-agentcore:${Region}:${Account}:gateway/${gateway-Id}.

A Gateway operates in one of two modes, determined by the kind of targets you attach. This distinction governs whether your tools get unified and searchable, or simply forwarded.

Aggregation mode (MCP targets). Multiple MCP targets are combined into a single virtual MCP server. The agent issues one tools/list call and gets back the union of tools across all aggregated targets. This is the mode that delivers Composition and Semantic Tool Selection. Lambda, OpenAPI, Smithy, API Gateway stages, remote MCP servers, and the built-in SaaS templates are all MCP targets.

Direct / proxy mode (HTTP targets). HTTP targets — for example, fronting a deployed AgentCore Runtime agent as a tool (agent-as-tool) — are proxied with path-based routing. There is no aggregation and no translation: the request is forwarded. HTTP targets are not searchable by semantic tool selection.

The practical takeaway: if you want a unified, searchable tool catalog, use MCP targets. Use the HTTP/proxy path specifically when you want to expose one Runtime agent to other agents as a callable tool.

When Gateway aggregates targets, two different targets could expose tools with the same name. Gateway prevents collisions by namespacing every tool with its target name using a triple underscore:

${target_name}___${tool_name}

For example, a target named LambdaUsingSDK that exposes a tool get_order_tool appears to the agent — in tools/list and in tools/call — as:

LambdaUsingSDK___get_order_tool

Here is the gotcha that bites everyone: your downstream backend receives the prefixed name. When the Gateway dispatches the call to your Lambda, the tool name in the payload still carries the ${target_name}___ prefix. If your Lambda's router switches on the bare tool name (get_order_tool), it will fail to match. You must strip the ${target_name}___ prefix before dispatching downstream.

A minimal Lambda handler that does this correctly:

def handler(event, context):
    # Gateway passes the namespaced tool name, e.g. "LambdaUsingSDK___get_order_tool"
    tool_name = context.client_context.custom["bedrockAgentCoreToolName"]

    # Strip the "${target_name}___" prefix (split on the triple underscore).
    if "___" in tool_name:
        tool_name = tool_name.split("___", 1)[1]   # -> "get_order_tool"

    if tool_name == "get_order_tool":
        order_id = event["order_id"]
        return {"status": "shipped", "order_id": order_id}
    raise ValueError(f"Unknown tool: {tool_name}")

One more constraint to keep in mind: the namespaced tool name has a length ceiling of 256 characters (treat as [VOLATILE] — verify the live quotas page). Because the prefix eats into that budget, very long target and tool names can collide with the limit.

There are four ways to create a Gateway: the Console, the new AgentCore CLI, boto3 against the bedrock-agentcore-control client, and the Starter Toolkit GatewayClient. Here are the two you'll reach for most.

boto3 (control plane). You create the Gateway on the control plane, specifying its protocol, inbound authorizer, and (optionally) semantic search. Note that gatewayUrl comes back in the response:

import boto3

client = boto3.client("bedrock-agentcore-control")

gw = client.create_gateway(
    name="my-gateway",
    roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
    protocolType="MCP",
    authorizerType="CUSTOM_JWT",                       # inbound: OAuth/JWT
    authorizerConfiguration={
        "customJWTAuthorizer": {
            "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/<pool>/.well-known/openid-configuration",
            "allowedClients": ["clientId"],
        }
    },
    protocolConfiguration={"mcp": {"searchType": "SEMANTIC"}},  # enables semantic tool search
)

print(gw["gatewayUrl"])
# -> https://{gateway-Id}.gateway.bedrock-agentcore.us-west-2.amazonaws.com

AgentCore CLI. The CLI wraps the same control plane with friendlier verbs. You add a gateway, then add targets to it, then deploy:

# Create the gateway (NONE authorizer here is dev/test only)
agentcore add gateway --name TestGateway --authorizer-type NONE --runtimes MyGatewayAgent

# Add a Lambda MCP target with a tool schema
agentcore add gateway-target --name TestLambdaTarget --type lambda-function-arn \
  --lambda-arn <ARN> --tool-schema-file tools.json --gateway TestGateway

# Add an OpenAPI MCP target (each operationId becomes a tool)
agentcore add gateway-target --name MyOpenAPITarget --type open-api-schema \
  --schema path/to/openapi.json --outbound-auth none --gateway MyGateway

agentcore deploy

We build out the full range of targets — Lambda toolSchema, OpenAPI/operationId, Smithy, remote MCP servers, and Runtime-as-tool — in the next lesson. The point here is to see that a Gateway is just a control-plane resource you create once, and the MCP endpoint it hands back is the single door every agent walks through.