AgentCore Gateway Deep Dive: Architecture, Interceptors, and Semantic Discovery

1. Service Overview & Architecture

What is AgentCore Gateway?

AgentCore Gateway is a fully managed, serverless service within Amazon Bedrock AgentCore that provides a unified MCP (Model Context Protocol) endpoint for AI agents to discover and securely access tools. It transforms existing APIs, Lambda functions, and MCP servers into MCP-compatible tools with built-in authentication, credential management, and semantic search.

Core Value Proposition: Agents need tools. Enterprises have APIs, Lambda functions, and services scattered across their infrastructure with different auth mechanisms. Gateway provides a single, secure endpoint where agents can discover and invoke any of these tools using the standardized MCP protocol — eliminating months of custom integration work.

Source: Amazon Bedrock AgentCore Gateway Developer Guide

Positioning Within AgentCore

AgentCore consists of 9 modular services that can be used together or independently:

Source: Introducing Amazon Bedrock AgentCore Gateway

Six Core Architectural Functions

Gateway serves six fundamental roles:

Source: Transform your MCP architecture: Unite MCP servers through AgentCore Gateway

Architecture Overview

                                    ┌─────────────────────────────┐
                                    │     AgentCore Gateway       │
                                    │                             │
┌──────────┐   MCP/JWT or IAM       │  ┌───────────────────────┐  │    ┌──────────────┐
│  Agent   │ ─────────────────────►│  │  Inbound Auth         │  │───►│ Lambda Fn A  │
│ (Runtime │   tools/list           │  │  (JWT / IAM / None)   │  │    └──────────────┘
│  or      │   tools/call           │  └───────────────────────┘  │
│  External│   search               │  ┌───────────────────────┐  │    ┌──────────────┐
│  Client) │                        │  │  Request Interceptor  │  │───►│ OpenAPI Svc  │
└──────────┘                        │  │  (optional Lambda)    │  │    └──────────────┘
                                    │  └───────────────────────┘  │
                                    │  ┌───────────────────────┐  │    ┌──────────────┐
                                    │  │  Tool Router /        │  │───►│ MCP Server   │
                                    │  │  Semantic Search      │  │    └──────────────┘
                                    │  └───────────────────────┘  │
                                    │  ┌───────────────────────┐  │    ┌──────────────┐
                                    │  │  Outbound Auth        │  │───►│ API Gateway  │
                                    │  │  (IAM/OAuth/API Key)  │  │    └──────────────┘
                                    │  └───────────────────────┘  │
                                    │  ┌───────────────────────┐  │    ┌──────────────┐
                                    │  │  Response Interceptor │  │───►│ Smithy API   │
                                    │  │  (optional Lambda)    │  │    └──────────────┘
                                    │  └───────────────────────┘  │
                                    └─────────────────────────────┘

Supported Protocols: MCP versions 2025-06-18 and 2025-03-26 over Streamable HTTP. A2A (Agent-to-Agent) communication is also supported.

Available in 15 AWS Regions: us-east-1, us-east-2, us-west-2, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, ca-central-1, eu-central-1, eu-west-1, eu-west-2, eu-west-3, eu-north-1, sa-east-1.

2. MCP Server Hosting on Gateway

Gateway speaks the MCP protocol natively. When an agent connects, it communicates using standard MCP JSON-RPC operations over HTTP.

Gateway Endpoint Formats

https://{gateway-id}.gateway.bedrock-agentcore.{region}.amazonaws.com/mcp
https://bedrock-agentcore-gateway.{region}.amazonaws.com/gateways/{gateway-id}/mcp

Three Core MCP Operations

List Tools (tools/list)

import requests

GATEWAY_URL = "https://{gateway-id}.gateway.bedrock-agentcore.{region}.amazonaws.com/mcp"

response = requests.post(GATEWAY_URL, json={
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "1"
}, headers={"Authorization": f"Bearer {token}"})

Call Tool (tools/call)

response = requests.post(GATEWAY_URL, json={
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "2",
    "params": {
        "name": "weather_tool___get_weather",  # {target_name}___{tool_name}
        "arguments": {"city": "Seattle"}
    }
}, headers={"Authorization": f"Bearer {token}"})

Semantic Search (tools/call with built-in search tool)

response = requests.post(GATEWAY_URL, json={
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "3",
    "params": {
        "name": "x_amz_bedrock_agentcore_search",
        "arguments": {"query": "how to check order status"}
    }
}, headers={"Authorization": f"Bearer {token}"})

Source: Using MCP semantic search with AgentCore Gateway

Tool Naming Convention

Tools are namespaced as {target_name}___{tool_name} (three underscores). For example, a target named weather_tool with tool get_weather becomes weather_tool___get_weather.

Connecting MCP Clients

Gateway works with any MCP-compatible client. Here are common integration patterns:

from strands import Agent
from strands.tools.mcp import MCPClient
from mcp.client.streamable_http import streamablehttp_client

def create_gateway_client(access_token, gateway_url):
    return MCPClient(
        lambda: streamablehttp_client(
            url=gateway_url,
            headers={"Authorization": f"Bearer {access_token}"}
        ),
        prefix="gateway"
    )

agent = Agent(tools=[create_gateway_client(token, gateway_url)])
result = agent("Check the weather in Seattle")

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

mcp_client = MultiServerMCPClient({
    "gateway": {
        "transport": "streamable_http",
        "url": gateway_url,
        "headers": {"Authorization": f"Bearer {access_token}"}
    }
})
tools = await mcp_client.get_tools()
graph = create_react_agent(model=bedrock_model, tools=tools)

Source: Amazon Bedrock AgentCore Samples — Tutorial 04

Gateway retrieves tools from MCP server targets in batches of 100, supporting up to 10,000 tools per target. Use the SynchronizeGatewayTargets API to force refresh.

3. Gateway Targets

Pre-built 1-click integrations with automatic OAuth: Salesforce, Slack, Jira, Asana, Zendesk.

Lambda Handler Pattern

When Gateway invokes a Lambda target, it passes the tool name via context.client_context.custom['bedrockAgentCoreToolName'] and arguments directly in the event:

def handler(event, context):
    delimiter = "___"
    original_tool_name = context.client_context.custom["bedrockAgentCoreToolName"]
    if delimiter in original_tool_name:
        tool_name = original_tool_name[original_tool_name.index(delimiter) + len(delimiter):]
    else:
        tool_name = original_tool_name

    if tool_name == "get_weather":
        city = event.get("city", "Unknown")
        return {"content": [{"type": "text", "text": f"Weather in {city}: 72F, Sunny"}]}

    return {"error": f"Unknown tool: {tool_name}"}

Source: Amazon Bedrock AgentCore Samples — Tutorial 01

Credential Provider Types

Gateway supports 25+ OAuth2 vendors including Google, GitHub, Slack, Salesforce, Microsoft, Atlassian, Okta, Auth0, Cognito, and more.

4. Semantic Tool Discovery

The Tool Overload Problem

As enterprise tool catalogs grow, agents face a fundamental challenge: tool overload. When an agent’s system prompt includes descriptions for hundreds or thousands of tools:

• Hallucination: LLMs may hallucinate tool names or parameters when overwhelmed
• Wrong tool selection: The model may select a semantically similar but incorrect tool
• Prompt bloat: Including all tool descriptions inflates prompt size, increasing cost and latency
• Context window limits: Large tool catalogs may exceed the model’s effective context window

Semantic search solves this by letting agents dynamically discover relevant tools at runtime.

Source: Transform your MCP architecture: Unite MCP servers through AgentCore Gateway

The Built-In Search Tool: x_amz_bedrock_agentcore_search

When semantic search is enabled, a built-in tool called x_amz_bedrock_agentcore_search becomes accessible via standard MCP tools/call. This tool:

• Takes a natural language query as input
• Returns a ranked list of tools matching the query
• Uses vector embeddings generated from tool names and descriptions
• Is accessible through the same MCP endpoint as all other tools

response = requests.post(GATEWAY_URL, json={
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "1",
    "params": {
        "name": "x_amz_bedrock_agentcore_search",
        "arguments": {"query": "how to check order status"}
    }
}, headers={"Authorization": f"Bearer {token}"})

Benefits

• Reduced prompt size: Instead of listing all 10,000 tools in the system prompt, agents search dynamically
• Up to 3x latency improvement: Less context = faster LLM inference
• Natural discovery: Agents find tools even without knowing exact names
• Reduced hallucination: Agents only see relevant tools, reducing wrong selections
• Scalability: Works with thousands of tools without performance degradation

Source: Using MCP semantic search with AgentCore Gateway

5. Agent-to-Agent (A2A) Communication

Gateway supports A2A patterns where one agent’s capabilities are exposed as tools for other agents through MCP. An agent running on AgentCore Runtime can be registered as a Gateway target:

Agent A ──► Gateway ──► Agent B (MCP server on Runtime)
                   ──► Agent C (MCP server on Runtime)

This enables hierarchical multi-agent patterns where a coordinator delegates to specialized sub-agents through Gateway. MCP session headers (mcpSessionId, mcpProtocolVersion) track conversations.

Source: Amazon Bedrock AgentCore Samples — Tutorial 12

6. Integration with AgentCore Identity

AgentCore Identity provides Workload Identities (digital identities for agents), a Token Vault (encrypted storage for credentials), OAuth2 Credential Providers, and API Key Credential Providers.

Inbound Authentication

Outbound Authentication

User identity is propagated through Gateway via the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header. Identity has no additional charges when used through Runtime or Gateway.

Source: Amazon Bedrock AgentCore Gateway Developer Guide

7. Security & Access Control

IAM Permissions for Gateway Role

The Gateway execution role (service principal: bedrock-agentcore.amazonaws.com) needs these permissions depending on configuration:

• Lambda targets: lambda:InvokeFunction
• Runtime targets: bedrock-agentcore:InvokeRuntime, bedrock-agentcore:InvokeRuntimeWithResponseStream
• Logging: logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents
• Credential providers: bedrock-agentcore:GetOAuth2CredentialProvider, secretsmanager:GetSecretValue, etc.
• Semantic search: bedrock:InvokeModel

Policy Engine (Cedar)

Gateway integrates with AgentCore Policy for declarative access control using Cedar. Two modes: LOG_ONLY (audit without blocking) and ENFORCE (block violations).

Multi-Tenant Access Pattern

User A (group: finance)     ─► Gateway ─► Interceptor ─► Finance tools only
User B (group: engineering) ─► Gateway ─► Interceptor ─► Engineering tools only
User C (group: admin)       ─► Gateway ─► Interceptor ─► All tools

Source: Apply fine-grained access control with Bedrock AgentCore Gateway interceptors

8. Interceptors — Deep Dive

Interceptors are Lambda functions that run before (REQUEST) or after (RESPONSE) tool invocations. They enable powerful middleware-like capabilities.

Source: AgentCore Gateway Interceptors

Interceptor Flow

Agent ─► Inbound Auth ─► REQUEST Interceptor ─► Target ─► RESPONSE Interceptor ─► Agent

Constraints: Maximum 1 interceptor per type (1 REQUEST + 1 RESPONSE = 2 total). Lambda-only.

REQUEST Interceptor Input Payload

{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
      "body": "<raw_request_body>"
    },
    "gatewayRequest": {
      "path": "/mcp",
      "httpMethod": "POST",
      "headers": {
        "Authorization": "Bearer <jwt_token>",
        "Content-Type": "application/json"
      },
      "body": {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list"
      }
    }
  }
}

Source: AgentCore Gateway Interceptor Types

REQUEST Interceptor Output — Key Behavior

Two possible outcomes:

• Pass-through: Return modified gateway request, forwarded to target
• Short-circuit: Return transformedGatewayResponse, Gateway responds immediately

RESPONSE Interceptor Input

The RESPONSE interceptor receives both the original request and the target’s response, enabling context-aware decisions:

{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "gatewayRequest": {
      "path": "/mcp",
      "httpMethod": "POST",
      "headers": { ... },
      "body": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { ... } }
    },
    "gatewayResponse": {
      "statusCode": 200,
      "headers": { ... },
      "body": {
        "jsonrpc": "2.0",
        "id": 1,
        "result": { "content": [{"type": "text", "text": "..."}] }
      }
    }
  }
}

Source: AgentCore Gateway Interceptor Types

Real-World Interceptor Use Cases

1. Fine-Grained Access Control (JWT Claims)

The REQUEST interceptor decodes the JWT, extracts user claims, and determines authorization. Unauthorized requests are short-circuited:

def handler(event, context):
    headers = event["mcp"]["gatewayRequest"]["headers"]
    body = event["mcp"]["gatewayRequest"]["body"]
    user_groups = extract_groups_from_jwt(headers.get("Authorization", ""))
    tool_name = body.get("params", {}).get("name", "")
    target_name = tool_name.split("___")[0] if "___" in tool_name else tool_name

    if not is_authorized(target_name, user_groups):
        return {"transformedGatewayResponse": {
            "statusCode": 403,
            "body": {"error": "Access denied"}
        }}
    return event["mcp"]["gatewayRequest"]

Source: Apply fine-grained access control with Gateway interceptors

2. Dynamic Tool Filtering

The RESPONSE interceptor filters tools/list results based on user permissions, preventing unauthorized tools from even appearing in the catalog.

3. Schema Translation

REQUEST interceptor transforms MCP requests into downstream-compatible formats. RESPONSE interceptor converts responses back. Useful for legacy API integration.

4. PII/SPI Data Redaction

RESPONSE interceptor inspects tool responses and masks sensitive data (credit cards, SSNs, emails) before returning to the agent, preventing data leaks into agent context.

5. Tenant Isolation for Multi-Tenant SaaS

REQUEST interceptor extracts tenant ID from JWT claims and injects it into downstream requests, ensuring data isolation across tenants.

6. Custom Header Propagation

Interceptor enriches downstream requests with identity headers (X-User-Id, X-User-Groups), correlation IDs for tracing, and tenant-specific configuration.

7. Token Exchange (Act-on-Behalf)

AWS recommends the act-on-behalf pattern over impersonation: the agent uses its own identity but includes user context so downstream services know who the action is for. The REQUEST interceptor handles token exchange.

Sources: AgentCore Samples Tutorials 07-10, 14-15

Tutorial Coverage

9. SDK & API Reference

Control Plane vs Data Plane

boto3 Example

import boto3

control = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

# Create Gateway
response = control.create_gateway(
    name="my_gateway",
    protocolType="MCP",
    roleArn=role_arn,
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration={
        "customJwtAuthorizer": {
            "discoveryUrl": discovery_url,
            "allowedClients": [client_id],
        }
    },
    protocolConfiguration={
        "mcp": {"supportedVersions": ["2025-03-26"], "searchType": "SEMANTIC"}
    }
)

# Create Target
control.create_gateway_target(
    gatewayIdentifier=response["gatewayId"],
    name="weather_tools",
    targetConfiguration={
        "mcp": {
            "lambda": {
                "lambdaArn": lambda_arn,
                "toolSchema": {"inlinePayload": tools_json}
            }
        }
    },
    credentialProviderConfigurations=[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]
)

Source: Amazon Bedrock AgentCore API Reference

Resource naming: Pattern ^[a-zA-Z][a-zA-Z0-9_]{0,47}$. Must start with a letter. No hyphens — use underscores. Maximum 48 characters.

10. Best Practices & Design Patterns

Architecture Patterns

Source: Transform your MCP architecture: Unite MCP servers through AgentCore Gateway

Key Recommendations

• Domain-driven target organization: Group tools by business domain, use meaningful names like crm_tools not lambda_1
• Never hardcode credentials: Use Token Vault for OAuth tokens and API keys
• Enable semantic search to reduce prompt size (up to 3x latency improvement)
• Batch tool schemas: Group related tools in a single Lambda target
• Use DEBUG exception level during development, remove in production
• Return structured errors from Lambda handlers: {"error": "message"}

11. Real-World Use Cases

Official Tutorials (15 Gateway Tutorials)

Source: Amazon Bedrock AgentCore Samples

Problems Gateway Solves

• Tool Sprawl: Dozens of APIs with different auth → unified endpoint
• Auth Complexity: Different credentials per backend → Token Vault manages all
• Tool Discovery at Scale: 1000+ tools → semantic search finds relevant ones
• Protocol Translation: REST/GraphQL/custom protocols → automatic MCP translation
• Enterprise Governance: Audit trails, access control, data masking → Gateway + Policy + Interceptors

12. Common Issues & Troubleshooting

Source: Amazon Bedrock AgentCore Gateway Developer Guide

13. Quotas, Limits & Pricing

Pricing: Consumption-based with no upfront commitments. Billed per MCP operation, per semantic search query, and per tool indexed. Identity has no additional charges when used through Gateway.

Source: Amazon Bedrock AgentCore Pricing

14. Comparison & Positioning

Gateway vs Self-Hosted MCP Servers

When Gateway is Essential

• Multiple backend systems with different auth mechanisms
• Enterprise governance (audit, access control, data masking)
• Large tool catalogs (100+ tools) requiring semantic discovery
• Multi-tenant SaaS with per-tenant tool access
• OAuth-heavy integrations (Salesforce, Slack, Jira)

When Gateway is Overkill

• Single MCP server with a few tools
• Prototype/hackathon — just connect MCP client directly
• Non-AWS infrastructure
• Single-agent, single-tool scenarios

15. Key Links & Resources

Official Documentation

• Gateway Developer Guide
• Gateway Interceptors
• Interceptor Types
• Semantic Search
• API Reference

AWS Blog Posts

• Introducing AgentCore Gateway (Aug 2025)
• Transform MCP Architecture with Gateway (Nov 2025)
• Fine-Grained Access Control with Interceptors (Nov 2025)

GitHub Repositories

• Official Samples (15 Gateway tutorials)
• Starter Toolkit
• Python SDK
• Full-Stack Template (FAST)

Authentication Flow

Agent ── 1. client_credentials ──► Cognito (IdP)
Agent ◄── 2. access_token ──────── Cognito
Agent ── 3. MCP tools/call ──────► Gateway
                                   4. Validate JWT (via discovery URL)
                                   Gateway ── 5. Get outbound creds ──► Token Vault
                                   Gateway ◄── 6. OAuth/API key ──── Token Vault
                                   Gateway ── 7. Call backend ──────► Target
                                   Gateway ◄── 8. Response ────────── Target
Agent ◄── 9. MCP response ──────── Gateway