How AgentCore Gateway Turns Any API Into an Agent Tool

TL;DR

• AgentCore Gateway is a managed front door for agent traffic. Agents connect to one endpoint; the gateway presents every registered tool as a single virtual MCP server.
• It solves the two hard parts of exposing a capability to agents: inbound auth (who may call the gateway) and outbound auth (how the gateway reaches the backend). Both are configured on the gateway, not in each tool.
• A tool is a target. Register a Lambda or an API as a target, and the gateway translates the agent's MCP call into an invocation of that backend, then translates the result back. No protocol code in the tool.
• The gateway collapses the M×N wiring problem to M×1. M agents each connect once; N tools each register once; neither side tracks the other's count. AWS calls the MCP behavior aggregation mode.

---

AgentCore Gateway is a managed front door between your agents and the tools they call. An agent opens one connection to the gateway and sees a menu of tools; behind the gateway, each tool is a Lambda, an API, or another service that never had to know the Model Context Protocol existed. The gateway does the translation, the authentication on both sides, and the fan-out to every connected agent. I run one with three tools on it, and adding the third took an afternoon because the gateway had already solved everything that is usually hard.

This post is about how that front door actually works — the target model, the two authentication boundaries, and the path a single tool call travels.

The Shape of It

A gateway sits between two populations that should not have to know about each other's size. On one side, agents. On the other, backends — Lambdas, APIs, services. The gateway is the only thing both sides connect to.

flowchart LR
    A1["agent: terminal"] --> GW
    A2["agent: editor"] --> GW
    A3["agent: CLI"] --> GW
    GW["AgentCore Gateway (one MCP endpoint)"] --> T1["target: kb-retrieve"]
    GW --> T2["target: web-search"]
    GW --> T3["target: publish"]

Every agent connects to the same endpoint. Every tool is a target behind it. The agent asks the gateway what tools exist and gets the combined list of all targets. AWS calls this aggregation mode: for MCP targets, the gateway "acts as an MCP server that combines the capabilities of all its MCP targets into a unified virtual MCP server." One endpoint, many tools, and the agent cannot tell that the tools live in separate Lambdas.

Targets: How a Backend Becomes a Tool

A target is the declaration that turns a backend into a tool. It names the backend, the tool it exposes, and the input schema the agent should send. The gateway supports three categories of target:

Target type	What it connects	Behavior
MCP	APIs, Lambda functions, existing MCP servers	Aggregated into the unified virtual MCP server
HTTP	Other agents, A2A services, HTTP endpoints	Proxied directly, path-based, no aggregation
Inference	Model providers	Routed by requested model

For a Lambda or an API you use an MCP target, and the gateway takes on the translation job: it "converts agent requests using protocols like Model Context Protocol into API requests and Lambda invocations." The tool author writes a plain handler that takes a query and returns a result. The handler contains no MCP code, no auth code, no protocol version handling. The gateway wraps all of that around it.

Registering the target is the entire integration. Point the gateway at the Lambda, give the tool a name and an input schema, and the tool appears in every agent already connected to that gateway on their next tool listing. There is no per-agent change.

Here is the target that turns my knowledge-base Lambda into a tool. It is a Lambda target with one tool definition — a name, a description the agent reads to decide when to use it, and the input schema:

{
  "name": "kb-retrieve",
  "targetType": "lambda",
  "lambdaArn": "<my-retrieval-lambda-arn>",
  "toolDefinitions": [
    {
      "name": "kb_retrieve",
      "description": "Semantic search over my blog knowledge base. Returns relevant source chunks with their document source and relevance score.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "The search query or question" },
          "numberOfResults": { "type": "integer", "description": "Number of chunks to return (1-20). Default: 5." }
        },
        "required": ["query"]
      }
    }
  ]
}

That declaration is the whole contract. The gateway now knows how to present the tool to agents and how to invoke the Lambda behind it. The description matters more than it looks: it is what the agent reads to decide whether this tool fits the task.

Two Authentication Boundaries

A gateway authenticates on both sides, and both boundaries are configured on the gateway itself. That dual authentication is what makes it a security boundary, and it is the reason the gateway can be trusted to sit in front of every tool.

          inbound auth                 outbound auth
          (JWT / IAM)          (service role / credential)
   agent  ──────────▶  Gateway  ────────────────▶  backend (Lambda / API)
     (holds a token             (holds credentials
      for the gateway)           for the backend)

Inbound controls who may call the gateway. The gateway requires an inbound authorizer and supports four types: OAuth (JWT), IAM (SigV4), authenticate-only (validate the token, delegate the decision to the target), and none (development only). Mine uses a JWT authorizer, so an agent presents a bearer token, the gateway validates it, and only then is the tool list even visible.

Outbound controls how the gateway reaches the backend. For a Lambda target, the gateway uses an attached execution role to invoke the function. For an API or external MCP server, you attach a credential provider that stores an API key or OAuth credentials, or configure SigV4 signing. The agent never holds the backend's credentials. It holds a token for the gateway; the gateway holds credentials for the backends.

That split is the point. A tool author does not implement authentication. They register a target and the gateway applies the inbound rule that already exists and the outbound credential the target declares. This is what the docs mean by calling Gateway the only managed service providing both ingress and egress authentication.

The Path of One Call

Follow a single tool call from an agent asking "what have I written about this" to an answer:

sequenceDiagram
    participant AG as Agent
    participant GW as AgentCore Gateway
    participant L as Lambda target
    participant API as Backend API
    AG->>GW: MCP call (tool + args) + bearer token
    Note over GW: validate token (inbound auth)
    Note over GW: translate MCP call to Lambda invoke
    GW->>L: invoke with service role (outbound auth)
    L->>API: one API call
    API-->>L: result
    L-->>GW: return payload
    Note over GW: translate result to MCP response
    GW-->>AG: tool result

The agent sends an MCP request naming the tool and its arguments, carrying its bearer token. The gateway validates the token, finds the target, translates the MCP call into a Lambda invocation, and calls the Lambda using its own service role. The Lambda makes the single backend API call it exists to make, returns the result, and the gateway translates that back into an MCP response. The agent gets a tool result and never saw the Lambda, the role, or the API.

Every boundary the tool author would normally build — the protocol layer, the token check, the backend credential — is handled at the gateway. The Lambda is left with only its one job.

Why the Count Stops Mattering

The reason this architecture is worth the setup is what happens as tools and agents multiply.

Wire each tool directly into each agent and you have an M×N problem: every new tool must be added to every agent, and every new agent must be given every tool. AWS names this exactly — the gateway "eliminates the M×N integration problem."

  direct wiring (M×N edges)          gateway (M+N edges)

  agent 1 ──┐ ┌─ tool A            agent 1 ─┐          ┌─ tool A
          ├─┼─                          ├─▶ gateway ─┼─
  agent 2 ──┘ └─ tool B            agent 2 ─┘          └─ tool B
  (every agent wired               (each agent connects once,
   to every tool)                   each tool registers once)

With a gateway, each agent connects once and each tool registers once. The two sides never track each other's number. I felt this concretely: I run several agents — a terminal agent, two editors, a CLI — and adding a knowledge-base tool meant editing none of them. The tool was there the next time each one connected, because it was registered to the gateway they already trusted.

Finding the Right Tool Among Many

Aggregation creates a second-order problem: as the tool list grows, handing an agent every tool description on every request bloats the prompt and makes the model pick worse. The gateway has an answer built in. Enable semantic search on the gateway and it exposes a meta-tool — x_amz_bedrock_agentcore_search — that an agent calls with a natural-language query to find the most relevant tools instead of loading all of them upfront.

My gateway turns this on with one line of configuration:

"protocolConfiguration": { "mcp": { "searchType": "SEMANTIC" } }

This is retrieval applied to tools — the same pattern as retrieval over documents, pointed at the tool catalog. AWS notes it is "particularly useful when you have many tools". With three tools it changes little. It is the mechanism that lets the M×1 model keep scaling past the point where a flat tool list would start hurting the agent.

What's Missing

The afternoon is real, but it assumes the gateway already exists. Standing up the first gateway — the inbound authorizer, the identity flow, the service role that lets targets reach cloud resources safely — is the actual work, and it is not an afternoon. Wiring your very first tool is genuinely simpler as a direct connection. The gateway earns its place once the second and third tool are in view.

The other open edge is blast radius. A gateway that fans one tool out to every agent also fans out every mistake. A target with too broad an outbound role, or one that returns more than it should, now reaches every connected agent at once. Centralizing the tool surface centralizes the risk, and the controls that answer it — per-target scoping, fine-grained authorization at the gateway boundary — are their own build. For a handful of read-only tools it is fine. I would not put a write-capable tool behind a shared gateway without more control than a basic setup gives you.

So What

AgentCore Gateway moves the hard parts of tool integration — protocol translation, inbound auth, outbound auth, fan-out — out of every tool and every agent and into one managed layer. A tool becomes a plain handler plus a target registration. An agent becomes one trusted connection. The capability I wanted behind it was a Bedrock Knowledge Base on the cheap tier of vector storage, reachable now from every agent I run.

The distance between "this is an API" and "my agents can use this" used to be a project. With the gateway in place it is a target registration, and the plumbing you paid for once carries every tool after it.