Building Gateway Targets

A Gateway by itself is just an MCP endpoint with an authorizer. The value comes from its targets — each target is a backend the Gateway connects to and exposes as one or more MCP tools. This is how AgentCore solves the M×N integration problem (M agents × N tools): you wire a backend into the Gateway once, and every agent that can speak MCP to the Gateway gets the tool.

Targets fall into two categories that behave very differently:

MCP targets are aggregated. Add five MCP targets and a single tools/list returns the union of all their tools — the agent sees one tool catalog, not five servers. HTTP targets are proxied, not aggregated: the Gateway routes by path and does no MCP↔backend translation, so they are not searchable and don't participate in the combined tool list.

Every tool name the agent sees is namespaced by the target name with a triple underscore: ${target_name}___${tool_name}, for example LambdaUsingSDK___get_order_tool. That prefix is the most-stepped-on detail in the whole feature — we cover it in the gotchas section.

All six MCP target types are aggregated into the combined tools/list and are eligible for semantic search. What differs is how the backend's operations become tools — and which outbound (egress) auth modes each supports (the auth lesson has the full matrix; not every MCP target supports OAuth 3LO — Lambda, API Gateway, and Smithy targets do not).

1. AWS Lambda — you supply the toolSchema. The Gateway can't introspect a raw Lambda, so you declare each tool's name, description, and inputSchema yourself. The Gateway lists those tools; when the agent calls one, the Gateway invokes your Lambda. Your Lambda receives the prefixed tool name (${target_name}___${tool_name}) and must strip the prefix before dispatching.

2. Amazon API Gateway REST API stages (added post-launch). Point the target at an existing REST API stage and the Gateway exposes its operations as tools — handy when you've already published an API and want agents to call it without rebuilding anything.

3. OpenAPI 3.0/3.1 schema. Each operation becomes one tool, named after its operationId (then prefixed). The Gateway translates between MCP and HTTP, calling the URL in your spec's servers[].url. Swagger 2.0 is not supported — must be OpenAPI 3.0 or 3.1. (Details and gotchas below.)

4. Smithy model. Smithy is AWS's interface definition language (IDL). The Gateway generates tools from the operations declared in the model — useful for AWS-shaped services already described in Smithy.

5. Remote MCP server. Front an existing remote MCP server through your Gateway so its tools join the aggregated catalog. It supports the server's tools (required), prompts (optional), and resources (optional).

6. Built-in integration provider templates. One-click templates for Salesforce, Slack, Jira, Asana, and Zendesk — the Gateway ships the tool definitions and the integration plumbing so you don't author a schema.

The OpenAPI media-type matrix is worth pinning down because it determines whether your spec will import cleanly:

Targets live under a Gateway, so the control-plane client is bedrock-agentcore-control (the same client you use for create_gateway). The Gateway itself is created with protocolType="MCP" and an authorizer; targets are then attached to it.

A Gateway, for reference:

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",
    authorizerConfiguration={"customJWTAuthorizer": {
        "discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/<pool>/.well-known/openid-configuration",
        "allowedClients": ["clientId"]}},
    protocolConfiguration={"mcp": {"searchType": "SEMANTIC"}})  # enables semantic search
print(gw['gatewayUrl'])

A Lambda MCP target. The Lambda target's config lives under targetConfiguration.mcp.lambda, with the function ARN and an inline toolSchema. For larger schemas you supply an S3 reference instead of inlinePayload. Outbound credentials are declared in credentialProviderConfigurations[]:

client.create_gateway_target(
    gatewayIdentifier=gw['gatewayId'],
    name="LambdaUsingSDK",
    targetConfiguration={
        "mcp": {
            "lambda": {
                "lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:order-tools",
                "toolSchema": {
                    "inlinePayload": [
                        {
                            "name": "get_order_tool",
                            "description": "Look up an order by its ID",
                            "inputSchema": {
                                "type": "object",
                                "properties": {"orderId": {"type": "string"}},
                                "required": ["orderId"]
                            }
                        }
                    ]
                    # ...or an S3 reference instead of inlinePayload for larger schemas
                }
            }
        }
    },
    credentialProviderConfigurations=[]
)

The agent will see this tool as LambdaUsingSDK___get_order_tool. Lambda targets use a basic GATEWAY_IAM_ROLE outbound config — no OAuth, no API key (see the auth lesson for the full matrix).

The exact targetConfiguration JSON keys for Smithy and API Gateway targets are not nailed down in our reference — treat those shapes as something to confirm against the live API reference before you ship code against them.

The AgentCore CLI wraps the same control-plane calls in a friendlier surface. You create the Gateway, add one or more targets, then deploy:

# 1. Create the gateway (NONE = no inbound auth, for dev/test only)
agentcore add gateway --name TestGateway --authorizer-type NONE --runtimes MyGatewayAgent

# 2a. Lambda target — point at the function ARN and a tool-schema file
agentcore add gateway-target --name TestLambdaTarget --type lambda-function-arn \
  --lambda-arn <ARN> --tool-schema-file tools.json --gateway TestGateway

# 2b. OpenAPI target — supply the spec and the outbound auth mode
agentcore add gateway-target --name MyOpenAPITarget --type open-api-schema \
  --schema path/to/openapi.json --outbound-auth none|api-key|oauth --gateway MyGateway

# 3. Deploy
agentcore deploy

The --tool-schema-file tools.json for a Lambda target is just the toolSchema payload — the array of {name, description, inputSchema} objects you'd otherwise inline in boto3:

[
  {
    "name": "get_order_tool",
    "description": "Look up an order by its ID",
    "inputSchema": {
      "type": "object",
      "properties": { "orderId": { "type": "string" } },
      "required": ["orderId"]
    }
  }
]

For the OpenAPI target, --outbound-auth is where you tell the Gateway how to authenticate to the backend (none, api-key, or oauth). Crucially, this is separate from any security scheme written into the OpenAPI document — the Gateway ignores in-spec security and uses what you configure here. There are four ways to create a Gateway in total (Console, AgentCore CLI, boto3 bedrock-agentcore-control, and the Starter Toolkit GatewayClient); CLI and boto3 are the two you'll script.

OpenAPI targets are the most common — and the most footgun-prone — so they deserve their own pass.

The core rule: each operation becomes exactly one tool, named after its operationId (then prefixed with the target name). Consider this fragment:

{
  "openapi": "3.1.0",
  "info": { "title": "Orders API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/orders/{orderId}": {
      "get": {
        "operationId": "getOrder",
        "summary": "Fetch a single order",
        "parameters": [
          { "name": "orderId", "in": "path", "required": true,
            "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}

The get /orders/{orderId} operation has operationId: getOrder, so the Gateway exposes a tool named getOrder — and the agent sees it as ${target_name}___getOrder. The Gateway handles MCP↔HTTP translation: when the agent calls the tool, the Gateway issues the HTTP request against servers[].url (here https://api.example.com/orders/{orderId}) and returns the response as an MCP tool result.

The single most common OpenAPI mistake: an operation with no operationId is not exposed as a tool at all. It's silently dropped. If a tool you expected is missing from tools/list, the first thing to check is whether that operation has an operationId in the spec.

You deliver the spec either inline or via S3, governed by size limits:

The 1 MB / 10 MB figures are quota values and can change — treat them as a starting point and confirm against the live AWS quotas page. The practical rule holds regardless of the exact numbers: small specs inline, large specs in S3.

The one HTTP target type fronts a deployed AgentCore Runtime agent as a tool — the agent-as-tool pattern. A supervisor agent calls a specialist agent through the Gateway exactly as it would call any other tool, which is the building block for multi-agent systems where one agent delegates a subtask to another.

The trade-offs versus MCP targets are real and worth internalizing:

• No aggregation. The Gateway proxies to the Runtime agent with path-based routing; it does not fold the agent into the combined MCP tools/list.
• No semantic search. Only MCP targets are indexed for x_amz_bedrock_agentcore_search — HTTP targets are not searchable.
• No MCP↔backend translation. It's a proxy, not a translator.

On outbound auth, the Runtime HTTP target is the only target that supports Caller IAM (via Forward Access Sessions / FAS), alongside the Gateway service role, OAuth 2LO, and token passthrough — useful when the downstream agent must act under the caller's permissions rather than the Gateway's.

Mental model:

Agent (MCP client)
  -> Gateway (one MCP endpoint)
       |-- MCP targets:  Lambda / OpenAPI / Smithy / API GW / remote MCP   [aggregated, searchable]
       \-- HTTP target:  AgentCore Runtime agent                           [proxied, agent-as-tool]

Most failed target setups come down to a short list of well-known traps. Memorize these — they're the difference between a tool that works and a tool that silently never appears.

• Forgetting operationId. An OpenAPI operation without an operationId is not exposed as a tool. No error — it just isn't there. Check this first when a tool is missing.
• Not stripping the ${target_name}___ prefix. Your downstream Lambda (or MCP server) receives the prefixed tool name. Dispatching on the raw name without stripping ${target_name}___ means your handler doesn't recognize it. Tool names are capped at 256 characters (a quota — verify on the live page).
• Swagger 2.0 is not supported. Only OpenAPI 3.0/3.1. Convert (or regenerate) Swagger 2.0 specs before importing.
• Composition keywords oneOf / anyOf / allOf are unsupported, along with complex parameter serializers, callbacks/webhooks, and links. Schemas leaning on these won't import cleanly.
• In-spec security schemes are ignored. Auth defined inside the OpenAPI document is not honored — configure outbound auth on the Gateway instead (--outbound-auth on the CLI, or credentialProviderConfigurations/outbound config in boto3).
• SSRF protection blocks private IPs. The Gateway blocks private IP ranges and you should avoid dynamic servers[].url values. Your backend must be reachable on a public/allowed endpoint.
• Trying to enable semantic search after creation. searchType="SEMANTIC" can only be set at Gateway creation; you can't flip it on later — you'd have to recreate the Gateway. (Strictly a Gateway-level setting, but it bites people the moment they add targets and expect search to light up.)

A quick triage table: