# Amazon Bedrock AgentCore Gateway: Securely connect tools and other resources to your Gateway
Amazon Bedrock AgentCore Gateway provides an easy and secure way for developers to build, deploy, discover, and connect to tools at scale. AI agents need tools to perform real-world tasks—from querying databases to sending messages to analyzing documents. With Gateway, developers can convert APIs, Lambda functions, and existing services into Model Context Protocol (MCP)-compatible tools and make them available to agents through Gateway endpoints with just a few lines of code. Gateway supports OpenAPI, Smithy, and Lambda as input types, and is the only solution that provides both comprehensive ingress authentication and egress authentication in a fully-managed service. Gateway also provides 1-click integration with several popular tools such as Salesforce, Slack, Jira, Asana, and Zendesk. Gateway eliminates weeks of custom code development, infrastructure provisioning, and security implementation so developers can focus on building innovative agent applications.
**Topics**
+ [
## Key benefits
](#gateway-benefits-using)
+ [
## Key capabilities
](#gateway-core-concepts-connectivity-layer)
+ [
# Get started with AgentCore Gateway
](gateway-quick-start.md)
+ [
# Core concepts for Amazon Bedrock AgentCore Gateway
](gateway-core-concepts.md)
+ [
# Amazon Bedrock AgentCore Gateway features
](gateway-features.md)
+ [
# Supported targets for Amazon Bedrock AgentCore gateways
](gateway-supported-targets.md)
+ [
# Prerequisites for using the Amazon Bedrock AgentCore gateway service
](gateway-prerequisites.md)
+ [
# Set up an Amazon Bedrock AgentCore gateway
](gateway-building.md)
+ [
# Use an AgentCore gateway
](gateway-using.md)
+ [
# Fine-grained access control for Amazon Bedrock AgentCore Gateway
](gateway-fine-grained-access-control.md)
+ [
# Debug and assess your gateway
](gateway-building-debug.md)
+ [
# Advanced features and topics for Amazon Bedrock AgentCore Gateway
](gateway-advanced.md)
## Key benefits
**Simplify tool development and integration**
Transform existing enterprise resources into agent-ready tools in just a few lines of code. Instead of spending months writing custom integration code and managing infrastructure, developers can focus on building differentiated agent capabilities while Gateway handles the undifferentiated heavy lifting of tool management and security at enterprise scale. Gateway also provides 1-click integration with several popular tools such as Salesforce, Slack, Jira, Asana, and Zendesk.
**Accelerate agent development through unified access**
Enable your agents to discover and use tools through a single, secure endpoint. By combining multiple tool sources—from APIs to Lambda functions—into one unified interface, developers can build and scale agent workflows faster without managing multiple tool connections or reimplementing integrations.
**Scale with confidence through intelligent tool discovery**
As your tool collection grows, help your agents find and use the right tools through contextual search. Built-in semantic search capabilities help agents effectively utilize available tools based on their task context, improving agent performance and reducing development complexity at scale.
**Comprehensive authentication**
Manage both inbound authentication (verifying agent identity) and outbound authentication (connecting to tools) in a single service. Handle OAuth flows, token refresh, and secure credential storage for third-party services.
**Framework compatibility**
Work with popular open-source frameworks including CrewAI, LangGraph, LlamaIndex, and Strands Agents. Integrate with any model while maintaining enterprise-grade security and reliability.
**Serverless infrastructure**
Eliminate infrastructure management with a fully managed service that automatically scales based on demand. Built-in observability and auditing capabilities simplify monitoring and troubleshooting.
## Key capabilities
Gateway provides the following key capabilities:
+ **Security Guard** - Manages OAuth authorization to ensure only valid users and agents can access tools and resources.
+ **Translation** - Converts agent requests using protocols like Model Context Protocol (MCP) into API requests and Lambda invocations, eliminating the need to manage protocol integration or version support.
+ **Composition** - Combines multiple APIs, functions, and tools into a single MCP endpoint for streamlined agent access.
+ **Secure Credential Exchange** - Handles credential injection for each tool, enabling agents to use tools with different authentication requirements seamlessly.
+ **Semantic Tool Selection** - Enables agents to search across available tools to find the most appropriate ones for specific contexts, allowing agents to leverage thousands of tools while minimizing prompt size and reducing latency.
+ **Infrastructure Manager** - Provides a serverless solution with built-in observability and auditing, eliminating infrastructure management overhead.
# Get started with AgentCore Gateway
In this quick start guide you’ll learn how to set up a gateway and integrate it into your agents using the AgentCore CLI. For more comprehensive guides and examples, see the [Amazon Bedrock AgentCore Gateway GitHub repository](https://github.com/awslabs/amazon-bedrock-agentcore-samples/tree/main/01-tutorials/02-AgentCore-gateway).
**Note**
The AgentCore CLI provides both commands and an interactive TUI wizard for managing AgentCore Gateway resources. For the full AWS SDK API reference, see [AgentCore Control Plane operations](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html).
**Topics**
+ [
## Prerequisites
](#gateway-quick-start-prereqs)
+ [
## Step 1: Setup and install
](#gateway-quick-start-setup)
+ [
## Step 2: Create gateway
](#gateway-quick-start-create-gateway-setup)
+ [
## Step 3: Run the setup
](#gateway-quick-start-run-setup)
+ [
## Step 4: Use the gateway with an agent
](#gateway-quick-start-use-gateway-with-agents)
+ [
## What you’ve built
](#gateway-quick-start-what-youve-built)
+ [
## Troubleshooting
](#gateway-quick-start-troubleshooting)
+ [
## Quick validation
](#gateway-quick-start-quick-validation)
+ [
## Cleanup
](#gateway-quick-start-cleanup)
+ [
## Next steps
](#gateway-quick-start-next-steps)
## Prerequisites
Before starting, make sure you have the following:
+ ** AWS Account** with credentials configured. To configure credentials, you can install and use the AWS Command Line Interface by following the steps at [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).
+ **Node.js 18\$1** installed (for the AgentCore CLI).
+ **Python 3.10\$1** installed (for the agent script).
+ **IAM permissions** for creating roles, Lambda functions, and using Amazon Bedrock AgentCore.
+ **Model Access** – Enable Anthropic’s Claude Sonnet 3.7 in the Amazon Bedrock console (or another model for the demo agent)
## Step 1: Setup and install
Install the AgentCore CLI globally:
```
npm install -g @aws/agentcore
```
Create a new AgentCore project with an agent and a gateway:
**Example**
1.
```
agentcore create --name MyGatewayAgent --defaults
```
The `--defaults` flag creates a project with a default Python Strands agent. Alternatively, omit `--defaults` and `--name` to use the interactive wizard to select your preferred framework.
1. You can also run `agentcore create` without flags to use the interactive wizard. The wizard guides you through selecting a project name, agent framework, model provider, and other options.
## Step 2: Create gateway
Add a gateway and a target to your project using the AgentCore CLI:
**Example**
1.
```
# Add a gateway with no inbound auth (simplest for getting started)
agentcore add gateway --name TestGateway --authorizer-type NONE --runtimes MyGatewayAgent
# Add a Lambda function target
agentcore add gateway-target --name TestLambdaTarget --type lambda-function-arn \
--lambda-arn \
--tool-schema-file tools.json \
--gateway TestGateway
```
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** :
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select the authorizer type. For this quickstart, choose **NONE** :
![\[Gateway wizard: select NONE authorizer\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-none.png)
1. Configure advanced options or accept the defaults:
![\[Gateway wizard: advanced configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
Next, select **add** again and choose **Gateway Target** to add a Lambda function target:
1. Enter the target name.
1. Select **Lambda function** as the target type:
![\[Gateway target wizard: select Lambda function\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-lambda.png)
1. Enter the Lambda ARN and tool schema file path, then confirm.
To use JWT-based authorization instead, specify `--authorizer-type CUSTOM_JWT` with your OAuth discovery URL:
**Example**
1.
```
agentcore add gateway --name TestGateway \
--authorizer-type CUSTOM_JWT \
--discovery-url https://cognito-idp.us-east-1.amazonaws.com//.well-known/openid-configuration \
--allowed-audience \
--runtimes MyGatewayAgent
```
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** . When prompted for the authorizer type, select **Custom JWT** :
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select **Custom JWT** as the authorizer type:
![\[Gateway wizard: select Custom JWT authorizer\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-jwt.png)
1. Enter the OAuth discovery URL and allowed audience when prompted.
1. Configure advanced options or accept the defaults:
![\[Gateway wizard: advanced configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
## Step 3: Run the setup
Deploy your project to AWS:
```
agentcore deploy
```
The CLI synthesizes a AWS CDK stack and deploys your gateway, targets, and agent to Amazon Bedrock AgentCore. This takes about 2-3 minutes.
## Step 4: Use the gateway with an agent
Retrieve your gateway URL using the AgentCore CLI:
```
agentcore status
```
Create a new file called `run_agent.py` and insert the following code. Install the Python dependencies first:
```
pip install strands-agents mcp
```
```
"""
Agent script to test the Gateway
Run this after setup: python run_agent.py
"""
from strands import Agent
from strands.models import BedrockModel
from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client
import json
import sys
def create_streamable_http_transport(mcp_url: str):
return streamablehttp_client(mcp_url)
def get_full_tools_list(client):
"""Get all tools with pagination support"""
more_tools = True
tools = []
pagination_token = None
while more_tools:
tmp_tools = client.list_tools_sync(pagination_token=pagination_token)
tools.extend(tmp_tools)
if tmp_tools.pagination_token is None:
more_tools = False
else:
more_tools = True
pagination_token = tmp_tools.pagination_token
return tools
def run_agent():
# Get the gateway URL from agentcore status
gateway_url = "" # Replace with URL from 'agentcore status'
# Model configuration - change if needed
model_id = "anthropic.claude-3-7-sonnet-20250219-v1:0"
print("Starting AgentCore Gateway Test Agent")
print(f"Gateway URL: {gateway_url}")
print(f"Model: {model_id}")
print("-" * 60)
# Setup Bedrock model
bedrockmodel = BedrockModel(
model_id=model_id,
streaming=True,
)
# Setup MCP client (no auth token needed for NONE authorizer)
mcp_client = MCPClient(lambda: create_streamable_http_transport(gateway_url))
with mcp_client:
# List available tools
tools = get_full_tools_list(mcp_client)
print(f"\nAvailable tools: {[tool.tool_name for tool in tools]}")
print("-" * 60)
# Create agent
agent = Agent(model=bedrockmodel, tools=tools)
# Interactive loop
print("\nInteractive Agent Ready!")
print("Try asking: 'What's the weather in Seattle?'")
print("Type 'exit', 'quit', or 'bye' to end.\n")
while True:
user_input = input("You: ")
if user_input.lower() in ["exit", "quit", "bye"]:
print("Goodbye!")
break
print("\nThinking...\n")
response = agent(user_input)
print(f"\nAgent: {response.message.get('content', response)}\n")
if __name__ == "__main__":
run_agent()
```
### Run your agent
Test your gateway by running the agent and interacting with the tools.
```
python run_agent.py
```
That’s it\$1 The agent will start and you can ask questions like:
+ "What’s the weather in Seattle?"
+ "What time is it in New York?"
## What you’ve built
Through this getting started tutorial, you’ve created the following resources:
+ **MCP Server (Gateway)** : A managed endpoint at `https://gateway-id.gateway.bedrock-agentcore.region.amazonaws.com/mcp`
+ **Lambda tools** : Mock functions that return test data (weather: "72°F, Sunny", time: "2:30 PM")
+ **AI agent** : Claude-powered assistant that can discover and use your tools
## Troubleshooting
The following table shows some possible issues and their solutions:
| Issue | Solution |
| --- | --- |
| "No module named 'strands'" | Run: `pip install strands-agents` |
| "Model not enabled" | Enable Claude Sonnet 3.7 in Bedrock console → Model access |
| "AccessDeniedException" | Check IAM permissions for bedrock-agentcore:\$1 |
| Gateway not responding | Wait 30-60 seconds after creation for DNS propagation |
## Quick validation
Run the following commands in a terminal to check that your gateway is working.
```
# Check your Gateway is working
curl -X POST YOUR_GATEWAY_URL \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Watch live logs
aws logs tail /aws/bedrock-agentcore/gateways/YOUR_GATEWAY_ID --follow
```
## Cleanup
To remove the gateway and its targets from your project:
```
agentcore remove gateway --name TestGateway
```
To remove all resources and redeploy:
```
agentcore remove all
agentcore deploy
```
## Next steps
+ **Custom Lambda Tools** : Create Lambda functions with your business logic
+ **Add Your Own APIs** : Extend your Gateway with OpenAPI specifications for real services
+ **Production Setup** : Configure VPC endpoints, custom domains, and monitoring
# Core concepts for Amazon Bedrock AgentCore Gateway
Amazon Bedrock AgentCore Gateway provides a standardized way for AI agents to discover and interact with tools. Understanding the core concepts of Gateway will help you design and implement effective tool integration strategies for your AI agents.
## Key concepts
**Gateway**
An AgentCore Gateway acts like an MCP server, providing a single access point for an agent to interact with its tools. A Gateway can have multiple targets, each representing a different tool or set of tools.
**Gateway Target**
A target defines the APIs or Lambda function that a Gateway will provide as tools to an agent. Targets can be Lambda functions, OpenAPI specifications, Smithy models, or other tool definitions.
**AgentCore Gateway Authorizer**
Since MCP only supports OAuth, each Gateway must have an attached OAuth authorizer. If you don’t have an OAuth authorization server already, you will be able to create one in this guide using Cognito.
**AgentCore Credential Provider**
When Gateway makes calls to your APIs or Lambda function it must use some credentials to access those functionalities. When you create a Smithy or Lambda target, Gateway uses the attached execution role to make calls to those targets. When you create an OpenAPI target, you must attach an AgentCore credential provider which stores the API Key or OAuth credentials that Gateway will use to access the OpenAPI target.
## Tool types
Gateway supports several types of tools and integration methods:
**OpenAPI specifications**
Transform existing REST APIs into MCP-compatible tools by providing an OpenAPI specification. The gateway automatically handles the translation between MCP and REST formats.
**Lambda functions**
Connect Lambda functions as tools, allowing you to implement custom business logic in your preferred programming language. The gateway invokes the Lambda function and translates the response into the MCP format.
**Smithy models**
Use Smithy models to define your API interfaces and generate MCP-compatible tools. Smithy is a language for defining services and SDKs that can be used with AWS services. The gateway can use Smithy models to generate tools that interact with AWS services or custom APIs.
**MCP servers**
Use remote MCP servers to connect tools to your agent runtime. Only MCP tools capabilities are supported. For both control plane and data plane operations, if tools are not available the operations will fail.
# Amazon Bedrock AgentCore Gateway features
Amazon Bedrock AgentCore Gateway provides features that you can optionally enable for your gateway. The following table provides a brief description of these features and links to documentation to learn more about the feature:
| Feature | Description | How to use | Learn more |
| --- | --- | --- | --- |
| Debugging messages | Allow the return of detailed debugging messages when invoking a gateway. | Enable when creating or updating a gateway. You can disable this setting before deploying a gateway to production. | [Turn on debugging messages](gateway-debug-messages.md) |
| Custom encryption | Instead of using an AWS-managed key, encrypt your gateway with a custom AWS KMS key that you control and manage. | Specify the key when creating or updating a gateway. | [Encrypt your AgentCore gateway with a customer-managed KMS key](gateway-encryption.md) |
| Semantic search of tools | Search for tools in your gateway with a natural language query to find ones applicable to a use case. | Enable when creating a gateway and then call the `x_amz_bedrock_agentcore_search` tool when you invoke the gateway. | [Search for tools in your AgentCore gateway with a natural language query](gateway-using-mcp-semantic-search.md) |
| Tagging | Add tags to a gateway to categorize resources for tracking and organizational purposes. | Add tags when creating or updating a gateway. | [Tagging AgentCore resources](tagging.md) |
# Supported targets for Amazon Bedrock AgentCore gateways
Targets define the tools that your gateway will host. Amazon Bedrock AgentCore Gateway supports multiple target types that are detailed in the following topics. You can attach different credential providers to different targets, which lets you securely control access to targets. By adding targets, your gateway becomes a single MCP URL that enables access to all of the relevant tools for an agent.
The following topics explain the target types that are supported for AgentCore Gateway and how they integrate into your gateway. You should review these pages to make sure that a resource that you want to add as a target for your gateway is compatible. The final topic discusses how target names are constructed for a gateway so you can understand how to incorporate them.
**Topics**
+ [
# AWS Lambda function targets
](gateway-add-target-lambda.md)
+ [
# Amazon API Gateway REST API stages as targets
](gateway-target-api-gateway.md)
+ [
# OpenAPI schema targets
](gateway-schema-openapi.md)
+ [
# Smithy model targets
](gateway-building-smithy-targets.md)
+ [
# MCP servers targets
](gateway-target-MCPservers.md)
+ [
# Built-in templates from integration providers as targets
](gateway-target-integrations.md)
+ [
# Understand how AgentCore Gateway tools are named
](gateway-tool-naming.md)
# AWS Lambda function targets
Lambda targets allow you to connect your gateway to AWS Lambda functions that implement your tools. This is useful when you want to execute custom code in response to tool invocations.
You create a Lambda function using the AWS Lambda service. In order to create the function, you should do the following:
+ Create a tool schema that defines the tools that your Lambda function can call.
+ Understand the Lambda input format. You can then follow the steps in the [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/) for **Building with** the language of your choice.
After you create the function, you configure permissions for the gateway to be able to access it.
Review the key considerations and limitations to help you decide whether a Lambda target is applicable to your use case. If it is, you can create the tool schema and the Lambda function and then set up permissions for the gateway to be able to access the target. Select a topic to learn more:
**Topics**
+ [
## Key considerations and limitations
](#gateway-building-lambda-limitations)
+ [
## Lambda function tool schema
](#gateway-lambda-tool-schema)
+ [
## Lambda function input format
](#gateway-building-lambda-input)
## Key considerations and limitations
When working with Lambda targets, be aware of the following limitations and considerations:
+ Tool name prefixes will need to be manually stripped off from the toolname in your AWS Lambda function. For more information, see [Understand how AgentCore Gateway tools are named](gateway-tool-naming.md).
+ If you are using an existing AWS Lambda function and import it as a tool into the gateway, you will need to change the function code to account for a schema change for event and context objects
+ The Lambda function must return a valid JSON response that can be parsed by the gateway
+ Lambda function timeouts should be configured appropriately to handle the expected processing time of your tools
+ Consider implementing error handling in your LLambda function to provide meaningful error messages to the client
## Lambda function tool schema
This section explains the structure of the tool schema that defines a tool that your Lambda function can return. After you define your tool schema, you can do one of the following:
+ Upload it to an Amazon S3 bucket and refer to the S3 location when you add the target to your gateway.
+ Paste the definition inline when you add the target to your gateway.
Select a topic to learn more about the details of the tool schema or to see examples:
**Topics**
+ [
### Tool definition
](#gateway-lambda-tool-definition)
+ [
### Top level schema definition for input and output schemas
](#gateway-lambda-top-level-schema-definition)
+ [
### Property schema definition
](#gateway-lambda-property-schema-definition)
+ [
### Example Lambda tool definitions
](#gateway-lambda-example)
### Tool definition
When you add a Lambda function as a gateway target, you provide a [ToolDefinition](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_ToolDefinition.html) when providing the target configuration. The structure of the tool definition is as follows:
```
{
"name": "string",
"description": "string",
"inputSchema": {
"type": "object",
"description" "string",
"properties": {
"string": SchemaDefinition
},
"required": ["string"]
},
"outputSchema": {
"type": "object",
"description" "string",
"properties": {
"string": SchemaDefinition
},
"required": ["string"]
}
}
```
The tool definition contains the following fields:
+ **name** (required) – The name of the tool.
+ **description** (required) – A description of the tool and its purpose and usage.
+ **inputSchema** (required) – A JSON object that defines the structure of the input that the tool accepts.
+ **outputSchema** (optional) – A JSON object that defines the structure of the output that the tool produces.
The `inputSchema` and `outputSchema` fields both map to an object-type [SchemaDefinition](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_SchemaDefinition.html) , described in the following section.
### Top level schema definition for input and output schemas
The `inputSchema` and `outputSchema` fields at the top level of the tool definition both map to an object-type [SchemaDefinition](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_SchemaDefinition.html) that contains the following fields:
```
{
"type": "object",
"description": "string",
"properties": {
"string": SchemaDefinition
},
"required": ["string"]
}
```
+ **type** (required) – Must be `object`.
+ **description** (optional) – A description of the schema and its purpose and usage.
+ **properties** (optional) – A JSON object that defines the properties or arguments of the tool. Each key is a name of a property and maps to a [SchemaDefinition](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_SchemaDefinition.html) object that defines the property.
+ **required** (optional) – An array that enumerates the properties that are reqired in the `properties` object.
If you include a `properties` field to define arguments for the tool, you provide a schema definition for each argument. The different types of schema definitions are outlined in the next section.
### Property schema definition
Each property in the top level `SchemaDefinition` maps to a [SchemaDefinition](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_SchemaDefinition.html) object that has slightly different requirements from the top level schema definition. The available fields depend on the `type` for the property. To see the shape of the `SchemaDefinition` for a type, select from the following tabs:
**Example**
1. The `SchemaDefinition` for a string property has the following structure:
```
{
"type": "string",
"description": "string"
}
```
1. The `SchemaDefinition` for a number property has the following structure:
```
{
"type": "number",
"description": "string"
}
```
1. The `SchemaDefinition` for a integer property has the following structure:
```
{
"type": "integer",
"description": "string"
}
```
1. The `SchemaDefinition` for a boolean property has the following structure:
```
{
"type": "boolean",
"description": "string"
}
```
1. The `SchemaDefinition` for an array property has the following structure:
```
{
"type": "array",
"description": "string",
"items": SchemaDefinition
}
```
The value of the `items` field is a `SchemaDefinition` that defines the structure of each item in the array.
1. The `SchemaDefinition` for an object property has the following structure and matches the top level property schema definition.
```
{
"type": "object",
"description": "string",
"properties": {
"string": SchemaDefinition
},
"required": ["string"]
}
```
If you include another object-type property, you will recursively add another `SchemaDefinition`.
### Example Lambda tool definitions
Select a tab to see example tool definitions that you can include in your Lambda function.
**Example**
1. The following `get_weather` tool requires a `location` string argument and can be used to return the weather for that location:
```
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location e.g. seattle, wa"
}
},
"required": [
"location"
]
}
}
```
1. The following `get_time` tool requires a `timezone` string argument and can be used to return the time for that timezone:
```
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {
"timezone": {
"type": "string"
}
},
"required": [
"timezone"
]
}
}
```
## Lambda function input format
When an Amazon Bedrock AgentCore gateway invokes a Lambda function, it passes an `event` object and a `context` object to the function. The Lambda event handler that you write can access values in these objects.
**Event object**
A map of `properties` from the `inputSchema` to their values, as returned by the tool. For example, if your input schema contains the properties `keywords` and `category` , the event object could be the following:
```
{
"keywords": "wireless headphones",
"category": "electronics"
}
```
**Context object**
Contains the following metadata:
+ bedrockAgentCoreMessageVersion – The version of the message.
+ bedrockAgentCoreAwsRequestId – The ID of the request made to the Amazon Bedrock AgentCore service.
+ bedrockAgentCoreMcpMessageId – The ID of the message sent to the MCP server.
+ bedrockAgentCoreGatewayId – The ID of the gateway that was invoked.
+ bedrockAgentCoreTargetId – The ID of the gateway target that was invoked.
+ bedrockAgentCoreToolName– The name of the tool that was called. The tool name is in the format `${target_name}` *\$1* `${tool_name}`.
The format of the context object is as follows:
```
{
"bedrockAgentCoreMessageVersion": "1.0",
"bedrockAgentCoreAwsRequestId": "string",
"bedrockAgentCoreMcpMessageId": "string",
"bedrockAgentCoreGatewayId": "string",
"bedrockAgentCoreTargetId": "string",
"bedrockAgentCoreToolName": "string"
}
```
The Lambda function that you write can access the properties of the event and context object. You can use the following boilerplate code to get started:
```
# Access context properties in your Lambda function
def lambda_handler(event, context):
# Since the visible tool name includes the target name as a prefix, we can use this delimiter to strip the prefix
delimiter = "___"
# Get the tool name from the context
originalToolName = context.client_context.custom['bedrockAgentCoreToolName']
toolName = originalToolName[originalToolName.index(delimiter) + len(delimiter):]
# Get other context properties
message_version = context.client_context.custom['bedrockAgentCoreMessageVersion']
aws_request_id = context.client_context.custom['bedrockAgentCoreAwsRequestId']
mcp_message_id = context.client_context.custom['bedrockAgentCoreMcpMessageId']
gateway_id = context.client_context.custom['bedrockAgentCoreGatewayId']
target_id = context.client_context.custom['bedrockAgentCoreTargetId']
# Process the request based on the tool name
if tool_name == 'searchProducts':
# Handle searchProducts tool
pass
elif tool_name == 'getProductDetails':
# Handle getProductDetails tool
pass
else:
# Handle unknown tool
pass
```
# Amazon API Gateway REST API stages as targets
An API Gateway REST API target connects your gateway to a [stage](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-stages.html) of your REST API. The gateway translates incoming MCP requests into HTTP requests to your REST API and handles response formatting. When you add or update an API Gateway target, AgentCore Gateway calls API Gateway’s [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) API on your behalf.
You can specify tool filters and tool overrides in your target configuration. Tool filters let you make specific resource path and HTTP method combinations available as tools on your gateway. These filters create an allow list that exposes only the operations you specify as tools.
You can also configure your API Gateway REST API stage as a gateway target from the API Gateway console. To learn more, see [Add a stage to an AgentCore gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/mcp-server.html) in the Amazon API Gateway documentation.
**Topics**
+ [
## Key considerations and limitations
](#gateway-target-api-gateway-limitations)
+ [
## API Gateway Tool Configuration
](#gateway-target-api-gateway-configuration)
+ [
## API Gateway export
](#gateway-target-api-gateway-export)
+ [
## Supported outbound authorization methods for an API Gateway API
](#gateway-target-api-gateway-outbound)
## Key considerations and limitations
When using an API Gateway REST API stage as a target, keep in mind the following requirements and limitations:
+ Your API must be in the same account as your AgentCore Gateway.
+ Your API must be in the same Region as your AgentCore Gateway.
+ Your API must be an API Gateway REST API. We do not support API Gateway [HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) or [WebSocket APIs.](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html)
+ Your API must be configured with a public [endpoint type](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.htm) . Private endpoints are not supported. To create a Gateway Target that can access resources in your VPC, you should use a public endpoint and an [API Gateway private integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-private-integration.html).
+ If your REST API has a method that uses `AWS_IAM` authorization and requires an [API key](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) , AgentCore Gateway won’t support this method. It will be excluded from processing.
+ If your API uses a proxy resources, such as `/pets/{proxy+}` , AgentCore Gateway won’t support this method.
+ To set up your API Gateway Target, AgentCore Gateway calls API Gateway’s [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) API on your behalf to get an OpenAPI 3.0 formatted export of your REST API Definition. For more details on this and how it might affect your Target configuration, see [API Gateway Export.](#gateway-target-api-gateway-export)
## API Gateway Tool Configuration
When you add an API Gateway REST API as a gateway target you need to provide an API Gateway tool configuration. The API Gateway tool configuration defines which operations from your REST API are exposed as tools. It requires a list of tool filters to select operations to expose, and optionally accepts tool overrides to customize tool metadata like tool names and descriptions.
### Tool Filters
Tool filters allow you to select REST API operations using path and method combinations. Each filter supports two path matching strategies:
+ **Explicit paths** – Matches a single specific path, such as `/pets/{petId}`
+ **Wildcard paths** – Matches all paths starting with the specified prefix, such as /pets/\$1
Each filter specifies both a path and a list of HTTP methods. The filter resolves to matching combinations that exist in your API. Multiple filters can overlap and duplicates are automatically de-duplicated.
### Tool Overrides
By default, the MCP tool name is taken from the `operationId` for each path and method combination that matches your filters. If there isn’t an `operationId` for a filter match, you’ll need a corresponding tool override that provides a name. If both the `operationId` and the override name are missing, target creation and updates will fail validation. For more information on tool names in AgentCore Gateway, see [Understand how AgentCore Gateway tools are named](gateway-tool-naming.md).
Tool overrides are optional. They allow you to customize the tool name or description for specific operations after filtering. Each override must specify an explicit path and a single HTTP method. Wildcards are not supported. The override must match an operation that exists in your API and must correspond to one of the operations resolved by your filters. You cannot override operations that weren’t selected. If you are experiencing errors with imports from operations with out an `operationId` you can use a tool override instead.
### Example API Gateway tool configurations
The following example API Gateway tool configurations show how to use filters and overrides. All examples use an API with the following paths and methods:
```
/pets/{petId} - GET
/pets/{petId} - POST
/pets/{petId} - OPTIONS
/pets - GET
/pets - OPTIONS
/ - GET
```
**Wild card path and list of methods**
Tool Configuration:
```
{
"filterPath": "/pets/*",
"methods": ["GET", "POST"]
}
```
**Result**
+ `GET /pets/{petId}`
+ `POST /pets/{petId}`
**Explicit path and list of methods**
Tool Configuration:
```
{
"filterPath": "/pets/{petId}",
"methods": ["GET", "POST"]
}
```
**Result**
+ `GET /pets/{petId}`
+ `POST /pets/{petId}`
**Explicit path and list of explicit method (most specific)**
Tool Configuration:
```
{
[
{
"filterPath": "/pets/{petId}",
"methods": ["POST"]
},
{
"filterPath": "/pets/{petId}",
"methods": ["GET"]
}
]
}
```
**Result**
+ `GET /pets/{petId}`
+ `POST /pets/{petId}`
**Mix and match an explicit and wildcard path:**
Tool Configuration:
```
{
[
{
"filterPath": "/pets/{petId}",
"methods": ["GET"]
},
{
"filterPath": "/*",
"methods": ["GET"]
}
]
}
```
**Result**
+ `GET /pets/{petId}`
+ `GET /pets/`
**Tool filter and tool override**
You can provide a tool filter and add an override. The override specifies a resource path in the REST API, such as /pets, and an HTTP method to expose for the specified path. The override must explicitly match an existing path in the REST API.
Tool Configuration
```
{
"toolFilters": [
{
"filterPath": "/pets/*",
"methods": ["GET", "POST"]
},
{
"filterPath": "/",
"methods": ["GET"]
}
],
"toolOverrides": [
{
"path": "/pets/{petId}",
"method": "GET",
"name": "GetPetById",
"description": "Retrieve a specific pet by its ID"
}
]
}
```
**Result**
+ `GET /pets/{petId}` – matched by the first `toolFilter` , but the name and description will be overridden based on the entry in `toolOverrides`
+ `POST /pets/{petId}` – matched by the first `toolFilter` but will use the `operationId` and `description` from the exported OpenAPI spec for tool name and description
+ `GET /` – matched by the second, explicit tool filter that names a path and a single method
## API Gateway export
To set up your API Gateway target, AgentCore Gateway calls the [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) operation for API Gateway on your behalf to get an OpenAPI 3.0 formatted export of your API definition. This helps the gateway properly translate incoming MCP requests into HTTP requests and handle the response. The following are considerations for when AgentCore Gateway calls the GetExport operation:
+ The GetExport request is made with using a [Forward Access Session](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_forward_access_sessions.html) and uses the caller’s credentials.
+ The caller creating the target must have permissions to call [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) on the API in API Gateway.
+ The `GetExport` request will be logged in CloudTrail.
+ The exported API is subject to the same [considerations and limitations](gateway-schema-openapi.md#gateway-schema-openapi-considerations) as the OpenAPI target type.
+ The maximum size of an OpenAPI spec exported from API Gateway is 50 MB.
### Updating operationId on your REST API
**Important**
The exported OpenAPI specification must include `operationId` fields for all operations that you want to expose as tools. The `operationId` is used as the tool name in the MCP interface.
You can update your REST API to ensure that the OpenAPI definition returned by [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) has `operationId` set. This is an alternative to providing a tool override. The following explains two ways to set the `operationId`.
#### Set the operationID by updating your OpenAPI definition
Export the OpenAPI definition from your deployed API stage by calling [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) , updating the operations that are missing `operationId` , and reimporting your API.
1. Export the OpenAPI definition from your deployed API stage by calling [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html) . You can do this with the CLI:
```
aws apigateway get-export \
--rest-api-id rest-api-id \
--stage-name api-stage \
--export-type oas30 \
--parameters 'extensions=apigateway' \
'/path/to/api_oas30_template.json'
```
1. Edit the OpenAPI definition manually to add the `operationId` to operations that are missing the property.
1. Import your updated OpenAPI definition with [PutRestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html) . You can do this with the AWS CLI:
```
aws apigateway put-rest-api \
--rest-api-id rest-api-id \
--mode merge \
--body 'fileb:///path/to/api_oas30_template.json'
```
1. Redeploy your API to your stage with the AWS CLI:
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name api-stage \
--description 'deployment-description'
```
#### Set the `operationId` by updating your REST API’s method
You can configure your API Gateway [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) to add an `operationName` using the [UpdateMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) command. When your API is exported, the `operationName` turns into the `operationId`.
1. Call [UpdateMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) with the AWS CLI:
```
aws apigateway update-method \
--rest-api-id rest-api-id \
--resource-id resource-id \
--http-method http-method \
--patch-operations '[
{
"op": "replace",
"path": "/operationName",
"value": operation-id
}
]'
```
1. Redeploy your API to your stage with the AWS CLI:
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name api-stage \
--description 'deployment-description'
```
## Supported outbound authorization methods for an API Gateway API
You can configure your AgentCore Gateway target to make calls to your API with outbound authentication.
**AgentCore Gateway supports the following types of outbound authorization for API Gateway Targets:**
+ **IAM-based outbound authorization** – Use the [gateway service role](gateway-prerequisites-permissions.md#gateway-service-role-permissions) to authenticate access to the gateway target with [Signature Version 4 (SigV4 or SigV4a)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) . Requires your API Gateway API to have IAM authorization enabled.
+ **API key** – call your API with an API key managed by AgentCore Gateway. This is not the same as [API keys](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in API Gateway.
+ **No authorization (not recommended)** – Some target types provide you the option to bypass outbound authorization.
To learn more, see [Set up outbound authorization for your gateway](gateway-outbound-auth.md).
### IAM outbound authorization
API Gateway allows you to secure your REST API with IAM. When IAM authorization is enabled, clients must use [Signature Version 4 (SigV4 or SigV4a)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) to sign their requests with AWS credentials.
**To set up IAM outbound authorization**
1. Create an IAM role with the correct trust permissions according to [AgentCore Gateway service role permissions](gateway-prerequisites-permissions.md#gateway-service-role-permissions).
1. Add a policy to your role to allow the action `execute-api:Invoke` along with a resource that corresponds to the REST API Id and Stage you used to set up your target, such as the following policy:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:aws-region:account-id:rest-api-id/api-stage/*/*",
"Effect": "Allow"
}
]
}
```
#### API Gateway resource policies
API Gateway resource policies are JSON policy documents that you attach to an API Gateway REST API to control whether a specified principal can invoke the API. In order for AgentCore Gateway to call your REST API with a resource policy you must do the following:
+ Set the method authorization type to `AWS_IAM` for any REST API method you make available as a tool.
+ Configure your resource policy to allow the `bedrock-agentcore.amazonaws.com` principal to call your service. You can add additional principals to the policy.
The following is an example of an API resource policy that grants AgentCore Gateway access to your REST API.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:us-west-2:111122223333:abcd123/*/*/*",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
}
}
}
]
}
```
### API key outbound authorization
To set up outbound authorization with an API key, you use the AgentCore Identity service to create a credential provider and with an API key that you have configured for through API Gateway.
**To set up API key outbound authorization**
1. Create an API Key in API Gateway according to [Set up API keys for REST APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-setup-api-keys.html).
1. Follow the steps to [Set up outbound authorization with an API key](gateway-outbound-auth.md) , providing the API key that you created through API Gateway.
# OpenAPI schema targets
OpenAPI (formerly known as Swagger) is a widely used standard for describing RESTful APIs. Gateway supports OpenAPI 3.0 specifications for defining API targets.
OpenAPI targets connect your gateway to REST APIs defined using OpenAPI specifications. The Gateway translates incoming MCP requests into HTTP requests to these APIs and handles the response formatting.
Review the key considerations and limitations, including feature support, to help you decide whether an OpenAPI target is applicable to your use case. If it is, you can create a schema that follows the specifications and then set up permissions for the gateway to be able to access the target. Select a topic to learn more:
**Topics**
+ [
## Key considerations and limitations
](#gateway-schema-openapi-considerations)
+ [
## OpenAPI schema specification
](#gateway-openapi-schema)
## Key considerations and limitations
**Important**
The OpenAPI specification must include `operationId` fields for all operations that you want to expose as tools. The operationId is used as the tool name in the MCP interface.
When using OpenAPI targets, keep in mind the following requirements and limitations:
+ OpenAPI versions 3.0 and 3.1 are supported (Swagger 2.0 is not supported)
+ The OpenAPI file must be free of semantic errors
+ The server attribute needs to have a valid URL of the actual endpoint
+ Only application/json content type is fully supported
+ Complex schema features like oneOf, anyOf, and allOf are not supported
+ Path parameter serializers and parameter serializers for query, header, and cookie parameters are not supported
+ Each LLM will have ToolSpec constraints. If OpenAPI has APIs/properties/object names not compliant to ToolSpec of the respective downstream LLMs, the data plane will fail. Common errors are property name exceeding the allowed length or the name containing unsupported character.
For best results with OpenAPI targets:
+ Always include operationId in all operations
+ Use simple parameter structures instead of complex serialization
+ Implement authentication and authorization outside of the specification
+ Only use supported media types for maximum compatibility
### Security best practices for URL parameters
**Warning**
When defining server URLs in your OpenAPI specifications, avoid using overly permissive URL parameter patterns that could expose your gateway to security risks.
URL parameters in OpenAPI server definitions allow dynamic endpoint configuration. However, certain patterns can introduce security vulnerabilities if not properly constrained. Specifically, avoid using fully dynamic domain patterns such as:
+ `https://{yourDomain}/` - Allows arbitrary domain substitution
+ `https://{subdomain}.{env}.{domain}.com` - Multiple unconstrained placeholders
+ `https://{host}/api/` - Unrestricted host parameter
These patterns can potentially be exploited to:
+ Redirect requests to unintended or malicious endpoints
+ Access internal network resources (Server-Side Request Forgery)
+ Exfiltrate credentials or sensitive data
**Recommended practices:**
+ Use fully qualified, static URLs whenever possible: `https://api.example.com/v1`
+ Limit parameters to subdomains within your controlled domain and implement validation in your application
+ Avoid using parameters that allow arbitrary domain or host substitution
+ Implement additional validation in your API to verify that runtime parameter values match expected patterns
AgentCore Gateway automatically validates region parameters and blocks requests to private IP ranges.
Example of a secure server URL configuration:
```
{
"servers": [
{
"url": "https://api.example.com/v1"
}
]
}
```
If dynamic parameters are necessary, use fully qualified domains with minimal placeholders and enum restrictions:
```
{
"servers": [
{
"url": "https://{tenant}.api.example.com/v1",
"variables": {
"tenant": {
"default": "default-tenant",
"description": "Customer tenant identifier",
"enum": ["tenant1", "tenant2", "tenant3"]
}
}
}
]
}
```
This approach restricts URL parameters to specific subdomains within your controlled domain while maintaining flexibility for multi-tenant deployments. Using enum restrictions prevents arbitrary values and helps protect against SSRF attacks by limiting parameters to predefined, safe values. Additionally, always validate tenant values in your application logic.
In considering using OpenAPI schema targets with AgentCore Gateway, review the following feature support table.
### OpenAPI feature support
The following table outlines the OpenAPI features that are supported and unsupported by Gateway:
| Supported Features | Unsupported Features |
| --- | --- |
| **Schema Definitions** Basic data types (string, number, integer, boolean, array, object) Required field validation Nested object structures Array definitions with item specifications | **Schema Composition** oneOf specifications anyOf specifications allOf specifications |
| **HTTP Methods** Standard HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) | **Security Schemes** Security schemes at the OpenAPI specification level (authentication must be configured using the Gateway’s outbound authorization configuration) |
| **Media Types** application/json application/xml multipart/form-data application/x-www-form-urlencoded | **Media Types** Custom media types beyond the supported list Binary media types |
| **Path Parameters** Simple path parameter definitions (Example: /users/ \$1 userId\$1) | **Parameter Serialization** Complex path parameter serializers (Example: `/users { ;id\*} { ?metadata}`) Query parameter arrays with complex serialization Header parameter serializers Cookie parameter serializers |
| **Query Parameters** Basic query parameter definitions Simple string, number, and boolean types | **Callbacks and Webhooks** Callback operations Webhook definitions |
| **Request/Response Bodies** JSON request and response bodies XML request and response bodies Standard HTTP status codes (200, 201, 400, 404, 500, etc.) | **Links** Links between operations |
## OpenAPI schema specification
The OpenAPI specification defines the REST API that your Gateway will expose. Refer to the following resources when setting up your OpenAPI specification:
+ For information about the format of the OpenAPI specification, see [OpenAPI Specification](https://swagger.io/specification/).
+ For information about supported and unsupported features when using an OpenAPI specification with AgentCore Gateway, see the table in [OpenAPI feature support](#gateway-schema-openapi-features) . Adhere to these requirements to prevent errors during target creation and invocation.
After you define your OpenAPI schema, you can do one of the following:
+ Upload it to an Amazon S3 bucket and refer to the S3 location when you add the target to your gateway.
+ Paste the definition inline when you add the target to your gateway.
Expand a section to see examples of supported and unsupported OpenAPI specifications:
### Supported OpenAPI specification Example 1
Following shows an example of a supported OpenAPI specification
Example of a supported OpenAPI specification:
```
{
"openapi": "3.0.0",
"info": {
"title": "Weather API",
"version": "1.0.0",
"description": "API for retrieving weather information"
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"paths": {
"/weather": {
"get": {
"summary": "Get current weather",
"description": "Returns current weather information for a location",
"operationId": "getCurrentWeather",
"parameters": [
{
"name": "location",
"in": "query",
"description": "City name or coordinates",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "units",
"in": "query",
"description": "Units of measurement (metric or imperial)",
"required": false,
"schema": {
"type": "string",
"enum": ["metric", "imperial"],
"default": "metric"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"location": {
"type": "string"
},
"temperature": {
"type": "number"
},
"conditions": {
"type": "string"
},
"humidity": {
"type": "number"
}
}
}
}
}
},
"400": {
"description": "Invalid request"
},
"404": {
"description": "Location not found"
}
}
}
}
}
}
```
### Supported OpenAPI Specification Example 2
Following shows another example of a supported OpenAPI specification.
```
{
"openapi": "3.0.0",
"info": {
"title": "Search API",
"version": "1.0.0",
"description": "API for searching content"
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"paths": {
"/search": {
"get": {
"summary": "Search for content",
"operationId": "searchContent",
"parameters": [
{
"name": "query",
"in": "query",
"description": "Search query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of results",
"required": false,
"schema": {
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"snippet": {
"type": "string"
}
}
}
},
"total": {
"type": "integer"
}
}
}
}
}
},
"400": {
"description": "Bad request"
}
}
}
}
}
}
```
### Unsupported OpenAPI schema
The following shows an example of an unsupported schema with oneOf:
```
{
"oneOf": [
{"$ref": "#/components/schemas/Pencil"},
{"$ref": "#/components/schemas/Pen"}
]
}
```
# Smithy model targets
Smithy is a language for defining services and software development kits (SDKs). Smithy models provide a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services, such as AgentCore Gateway.
Smithy model targets connect your AgentCore gateway to services that are defined using Smithy API models. When you invoke a Smithy model gateway target, the gateway translates incoming MCP requests into API calls that are sent to these services. The gateway also handles the response formatting.
Review the key considerations and limitations, including feature support, to help you decide whether a Smithy target is applicable to your use case. If it is, you can create a schema that follows the specifications and then set up permissions for the gateway to be able to access the target. Select a topic to learn more:
**Topics**
+ [
## Key considerations and limitations
](#gateway-building-smithy-considerations)
+ [
## Smithy model specification
](#gateway-smithy-models)
## Key considerations and limitations
When using Smithy models with AgentCore Gateway, be aware of the following limitations:
+ Maximum model size: 10MB
+ Only JSON protocol bindings are fully supported
+ Only RestJson protocol is supported
In considering using Smithy models with AgentCore Gateway, review the following feature support table.
### Security best practices for endpoint configuration
**Warning**
When defining endpoint rules and server URLs in your Smithy models, avoid using overly permissive URL parameter patterns that could expose your gateway to security risks.
Smithy models support dynamic endpoint configuration through endpoint rules and URL parameters. However, certain patterns can introduce security vulnerabilities if not properly constrained. Specifically, avoid using fully dynamic patterns such as:
+ Unrestricted host or domain parameters in endpoint URLs: `https://{host}/api/v1` or `https://{domain}.example.com`
+ Multiple unconstrained placeholders in server URLs: `https://{subdomain}.{env}.{domain}.com`
+ Endpoint rules that allow arbitrary URL construction without validation
These patterns can potentially be exploited to:
+ Redirect requests to unintended or malicious endpoints
+ Access internal network resources or instance metadata services (Server-Side Request Forgery)
+ Exfiltrate IAM credentials or sensitive data
**Recommended practices:**
+ Use static, fully qualified endpoint URLs whenever possible
+ For AWS services, rely on standard endpoint resolution with validated region parameters. Gateway enforces AWS region validation for AWS services
+ If custom endpoint rules are required, constrain parameters to specific, validated values
+ Avoid exposing raw host or domain parameters in your Smithy model’s endpoint configuration
For AWS service integrations, AgentCore Gateway automatically validates region parameters and blocks requests to private IP ranges.
### Smithy feature support for AgentCore Gateway
The following table outlines the Smithy features that are supported and unsupported by Gateway:
| Supported Features | Unsupported Features |
| --- | --- |
| **Service Definitions** Service structure definitions based on Smithy specifications Operation definitions with input/output shapes Resource definitions Trait shapes **Protocol Support** RestJson protocol Standard HTTP request/response patterns **Data Types** Primitive types (string, integer, boolean, float, double) Complex types (structures, lists, maps) Timestamp handling Blob data types **HTTP Bindings** Basic HTTP method bindings Simple path parameter bindings Query parameter bindings Header bindings for simple cases **Endpoint Rules** Endpoint rule sets Runtime endpoint determination based on conditions | **Protocol Support** RestXml protocol JsonRpc protocol AwsQuery protocol Ec2Query protocol Custom protocols **Authentication** Multiple egress authentication types for specific APIs Complex authentication schemes requiring runtime decisions **Operations** Streaming operations Operations requiring custom protocol implementations |
## Smithy model specification
AgentCore Gateway provides built-in Smithy models for common AWS services. To see Smithy models for AWS services, see the [AWS API Models repository](https://github.com/aws/api-models-aws).
**Note**
AgentCore Gateway doesn’t support custom Smithy models for non-AWS services.
After you define your Smithy model, you can do one of the following:
+ Upload it to an Amazon S3 bucket and refer to the S3 location when you add the target to your gateway.
+ Paste the definition inline when you add the target to your gateway.
Expand a section to see examples of supported and unsupported Smithy model specifications:
### Example: Valid Smithy model for weather service
The following example shows a valid Smithy model specification for a weather service:
```
{
"smithy": "2.0",
"metadata": {
"suppressions": []
},
"shapes": {
"example.weather#WeatherService": {
"type": "service",
"version": "1.0.0",
"operations": [
{
"target": "example.weather#GetCurrentWeather"
}
],
"traits": {
"aws.protocols#restJson1": {},
"smithy.api#documentation": "Weather service for retrieving weather information"
}
},
"example.weather#GetCurrentWeather": {
"type": "operation",
"input": {
"target": "example.weather#GetCurrentWeatherInput"
},
"output": {
"target": "example.weather#GetCurrentWeatherOutput"
},
"errors": [
{
"target": "smithy.framework#ValidationException"
}
],
"traits": {
"smithy.api#http": {
"method": "GET",
"uri": "/weather"
},
"smithy.api#documentation": "Get current weather for a location"
}
},
"example.weather#GetCurrentWeatherInput": {
"type": "structure",
"members": {
"location": {
"target": "smithy.api#String",
"traits": {
"smithy.api#required": {},
"smithy.api#httpQuery": "location",
"smithy.api#documentation": "City name or coordinates"
}
},
"units": {
"target": "example.weather#Units",
"traits": {
"smithy.api#httpQuery": "units",
"smithy.api#default": "metric",
"smithy.api#documentation": "Units of measurement (metric or imperial)"
}
}
}
},
"example.weather#GetCurrentWeatherOutput": {
"type": "structure",
"members": {
"location": {
"target": "smithy.api#String",
"traits": {
"smithy.api#documentation": "Location name"
}
},
"temperature": {
"target": "smithy.api#Float",
"traits": {
"smithy.api#documentation": "Current temperature"
}
},
"conditions": {
"target": "smithy.api#String",
"traits": {
"smithy.api#documentation": "Weather conditions description"
}
},
"humidity": {
"target": "smithy.api#Float",
"traits": {
"smithy.api#documentation": "Humidity percentage"
}
}
}
},
"example.weather#Units": {
"type": "enum",
"members": {
"metric": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "metric"
}
},
"imperial": {
"target": "smithy.api#Unit",
"traits": {
"smithy.api#enumValue": "imperial"
}
}
}
}
}
}
```
### Example: Invalid Smithy model specification
The following example shows an invalid endpoint rules configuration using Smithy:
```
@endpointRuleSet({
"rules": [
{
"conditions": [{"fn": "booleanEquals", "argv": [{"ref": "UseFIPS"}, true]}],
"endpoint": {"url": "https://weather-fips.{Region}.example.com"}
},
{
"endpoint": {"url": "https://weather.{Region}.example.com"}
}
]
})
```
# MCP servers targets
MCP servers provide local tools, data access, or custom functions for your interactions with models and agents in Bedrock AgentCore. In Bedrock AgentCore, you can define a preconfigured MCP server as a target when creating a gateway.
MCP servers host tools that agents can discover and invoke. In Bedrock AgentCore, you use a gateway to associate targets with tools and connect them to your agent runtime. You connect with external MCP servers through the `SynchronizeGatewayTargets` API that performs protocol handshakes and indexes available tools. For more information about installing and using MCP servers, see [Amazon Bedrock AgentCore MCP Server: Vibe coding with your coding assistant](mcp-getting-started.md).
**Topics**
+ [
## Key considerations and limitations
](#gateway-target-MCPservers-considerations)
+ [
## Connecting to an OAuth-protected MCP server using Authorization Code flow
](#gateway-target-MCPservers-auth-code-grant-flow)
+ [
## Configuring permissions
](#gateway-target-MCPservers-permissions)
## Key considerations and limitations
Tool discovery is managed through the synchronization operation provided by the `SynchronizeGatewayTargets` API as follows.
**Implicit Synchronization**
Implicit synchronization is the automatic tool discovery and indexing that occurs during `CreateGatewayTarget` and `UpdateGatewayTarget` operations. Gateway immediately calls the MCP server’s tools/list capability to fetch available tools and make tools available in the unified catalog without requiring separate user action.
**Explicit Synchronization**
Manual tool catalog refresh triggered by calling the `SynchronizeGatewayTargets` API. Invoke this when the MCP server has changed its tool definitions. The API performs the discovery process on-demand, allowing users to control when Gateway updates its view of available tools.
Synchronization is a critical mechanism for maintaining accurate tool catalogs when integrating MCP servers. Implicit synchronization occurs automatically during target creation and updates, where Gateway immediately discovers and indexes tools from the MCP server to ensure tools are available for semantic search and unified listing. Explicit synchronization is performed on-demand through the `SynchronizeGatewayTargets` API, allowing discovery of the MCP tool catalog when MCP servers independently modify their capabilities.
**When to call SynchronizeGatewayTargets**
Use this API whenever your MCP server’s tools change - whether adding new tools, modifying existing tool schemas, or removing deprecated tools. Since Gateway pre-computes vector embeddings for semantic search and maintains normalized tool catalogs, synchronization ensures users can discover and invoke the latest available tools across all target types.
**How to call the API**
Make a PUT request to /gateways/ \$1 gatewayIdentifier\$1/synchronize with the target ID in the request body. The API returns a 202 response immediately and processes synchronization asynchronously. Monitor the target status through GetGatewayTarget to track synchronization progress, as the operation can take several minutes for large tool sets.
**Authorization strategy**
The following types of the authorization strategy are supported.
+ No authorization – The gateway invokes the MCP server without preconfigured authorization. This approach is not recommended.
+ OAuth – The gateway supports both two-legged OAuth (Client Credentials grant type) and three-legged OAuth (Authorization Code grant type). You configure the authorization provider in Amazon Bedrock AgentCore Identity in the same account and Region for the gateway to make calls to the MCP server.
+ IAM ( [AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) ) – The gateway signs requests to the MCP server using SigV4 with the gateway service role credentials. You configure an `IamCredentialProvider` with a required service name for SigV4 signing and an optional Region (defaults to the gateway Region).
**Important**
IAM (SigV4) outbound authorization requires that the MCP server is hosted behind an AWS service that natively supports IAM authentication. The gateway signs outbound requests with SigV4 but does not modify the authentication configuration on the target. The target service must be able to verify SigV4 signatures. The following AWS services natively support IAM authentication and are compatible with IAM outbound authorization for MCP server targets: \$1 Amazon Bedrock AgentCore Gateway \$1 Amazon Bedrock AgentCore Runtime (see [Deploy MCP servers in AgentCore Runtime](runtime-mcp.md) ) \$1 Amazon API Gateway \$1 Lambda Function URLs Services that do not natively verify SigV4 signatures, such as Application Load Balancer or direct Amazon EC2 endpoints, are not compatible with IAM outbound authorization. If your MCP server is hosted behind one of these services, use OAuth or API key authorization instead.
**Configuration considerations for MCP server targets**
The following must be configured.
1. The MCP server must have tool capabilities.
1. Supported MCP protocol versions are - **2025-06-18** , **2025-03-26** , and **2025-11-25**.
1. For the provided URL/endpoint of the server, the URL should be encoded. The Gateway will use the same URL to invoke the server.
1. JSON Schema reference keywords such as `$ref` , `$defs` , `$anchor` , `$dynamicRef` , and `$dynamicAnchor` are not supported in the tool definitions returned by the MCP server’s `tools/list` response. If your MCP server returns tool schemas containing these keywords, the target creation or synchronization will fail. Ensure your MCP server returns fully resolved, self-contained JSON schemas without reference keywords.
## Connecting to an OAuth-protected MCP server using Authorization Code flow
To support the Authorization Code grant type (three-legged OAuth) with MCP server targets, Amazon Bedrock AgentCore Gateway provides two methods for target creation.
**Implicit sync during MCP server target creation**
With this method, the admin user completes the authorization code flow during `CreateGatewayTarget` , `UpdateGatewayTarget` , or `SynchronizeGatewayTargets` operations using the authorization URL returned in the response. This allows Amazon Bedrock AgentCore Gateway to discover and cache the MCP server’s tools upfront.
**Note**
You cannot delete, update, or synchronize a target that is in a pending authorization state ( `CREATE_PENDING_AUTH` , `UPDATE_PENDING_AUTH` , or `SYNCHRONIZE_PENDING_AUTH` ). Wait for the authorization to complete or fail before performing further operations on the target.
**Provide schema upfront during MCP server target creation**
With this method, admin users provide the tool schema directly during `CreateGatewayTarget` or `UpdateGatewayTarget` operations using the `mcpToolSchema` field, rather than Amazon Bedrock AgentCore Gateway fetching them dynamically from the MCP server. Amazon Bedrock AgentCore Gateway parses the provided schema and caches the tool definitions.
**Note**
You cannot synchronize a target that has a static tool schema ( `mcpToolSchema` ) configured. Remove the static schema through an `UpdateGatewayTarget` call to enable dynamic tool synchronization.
**URL Session Binding**
[OAuth 2.0 authorization URL session binding](oauth2-authorization-url-session-binding.md) verifies that the user who initiated the OAuth authorization request is the same user who granted consent. After the user completes consent, the browser redirects back to a return URL configured on the target with a unique session URI. The application is then responsible for calling the [CompleteResourceTokenAuth](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CompleteResourceTokenAuth.html) API, presenting both the user’s identity and the session URI. Amazon Bedrock AgentCore Identity validates that the user who started the flow is the same user who completed it before exchanging the authorization code for an access token.
This prevents a scenario where a user accidentally shares the authorization URL and someone else completes the consent, which would grant access tokens to the wrong party. The authorization URL and session URI are only valid for 10 minutes, further limiting the window for misuse. Session binding applies during target creation (implicit sync) and during tool invocation.
**Note**
When performing target operations (Create, Update, or Synchronize) and authorization through the AWS Management Console, the [CompleteResourceTokenAuth](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CompleteResourceTokenAuth.html) call is made on behalf of the resource owner, requiring no further action after authorization.
## Configuring permissions
The IAM role which you use to create, update or synchronize MCP servers targets should have the permissions shown in the following example.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateGateway",
"bedrock-agentcore:GetGateway",
"bedrock-agentcore:CreateGatewayTarget",
"bedrock-agentcore:GetGatewayTarget",
"bedrock-agentcore:SynchronizeGatewayTargets",
"bedrock-agentcore:UpdateGatewayTarget"
],
"Resource": "arn:aws:bedrock-agentcore:*:*:*gateway*"
},
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:CreateWorkloadIdentity",
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForUserId",
"bedrock-agentcore:GetResourceOauth2Token",
"bedrock-agentcore:CompleteResourceTokenAuth",
"secretsmanager:GetSecretValue"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:EnableKeyRotation",
"kms:Decrypt",
"kms:Encrypt",
"kms:GenerateDataKey*",
"kms:ReEncrypt*",
"kms:CreateAlias",
"kms:DisableKey",
"kms:*"
],
"Resource": "arn:aws:kms:*:123456789012:key/*"
}
]
}
```
# Built-in templates from integration providers as targets
Amazon Bedrock AgentCore lets you add open source templates from the following integration providers as targets in your gateway:
+ Amazon
+ Asana
+ BambooHR
+ Brave
+ Confluence
+ Jira
+ Microsoft
+ PagerDuty
+ Salesforce
+ ServiceNow
+ Slack
+ Smartsheet
+ Tavily
+ Zendesk
+ Zoom
**Topics**
+ [
## Key considerations and limitations
](#gateway-target-integrations-considerations)
+ [
## Supported APIs by template
](#gateway-target-integrations-supported-apis)
## Key considerations and limitations
When using templates from integration providers as targets, keep in mind the following requirements and limitations:
+ You can only add an integration provider template as a target through the AWS Management Console and not through the API.
+ Amazon Bedrock AgentCore doesn’t host any servers natively, so you must set up server hosting yourself. After you add the template, you can invoke the server URL that you set up using the authorization that you configure.
+ Amazon Bedrock AgentCore supports a subset of APIs that the provider supports for interacting with these templates. For a list of APIs supported by AgentCore, see [Supported APIs by template](#gateway-target-integrations-supported-apis).
## Supported APIs by template
This section lists the APIs that are supported for each template from an integration provider. To learn more about a specific API and schemas, do the following:
+ Search for the provider’s API documentation.
+ Send a `tools/list` call to the target after setting it up.
The following sections show, for each template, the [outbound authentication](gateway-outbound-auth.md) types supported, the server URL, and the supported APIs and their paths.
**Note**
If an API path has a replaceable `{variable}` , pass the variable in the `params` field of the JSON RPC request.
Select a topic to learn about which APIs are supported for each template:
**Topics**
+ [
### Agents for Amazon Bedrock Runtime
](#gateway-target-integrations-supported-apis-bedrock-agent-runtime)
+ [
### Amazon Bedrock Runtime
](#gateway-target-integrations-supported-apis-bedrock-runtime)
+ [
### Amazon CloudWatch
](#gateway-target-integrations-supported-apis-cloudwatch)
+ [
### Amazon DynamoDB
](#gateway-target-integrations-supported-apis-amazon-dynamodb)
+ [
### Asana
](#gateway-target-integrations-supported-apis-asana)
+ [
### BambooHR
](#gateway-target-integrations-supported-apis-bamboohr)
+ [
### Brave Search
](#gateway-target-integrations-supported-apis-brave-search)
+ [
### The Confluence Cloud REST API v2
](#gateway-target-integrations-supported-apis-confluence)
+ [
### The Jira Cloud platform
](#gateway-target-integrations-supported-apis-jira)
+ [
### Microsoft Exchange
](#gateway-target-integrations-supported-apis-microsoft-exchange)
+ [
### Microsoft OneDrive
](#gateway-target-integrations-supported-apis-onedrive)
+ [
### Microsoft SharePoint
](#gateway-target-integrations-supported-apis-sharepoint)
+ [
### Microsoft Teams
](#gateway-target-integrations-supported-apis-microsoft-teams)
+ [
### PagerDuty Advance
](#gateway-target-integrations-supported-apis-pagerduty)
+ [
### Salesforce Lightning Platform
](#gateway-target-integrations-supported-apis-salesforce)
+ [
### ServiceNow
](#gateway-target-integrations-supported-apis-servicenow)
+ [
### Slack Web
](#gateway-target-integrations-supported-apis-slack)
+ [
### Smartsheet
](#gateway-target-integrations-supported-apis-smartsheet)
+ [
### Tavily Search
](#gateway-target-integrations-supported-apis-tavily)
+ [
### Zendesk Suite
](#gateway-target-integrations-supported-apis-zendesk)
+ [
### Zoom
](#gateway-target-integrations-supported-apis-zoom)
### Agents for Amazon Bedrock Runtime
The following list provides key information for this template
+ Server URL – https://bedrock-agent-runtime. `{region}` .amazonaws.com
Replace `{region}` with an actual value. Look up supported Regions at [Agents for Amazon Bedrock runtime APIs](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt).
+ Outbound authentication types accepted:
+ IAM credentials of gateway service role
To learn more about the Amazon Bedrock Agents Runtime API, see the [Agents for Amazon Bedrock API reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock_Runtime.html)
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | CreateSession | / | Creates a session to temporarily store conversations for generative AI applications. |
| POST | DeleteAgentMemory | / | Deletes a memory from an agent. |
| POST | DeleteSession | / | Deletes a session for temporarily storing conversations for generative AI applications. |
| POST | EndSession | / | Ends a session for temporarily storing conversations for generative AI applications. |
| POST | GenerateQuery | / | Generates a query to submit to an Amazon Bedrock knowledge base. |
| POST | GetAgentMemory | / | Gets a memory from an agent. |
| POST | GetSession | / | Gets a session for temporarily storing conversations for generative AI applications. |
| POST | InvokeAgent | / | Invokes an Amazon Bedrock agent. |
| POST | InvokeInlineAgent | / | Invokes an agent that you define inline. |
| POST | ListSessions | / | Lists sessions for temporarily storing conversations for generative AI applications. |
| POST | ListTagsForResource | / | Lists tags for an Agents for Amazon Bedrock Runtime resource. |
| POST | OptimizePrompt | / | Optimizes a prompt for a specific task. |
| POST | Rerank | / | Reranks the relevance of cited sources based on a query. |
| POST | Retrieve | / | Retrieves results from querying a knowledge base. |
| POST | RetrieveAndGenerate | / | Generate a natural language response based on results retrieved from querying a knowledge base. |
| POST | TagResource | / | Tag an Agents for Amazon Bedrock resource. |
| POST | UntagResource | / | Untag an Agents for Amazon Bedrock resource. |
| POST | UpdateSession | / | Update a session for temporarily storing conversations for generative AI applications. |
### Amazon Bedrock Runtime
The following list provides key information for this template
+ Server URL – https://bedrock-runtime. `{region}` .amazonaws.com
Replace `{region}` with an actual value. look up supported Regions at [Amazon Bedrock runtime APIs](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt) ).
+ Outbound authentication types accepted:
+ IAM credentials of gateway service role
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | Converse | / | Invoke an Amazon Bedrock model to generate a response in a conversational interface. |
| POST | ApplyGuardrail | / | Apply a guardrail to content. |
| POST | InvokeModel | / | Invoke an Amazon Bedrock model to generate a response for a prompt. |
### Amazon CloudWatch
The following list provides key information for this template
+ Server URL – https://monitoring. `{region}` .amazonaws.com
Replace `{region}` with an actual value. Look up supported Regions at [Amazon CloudWatch endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/cw_region.html).
+ Outbound authentication types accepted:
+ IAM credentials of gateway service role
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | DescribeAlarmHistory | / | Retrieve the history for an alarm you’ve set up. |
| POST | DescribeAlarms | / | Retrieve information about specific alarms. |
| POST | DescribeAlarmsForMetric | / | Retrieve information about alarms for a metric. |
| POST | DescribeAnomalyDetectors | / | Retrieve anomaly detection models that you’ve created in your account. |
| POST | DescribeInsightRules | / | Retrieve a list of Contributor Insights rules in your account. |
| POST | DisableAlarmActions | / | Disable actions for the specified alarms. |
| POST | DisableInsightRules | / | Disable the specified Contributor Insights rules. |
| POST | GetDashboard | / | Display the details of the dashboard that you specify. |
| POST | GetInsightRuleReport | / | Get the time series data collected by a Contributor Insights rule. |
| POST | GetMetricData | / | Get metric values. |
| POST | GetMetricStatistics | / | Get statistics for a specified metric. |
| POST | GetMetricStream | / | Get information about a metric stream. |
| POST | GetMetricWidgetImage | / | Get a snapshot graph of a metric as a bitmap image. |
| POST | ListDashboards | / | Return a list of dashboards. |
| POST | ListManagedInsightRules | / | Return a list of managed Contributor Insights rules. |
| POST | ListMetricStreams | / | Return a list of metric streams. |
| POST | ListMetrics | / | Retrieve a list of metrics. |
| POST | ListTagsForResource | / | List tags for a CloudWatch resource. |
### Amazon DynamoDB
The following list provides key information for this template
+ Server URL – https://dynamodb. `{region}` .amazonaws.com
Replace `{region}` with an actual value. Look up supported Regions at [Amazon DynamoDB endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ddb.html).
+ Outbound authentication types accepted:
+ IAM credentials of gateway service role
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | BatchExecuteStatement | / | Perform batch read or writes on data using PartiQL. |
| POST | BatchGetItem | / | Returns the attributes of items from one or more tables. |
| POST | BatchWriteItem | / | Puts or deletes items in one or more tables. |
| POST | CreateBackup | / | Create a backup for a table. |
| POST | CreateTable | / | Create a table. |
| POST | DeleteItem | / | Delete an item from a table. |
| POST | DeleteTable | / | Delete a table and all its items. |
| POST | DescribeBackup | / | Get information about a backup. |
| POST | DescribeContinuousBackups | / | Check the status of continuous backups and point in time recovery on a specified table. |
| POST | DescribeEndpoints | / | Return regional endpoint information. |
| POST | DescribeLimits | / | Return your current provisioned-capacity quotas for your account in an AWS Region and for a table you create in it. |
| POST | DescribeTable | / | Get information about a table. |
| POST | DescribeTimeToLive | / | Get information about the time to live (TTL) status on a specified table. |
| POST | ExecuteStatement | / | Perform a read or singleton write on data using PartiQL. |
| POST | ExecuteTransaction | / | Perform transactional reads or writes on data using PartiQL. |
| POST | GetItem | / | Get a set of attributes for an item in your data. |
| POST | GetResourcePolicy | / | Get a resource-based IAM policy attached to a resource, such as a table or stream. |
| POST | ListBackups | / | List backups for a table. |
| POST | ListGlobalTables | / | List all global tables that have a replica in the specified Region. |
| POST | ListTables | / | List table names associated with an account and endpoint. |
| POST | ListTagsOfResource | / | List the tags for a DynamoDB resource. |
| POST | PutItem | / | Create or update an item in a table. |
| POST | PutResourcePolicy | / | Attach a resource-based IAM policy to a resource, such as a table or stream. |
| POST | Query | / | Return the results for a database query. |
| POST | Scan | / | Return items and item attributes by accessing every item in a table or secondary index. |
| POST | TagResource | / | Add a tag to a DynamoDB resource. |
| POST | TransactGetItems | / | Retrieve items from one or more tables in the same account and Region. |
| POST | TransactWriteItems | / | Carry out the specified action on items in one or more tables in the same account and Region. |
| POST | UntagResource | / | Remove a tag from a DynamoDB resource. |
| POST | UpdateItem | / | Modify an item’s attributes or add the item to the table if it doesn’t exist. |
| POST | UpdateTable | / | Modify provisioned throughput settings, global secondary indexes, or DynamoDB Streams settings for a table. |
### Asana
The following list provides key information for this template
+ Server URL – https://app.asana.com/api/1.0
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | createTask | /tasks | Create new task in workspace |
| PUT | updateTask | /tasks/ `{task_gid}` | Update existing task details |
### BambooHR
The following list provides key information for this template
+ Server URL – https://api.bamboohr.com/api/gateway.php/ `{companyDomain}`
+ Outbound authentication types accepted:
+ OAuth2
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | getCompanyInformation | /v1/company\$1information | View company details |
| GET | getCompanyEINs | /v1/company\$1eins | View company tax IDs |
| GET | getEmployee | /v1/employees/ `{employeeId}` | Retrieve employee information |
| POST | updateEmployee | /v1/employees/ `{employeeId}` | Update employee information |
| POST | addEmployee | /v1/employees | Add new employee with basic info |
| GET | getEmployeesDirectory | /v1/employees/directory | View employee directory |
| GET | getTimeOffTypes | /v1/meta/time\$1off/types | View types of time off |
| GET | getTimeOffPolicies | /v1/meta/time\$1off/policies | View time off policy list |
| GET | getTimeOffRequests | /v1/time\$1off/requests | View time off requests |
| PUT | addTimeOffRequest | /v1/employees/ `{employeeId}` /time\$1off/request | Submit time off request |
| PUT | changeRequestStatus | /v1/time\$1off/requests/ `{requestId}` /status | Update time off request status |
| PUT | adjustTimeOffBalance | /v1/employees/ `{employeeId}` /time\$1off/balance\$1adjustment | Adjust employee time off balance |
| PUT | assignTimeOffPolicies | /v1\$11/employees/ `{employeeId}` /time\$1off/policies | Assign employee time off policies |
| GET | listTimeOffPolicies | /v1/employees/ `{employeeId}` /time\$1off/policies | View time off policies |
| GET | estimateFutureTimeOffBalances | /v1/employees/ `{employeeId}` /time\$1off/calculator | Calculate future time off estimates |
| GET | getWhosOutList | /v1/time\$1off/whos\$1out | See who’s on leave |
| GET | listEmployeeFiles | /v1/employees/ `{employeeId}` /files/view | View employee documents |
| POST | uploadEmployeeFile | /v1/employees/ `{employeeId}` /files | Upload Employee File |
| GET | getEmployeeTableRow | /v1/employees/ `{employeeId}` /tables/ `{table}` | Get employee table data |
### Brave Search
The following list provides key information for this template
+ Server URL – https://api.search.brave.com/res/v1
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | BraveWebSearch | /web/search | Performs a web search query |
### The Confluence Cloud REST API v2
The following list provides key information for this template
+ Server URL – https:// `{sub-domain}` .atlassian.net
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | getPages | /wiki/api/v2/pages | Get pages |
| POST | createPage | /wiki/api/v2/pages | Create page |
| PUT | updatePage | /wiki/api/v2/pages/ `{id}` | Update page |
| GET | getPageById | /wiki/api/v2/pages/ `{id}` | Get page by id |
| GET | searchByCQL | /wiki/rest/api/search | Search content |
| GET | getSpaces | /wiki/api/v2/spaces | Get spaces |
### The Jira Cloud platform
The following list provides key information for this template
+ Server URL – https://api.atlassian.com/ex/jira/ `{customerInstanceId}`
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | moveIssuesToBacklog | /rest/agile/1.0/backlog/issue | Move issues to backlog |
| GET | GetAllBoards | /rest/agile/1.0/board | Get boards |
| GET | getBoard | /rest/agile/1.0/board/ \$1 boardId\$1 | Get board |
| GET | getAllSprints | /rest/agile/1.0/board/ \$1 boardId\$1/sprint | Get all sprints |
| POST | createSprint | /rest/agile/1.0/sprint | Create sprint |
| DELETE | deleteSprint | /rest/agile/1.0/sprint/ \$1 sprintId\$1 | Delete sprint |
| GET | getSprint | /rest/agile/1.0/sprint/ \$1 sprintId\$1 | Get sprint |
| PUT | updateSprint | /rest/agile/1.0/sprint/ \$1 sprintId\$1 | Update sprint |
| POST | moveIssuesToSprintAndRank | /rest/agile/1.0/sprint/ \$1 sprintId\$1/issue | Move issues to sprint and rank |
| GET | getAttachmentContent | /rest/api/3/attachment/content/ `{id}` | Get attachment content |
| POST | createIssue | /rest/api/3/issue | Create an issue |
| PUT | editIssue | /rest/api/3/issue/ \$1 issueIdOrKey\$1 | Edit issue |
| GET | getIssue | /rest/api/3/issue/ \$1 issueIdOrKey\$1 | Get issue |
| DELETE | deleteIssue | /rest/api/3/issue/ \$1 issueIdOrKey\$1 | Delete issue |
| POST | addAttachment | /rest/api/3/issue/ \$1 issueIdOrKey\$1/attachments | Add attachment |
| GET | getComments | /rest/api/3/issue/ \$1 issueIdOrKey\$1/comment | Get comments |
| POST | addComment | /rest/api/3/issue/ \$1 issueIdOrKey\$1/comment | Add comment |
| DELETE | deleteComment | /rest/api/3/issue/ \$1 issueIdOrKey\$1/comment/ `{id}` | Delete comment |
| PUT | updateComment | /rest/api/3/issue/ \$1 issueIdOrKey\$1/comment/ `{id}` | Update comment |
| GET | getTransitions | /rest/api/3/issue/ \$1 issueIdOrKey\$1/transitions | Get transitions |
| POST | DoTransition | /rest/api/3/issue/ \$1 issueIdOrKey\$1/transitions | Transition issue |
| GET | getIssueTypesForProject | /rest/api/3/issuetype/project | Get issue types for project |
| GET | getAllLabels | /rest/api/3/label | Get all labels |
| GET | getPriorities | /rest/api/3/priority | Get priorities |
| POST | createProject | /rest/api/3/project | Create project |
| GET | listProjects | /rest/api/3/project | Get all projects |
| GET | searchProjects | /rest/api/3/project/search | Get projects paginated |
| DELETE | deleteProject | /rest/api/3/project/ \$1 projectIdOrKey\$1 | Delete project |
| GET | getProject | /rest/api/3/project/ \$1 projectIdOrKey\$1 | Get project |
| PUT | updateProject | /rest/api/3/project/ \$1 projectIdOrKey\$1 | Update project |
| GET | searchStatuses | /rest/api/3/statuses/search | Search statuses paginated |
| GET | SearchIssues | /rest/api/3/search/jql | Search for issues using JQL enhanced search (GET) |
| GET | getAllUsers | /rest/api/3/users | Get all users default |
| GET | findUsers | /rest/api/3/user/search | Find users |
### Microsoft Exchange
The following list provides key information for this template
+ Server URL – https://graph.microsoft.com/v1.0
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | sendUserEmail | /users/ `{userId}` /microsoft.graph.sendMail | Send Email |
| GET | listUserMails | /users/ `{userId}` /messages | Get messages from users |
| GET | ListFolderMessage | /users/ `{userId}` /mailFolders/ `{mailFolderId}` /messages | Get messages from users |
| GET | getEmailById | /users/ `{userId}` /messages/ `{messageId}` | Get messages from users |
| PATCH | updateEmail | /users/ `{userId}` /messages/ `{messageId}` | Update the navigation property messages in users |
| DELETE | deleteEmail | /users/ `{userId}` /messages/ `{messageId}` | Delete navigation property messages for users |
| POST | moveEmailToFolder | /users/ `{userId}` /messages/ `{messageId}` /move | Move Email to Folder |
| POST | forwardUserEmail | /users/ `{userId}` /messages/ `{messageId}` /forward | Forward User Email |
| POST | replyToEmail | /users/ `{userId}` /messages/ `{messageId}` /reply | Reply to a message |
| GET | listEmailAttachment | /users/ `{userId}` /messages/ `{messageId}` /attachments | Get attachments from users |
| GET | getAttachmentById | /users/ `{userId}` /messages/ `{messageId}` /attachments/ `{attachmentId}` | Get attachments from users |
| GET | listCalendarEvents | /users/ `{userId}` /calendar/events | Get events from users |
| POST | createCalendarEvent | /users/ `{userId}` /calendar/events | Create new navigation property to events for users |
| PATCH | updateCalendarEvent | /users/ `{userId}` /calendar/events/ `{eventId}` | Update the calender events in users |
| POST | findMeetingTimes | /users/ `{userId}` /findMeetingTimes | Suggest meeting times and locations |
| GET | listMailFolders | /users/ `{userId}` /mailFolders | Get mailFolders from users |
| GET | listContacts | /users/ `{userId}` /contacts | Get contacts from users |
| GET | listUsers | /users | List users |
| GET | getUser | /users/ `{userId}` | Get a user |
| GET | getMailboxSettings | /users/ `{userId}` /mailboxSettings | Get current mailbox settings of the user. |
| GET | listPlaces | /places/microsoft.graph.room | List places |
### Microsoft OneDrive
The following list provides key information for this template
+ Server URL – https://graph.microsoft.com/v1.0
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | getUser | /users/ `{userId}` | Get a user |
| GET | getDrive | /users/ `{userId}` /drive | Get drive from users |
| GET | listItem | /users/ `{userId}` /drive/root/children | Get items from users |
| POST | createItem | /users/ `{userId}` /drive/root/children | Create new navigation property to items for users |
| GET | getItem | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` | Get items from users |
| PATCH | updateItem | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` | Update file or folder metadata |
| DELETE | deleteItem | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` | Delete navigation property items for users |
| GET | listChildren | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /children | Get children from users |
| POST | copyItem | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /copy | Copy item within a drive |
| POST | addPermisions | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /invite | Add permission |
| PUT | uploadFile | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` :/ `{fileName}` :/content | Upload new file |
| POST | addSheet | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/add | Add worksheet |
| GET | readSheet | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` | Get worksheets from drives |
| PATCH | updateSheet | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` | Update worksheet |
| DELETE | deleteSheet | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` | Delete worksheet |
| GET | readCell | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /cell(row= `{row}` ,column= `{column}` ) | Read cell within a sheet |
| PATCH | writeCell | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /cell(row= `{row}` ,column= `{column}` ) | Write cell within a sheet |
| GET | readRange | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ') | Read range |
| PATCH | writeRange | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ') | Write range |
| POST | deleteRange | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ')/delete | Delete Range within a sheet |
| GET | listSheets | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets | Get worksheets from drives |
| GET | readUsedRange | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /usedRange | Read used range of a sheet |
| POST | clearRange | /users/ `{userId}` /drives/ `{driveId}` /items/ `{driveItemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ')/clear | Clear range within a sheet |
### Microsoft SharePoint
The following list provides key information for this template
+ Server URL – https://graph.microsoft.com/v1.0
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | listSites | /sites | Search for sites |
| GET | getSite | /sites/ `{siteId}` | Get a site resource |
| GET | listLists | /sites/ `{siteId}` /lists | Get lists in a site |
| GET | getList | /sites/ `{siteId}` /lists/ `{listId}` | List operations on a list |
| GET | listItem | /sites/ `{siteId}` /lists/ `{listId}` /items | Enumerate items in a list |
| POST | createItem | /sites/ `{siteId}` /lists/ `{listId}` /items | Create a new item in a list |
| GET | getItem | /sites/ `{siteId}` /lists/ `{listId}` /items/ `{listItemId}` | Get listItem |
| PATCH | updateItem | /sites/ `{siteId}` /lists/ `{listId}` /items/ `{listItemId}` | Update the navigation property items in sites |
| DELETE | deleteItem | /sites/ `{siteId}` /lists/ `{listId}` /items/ `{listItemId}` | Delete an item from a list |
| POST | addSheet | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/add | Add worksheet |
| GET | readSheet | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` | Read a sheet |
| DELETE | deleteSheet | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` | Delete a new sheet |
| PATCH | updateSheet | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` | Update worksheet |
| GET | listSheets | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets | List worksheet collection |
| PUT | uploadFile | /sites/ `{siteId}` /drive/items/ `{parentId}` :/ `{fileName}` :/content | Create or upload a file |
| GET | readCell | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /cell(row= `{row}` ,column= `{column}` ) | Read cell |
| PATCH | writeCell | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /cell(row= `{row}` ,column= `{column}` ) | Write cell |
| GET | readRange | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ') | Read range |
| PATCH | writeRange | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ') | Write range |
| POST | deleteRange | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ')/delete | Delete range |
| POST | clearRange | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /range(address=' `{address}` ')/clear | Clear range |
| GET | getUsedRange | /sites/ `{siteId}` /drive/items/ `{itemId}` /workbook/worksheets/ `{worksheetIdOrName}` /usedRange | Get used range |
### Microsoft Teams
The following list provides key information for this template
+ Server URL – https://graph.microsoft.com/v1.0
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | listChats | /chats | List chats |
| POST | CreateChat | /chats | Create a new chat object |
| GET | GetIndividualChat | /chats/ `{chatId}` | Get chat |
| GET | ListAllChatMessages | /chats/ `{chatId}` /messages | List messages in a chat |
| POST | SendChatMessage | /chats/ `{chatId}` /messages | Send a message in a chat |
| GET | listTeams | /teams | List teams |
| GET | GetTeam | /teams/ `{teamId}` | Get team |
| GET | ListAllChannels | /teams/ `{teamId}` /channels | List channels |
| POST | CreateChannel | /teams/ `{teamId}` /channels | Create channel |
| GET | GetChannel | /teams/ `{teamId}` /channels/ `{channelId}` | Get channel |
| POST | InviteChannelMember | /teams/ `{teamId}` /channels/ `{channelId}` /members | Add conversationMember |
| GET | ListAllChannelMessages | /teams/ `{teamId}` /channels/ `{channelId}` /messages | List channel messages |
| POST | SendChannelMessage | /teams/ `{teamId}` /channels/ `{channelId}` /messages | Send a message in a channel |
| POST | ReplyToChannelMessage | /teams/ `{teamId}` /channels/ `{channelId}` /messages/ `{chatMessageId}` /replies | Reply to a message in a channel |
| GET | ListAllTeamMembers | /teams/ `{teamId}` /members | List members of team |
| POST | InviteUserToTeam | /teams/ `{teamId}` /members | Add member to team |
| GET | listUsers | /users | List users |
| GET | getUser | /users/ `{userId}` | Get a user |
| POST | CreateOnlineTeamsMeeting | /users/ `{userId}` /onlineMeetings | Create an online meeting. |
| GET | GetOnlineTeamsMeeting | /users/ `{userId}` /onlineMeetings/ `{meetingId}` | Get an online meeting. |
| GET | ListAllRecordings | /users/ `{userId}` /onlineMeetings/ `{meetingId}` /recordings | List all recordings. |
| GET | ListAllTranscripts | /users/ `{userId}` /onlineMeetings/ `{meetingId}` /transcripts | List all transcripts. |
### PagerDuty Advance
The following list provides key information for this template
+ Server URL – https://api.pagerduty.com
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | listIncidents | /incidents | View incidents in my account |
| POST | createIncident | /incidents | Create new incident |
| GET | getIncident | /incidents/ `{id}` | View incident details |
| PUT | updateIncident | /incidents/ `{id}` | Update an incident |
| GET | listUsers | /users | View user list |
### Salesforce Lightning Platform
The following list provides key information for this template
+ Server URL – https:// `{domainName}` .develop.my.salesforce.com/services/data/v60.0
+ Outbound authentication types accepted:
+ OAUTH2
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | getAccountList | /sobjects/Account | View all accounts |
| POST | createAccount | /sobjects/Account | Create new account |
| GET | getAccount | /sobjects/Account/ `{id}` | Get account details |
| DELETE | deleteAccount | /sobjects/Account/ `{id}` | Remove account |
| PATCH | updateAccount | /sobjects/Account/ `{id}` | Edit account details |
| POST | createAccountTeamMember | /sobjects/AccountTeamMember | Add account team member |
| GET | getAccountTeamMember | /sobjects/AccountTeamMember/ `{id}` | View account team member |
| DELETE | deleteAccountTeamMember | /sobjects/AccountTeamMember/ `{id}` | Remove account team member |
| GET | getCaseList | /sobjects/Case | View all cases |
| POST | createCase | /sobjects/Case | Create new case |
| GET | getCase | /sobjects/Case/ `{id}` | View case details |
| DELETE | deleteCase | /sobjects/Case/ `{id}` | Remove case |
| PATCH | updateCase | /sobjects/Case/ `{id}` | Edit case |
| GET | getCampaignList | /sobjects/Campaign | View all campaigns |
| POST | createCampaign | /sobjects/Campaign | Create new campaign |
| GET | getCampaign | /sobjects/Campaign/ `{id}` | Get campaign details |
| DELETE | deleteCampaign | /sobjects/Campaign/ `{id}` | Remove campaign |
| PATCH | updateCampaign | /sobjects/Campaign/ `{id}` | Edit campaign |
| POST | createCampaignMember | /sobjects/CampaignMember | Add campaign member |
| GET | getCampaignMember | /sobjects/CampaignMember/ `{id}` | Get campaign member details |
| DELETE | deleteCampaignMember | /sobjects/CampaignMember/ `{id}` | Remove campaign member |
| GET | getContactList | /sobjects/Contact | View all contacts |
| POST | createContact | /sobjects/Contact | Create new contact |
| GET | getContact | /sobjects/Contact/ `{id}` | Get contact information |
| DELETE | deleteContact | /sobjects/Contact/ `{id}` | Remove contact |
| PATCH | updateContact | /sobjects/Contact/ `{id}` | Edit contact |
| POST | createFeedItem | /sobjects/FeedItem | Create new feed item |
| GET | getFeedItem | /sobjects/FeedItem/ `{id}` | View feed item |
| DELETE | deleteFeedItem | /sobjects/FeedItem/ `{id}` | Remove feed item |
| PATCH | updateFeedItem | /sobjects/FeedItem/ `{id}` | Edit feed item |
| GET | getLeadList | /sobjects/Lead | View all leads |
| POST | createLead | /sobjects/Lead | Create new lead |
| GET | getLead | /sobjects/Lead/ `{id}` | Get lead details |
| DELETE | deleteLead | /sobjects/Lead/ `{id}` | Remove lead |
| PATCH | updateLead | /sobjects/Lead/ `{id}` | Edit lead details |
| GET | getOpportunityList | /sobjects/Opportunity | View list of opportunities |
| POST | createOpportunity | /sobjects/Opportunity | Create new opportunity |
| GET | getOpportunity | /sobjects/Opportunity/ `{id}` | View opportunity details |
| DELETE | deleteOpportunity | /sobjects/Opportunity/ `{id}` | Remove opportunity |
| PATCH | updateOpportunity | /sobjects/Opportunity/ `{id}` | Edit opportunity |
| GET | getUser | /sobjects/User | View user details |
| GET | describeSObject | /sobjects/ `{sObject}` /describe | Get object metadata and field details |
| GET | queryAccounts | /query | Executes a SOQL query to retrieve account data from Salesforce |
### ServiceNow
The following list provides key information for this template
+ Server URL – https:// `{instance}` .service-now.com
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | retrieveAttachmentsMetadata | /api/now/attachment | Get all attachments info |
| POST | uploadBinaryAttachment | /api/now/attachment/file | Upload binary file |
| GET | retrieveAttachmentMetadata | /api/now/attachment/ `{sys_id}` | Get attachment info |
| DELETE | deleteAttachment | /api/now/attachment/ `{sys_id}` | Remove attachment |
| GET | retrieveAttachmentContent | /api/now/attachment/ `{sys_id}` /file | Get attachment content |
| GET | listIncidents | /api/now/table/incident | View all incidents |
| POST | createIncident | /api/now/table/incident | Create new incident |
| GET | getIncident | /api/now/table/incident/ `{sys_id}` | View incident details |
| PATCH | updateIncident | /api/now/table/incident/ `{sys_id}` | Edit incident |
| DELETE | deleteIncident | /api/now/table/incident/ `{sys_id}` | Remove incident |
| GET | listProblem | /api/now/table/problem | View all problems |
| POST | createProblem | /api/now/table/problem | Create new problem |
| GET | getProblem | /api/now/table/problem/ `{sys_id}` | View problem details |
| DELETE | deleteProblem | /api/now/table/problem/ `{sys_id}` | Remove problem |
| PATCH | updateProblem | /api/now/table/problem/ `{sys_id}` | Edit problem |
| POST | createKnowledgeBaseArticle | /api/now/table/kb\$1knowledge | Create KB article |
| DELETE | deleteKnowledgeBaseArticle | /api/now/table/kb\$1knowledge/ `{sys_id}` | Remove KB article |
| PATCH | updateKnowledgeBaseArticle | /api/now/table/kb\$1knowledge/ `{sys_id}` | Edit KB article |
| GET | listChoices | /api/now/table/sys\$1choice | View all system choices |
| GET | listUsers | /api/now/table/sys\$1user | View all users |
| GET | listChangeRequest | /api/sn\$1chg\$1rest/change | View all change requests |
| POST | createChangeRequest | /api/sn\$1chg\$1rest/change | Create new change request |
| GET | getChangeRequest | /api/sn\$1chg\$1rest/change/ `{sys_id}` | View change request details |
| DELETE | deleteChangeRequest | /api/sn\$1chg\$1rest/change/ `{sys_id}` | Remove change request |
| PATCH | updateChangeRequest | /api/sn\$1chg\$1rest/change/ `{sys_id}` | Edit change request |
### Slack Web
The following list provides key information for this template
+ Server URL – https://slack.com/api
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | chatPostEphemeral | /chat.postEphemeral | Send temporary message |
| POST | chatPostMessage | /chat.postMessage | Send new message |
| POST | conversationsCreate | /conversations.create | Start new channel |
| GET | conversationsHistory | /conversations.history | View message history |
| POST | conversationsInvite | /conversations.invite | Add users to channel |
| POST | conversationsJoin | /conversations.join | Enter existing conversation |
| POST | conversationsKick | /conversations.kick | Remove user from chat |
| POST | conversationsLeave | /conversations.leave | Exit conversation |
| GET | conversationsList | /conversations.list | View all channels |
| GET | conversationsMembers | /conversations.members | View chat participants |
| POST | conversationsOpen | /conversations.open | Start or resume direct message |
| GET | conversationsReplies | /conversations.replies | View message thread |
| POST | conversationsSetTopic | /conversations.setTopic | Set chat topic |
| GET | filesList | /files.list | List for a team, in a channel, or from a user with applied filters. |
| GET | filesInfo | /files.info | View file details |
| GET | searchAll | /search.all | Search messages and files |
| POST | userGroupsCreate | /usergroups.create | Create new user group |
| GET | userGroupsList | /usergroups.list | View all user groups |
| POST | userGroupsUsersUpdate | /usergroups.users.update | Edit user group |
| GET | usersList | /users.list | View team members |
| POST | remindersAdd | /reminders.add | Set new reminder |
| POST | usersProfileSet | /users.profile.set | Update user profile |
| GET | GetUploadURLExternal | /files.getUploadURLExternal | Get an upload URL for a file to be uploaded externally to Slack. |
| POST | completeUploadExternal | /files.completeUploadExternal | Finalize file upload to Slack. Should be used after Upload File. |
### Smartsheet
The following list provides key information for this template
+ Server URL – https://api.smartsheet.com/2.0
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | listSearch | /search | Search all sheets |
| GET | getSheet | /sheets/ `{sheetId}` | View sheet details |
| GET | listReports | /reports | View all reports |
| GET | getReport | /reports/ `{reportId}` | View report information |
### Tavily Search
The following list provides key information for this template
+ Server URL – https://api.tavily.com
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| POST | TavilySearchPost | /search | ExecuteasearchqueryusingTavilySearch |
| POST | TavilySearchExtract | /extract | ExtractwebpagecontentfromURLsusingTavilyExtract |
### Zendesk Suite
The following list provides key information for this template
+ Server URL – https:// `{customerInstanceId}` .zendesk.com
+ Outbound authentication types accepted:
+ OAUTH2
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | listSearchResults | /api/v2/search | List Search Results |
| GET | listTickets | /api/v2/tickets | List Tickets |
| POST | createTicket | /api/v2/tickets | Create Ticket |
| GET | showTicket | /api/v2/tickets/ `{ticket_id}` | Show Ticket |
| PUT | updateTicket | /api/v2/tickets/ `{ticket_id}` | Update Ticket |
| GET | ListTicketEmailCCs | /api/v2/tickets/ `{ticket_id}` /email\$1ccs | List Email CCs for a Ticket |
| GET | ListTicketFollowers | /api/v2/tickets/ `{ticket_id}` /followers | List Followers for a Ticket |
| GET | ListTicketIncidents | /api/v2/tickets/ `{ticket_id}` /incidents | List Ticket Incidents |
| GET | TicketRelatedInformation | /api/v2/tickets/ `{ticket_id}` /related | Ticket Related Information |
### Zoom
The following list provides key information for this template
+ Server URL – https://api.zoom.us/v2
+ Outbound authentication types accepted:
+ API key
The following table shows the APIs that you can call if you add this target type to your gateway:
| REST API type | Operation name | REST API path | Description |
| --- | --- | --- | --- |
| GET | recordingsList | /users/ `{userId}` /recordings | List all recordings |
| GET | meeting | /meetings/ `{meetingId}` | Get a meeting |
| GET | meetings | /users/ `{userId}` /meetings | List meetings |
| POST | meetingCreate | /users/ `{userId}` /meetings | Create a meeting |
| GET | recordingGet | /meetings/ `{meetingId}` /recordings | Get meeting recordings |
# Understand how AgentCore Gateway tools are named
The name of a tool in your gateway is dependent on the name of the target through which the tool can be accessed. Tool names are constructed in the following pattern:
```
${target_name}___${tool_name}
```
For example, if your target’s name is `LambdaUsingSDK` and you have a tool named `get_order_tool` that is accessible at that target, the tool name that is visible through the Model Context Protocol (MCP) is `LambdaUsingSDK___get_order_tool`.
You should ensure that your application code accounts for the discrepancy between the tool name visible through the MCP and the tool name itself.
For an example of a Lambda handler function that strips the target name prefix from the tool name before passing it to a handler function, see [Lambda function input format](gateway-add-target-lambda.md#gateway-building-lambda-input).
# Prerequisites for using the Amazon Bedrock AgentCore gateway service
To interact with the AgentCore Gateway service, you’ll need to complete the following prerequisites:
**Prerequisites for using the AgentCore Gateway service**
1. Install and set up the tools that you wish to use and ensure that you have the necessary permissions to use AgentCore Gateway methods and access AgentCore Gateway resources.
1. Set up and retrieve your AWS credentials. To access your AWS credentials and configure them, follow the steps at [Using IAM Identity Center to authenticate AWS SDK and Tools](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) . You need AWS credentials for the following tools:
1. Ensure you have the necessary permissions to perform AgentCore Gateway-related API operations and access AgentCore Gateway resources.
1. Set up inbound authorization to authenticate requests made to your gateway.
1. Set up at least one target for your gateway.
1. Set up outbound authorization to authenticate access to your gateway targets.
The following topics describe where you can find information about setting up the tools that you can use to interact with the AgentCore Gateway service.
**Topics**
+ [
# Set up dependencies and credentials to create, maintain, and use gateway resources
](gateway-setup-tools-credentials.md)
+ [
# Set up permissions for AgentCore Gateway
](gateway-prerequisites-permissions.md)
+ [
# Set up inbound authorization for your gateway
](gateway-inbound-auth.md)
+ [
# Set up outbound authorization for your gateway
](gateway-outbound-auth.md)
# Set up dependencies and credentials to create, maintain, and use gateway resources
The AgentCore Gateway service involves the following main processes:
+ **Creation and maintenance of gateway resources** – You can create gateway and gateway target resources through the Amazon Bedrock AgentCore Control Plane service.
+ **Invocation of gateways** – After creating a gateway and gateway target, you can invoke the gateway through direct HTTP requests to the gateway or through the help of an MCP client or agent.
Select a topic to learn about setting up tools and credentials for carrying out these processes:
**Topics**
+ [
## Set up tools and credentials for the creation and maintenance of gateway resources
](#gateway-setup-control-plane)
+ [
## Invocation of gateways
](#gateway-setup-data-plane)
## Set up tools and credentials for the creation and maintenance of gateway resources
You create, modify, delete, and retrieve information about gateway and gateway target resources through making calls to the Amazon Bedrock AgentCore Control Plane service. The [Amazon Bedrock AgentCore Control Plane service API reference](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html) details information about the API operations and structures in this service.
You can interact with the Amazon Bedrock AgentCore Control Plane service in the following ways. Expand a topic to learn how to install the tool and set up authentication for it.
### AWS Management Console
The AWS Management Console lets you create and maintain gateway and gateway target resources through an interactive graphical interface in a web browser.
+ **Installation** – None needed. To manage gateways through the AgentCore console, you can navigate to [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#) and select **Gateways** from the left navigation pane.
+ **Authentication** – Sign in with an IAM identity with permissions to use AgentCore Gateway actions.
### Direct HTTP requests
The [Amazon Bedrock AgentCore Control Plane service API reference](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html) page for each API operations provides the information you need to make an API request.
+ **Installation** – None needed.
+ **Authentication** – You can use the [Authorization header](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) or query parameters (using [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) ) to authenticate.
### AWS software development kits SDKs
AWS SDKs let you make API requests to AWS services through a programming language of your choice. Refer to the following resources in the [AWS SDKs and Tools Reference Guide](https://docs.aws.amazon.com/sdkref/latest/guide/overview.html) to get set up:
+ **Installation** – To learn about an SDK and how to install it, select the ** AWS SDK for** link that corresponds to your programming language of choice.
+ **Authentication** – To learn about configuring SDKs and authentication, refer to the links in the **This guide’s relevant sections for you are:** column.
+ **Other resources** – In the language-specific reference, search for the Amazon Bedrock AgentCore Core Control service to see the syntax of specific API methods.
### AWS Command Line Interface
The AWS Command Line Interface (CLI) lets you interact with the AWS API in a command line interface. To learn how to install and set up the AWS CLI, see [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/).
+ **Installation** – To learn how to install the AWS CLI see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com//cli/latest/userguide/getting-started-install.html).
+ **Authentication** – To learn about configuring your credentials in the AWS CLI see [Setting up the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html).
+ **Other resources** – To see the syntax of specific API methods in the Amazon Bedrock AgentCore control plane service, see the [bedrock-agentcore-control](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/) reference.
### AgentCore CLI
The AgentCore CLI is a Node.js command-line tool for interacting with the AgentCore API. Refer to the following resources in the [AgentCore CLI repository](https://github.com/aws/agentcore-cli).
+ **Installation** – To install the AgentCore CLI, run the following command:
```
npm install -g @aws/agentcore
```
+ **Authentication** – To access your AWS credentials and configure them for the AgentCore CLI, follow the steps at [Using IAM Identity Center to authenticate AWS SDK and Tools](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html).
+ **Other resources** – For more information about using the AgentCore CLI to interact with AgentCore Gateway, see the [AgentCore CLI repository](https://github.com/aws/agentcore-cli).
## Invocation of gateways
After you create a gateway and gateway targets, you can interact with the gateway through direct HTTP requests or through an MCP client or agent.
### Direct HTTP requests
To make an HTTP request to an AgentCore gateway, you make a POST request to a gateway endpoint that you set up when creating a gateway.
+ **Installation** – None needed.
+ **Authentication** – You can use the [Authorization header](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) or query parameters (using [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) ) to authenticate.
### MCP client
To interact with an AgentCore gateway using an MCP client, you need to install the MCP client by following the **Setting up your environment** and **Setting up your API key** steps at [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) after choosing your programming language of choice. By following the steps, you’ll also retrieve an Anthropic API key for authentication.
### Strands Agents SDK
To interact with an AgentCore gateway using the Strands Agents SDK, you need to install the Strands SDK by following the steps at [Strands Agents SDK](https://strandsagents.com/latest/documentation/docs/) to install the SDK and set up credentials.
### Langgraph agent
To interact with an AgentCore gateway using a Langgraph agent, you need to install Langgraph by navigating to [LangGraph](https://www.langchain.com/langgraph) , selecting **Docs** , and choosing the **LangGraph** page that corresponds to your programming language of choice. By following these steps, you’ll also receive an API key to help set up your credentials.
# Set up permissions for AgentCore Gateway
To use Amazon Bedrock AgentCore Gateway and its capabilities, you’ll need to consider the following permissions:
1. **Gateway builder/user permissions** – Permissions provided to a gateway builder or user to allow it to create, manage, and or use AgentCore gateways.
1. **Gateway service role permissions** – Permissions provided to a service role that you’ll create for your gateway. These permissions allow the Amazon Bedrock AgentCore service to perform actions on behalf of the identity that invokes the gateway.
1. **Resource-based permissions** – Permissions attached to resources to allow the gateway service role to access it. You’ll include the Amazon Resource Name (ARN) of the gateway service role as the `Principal` in the resource-based policy.
1. **Gateway resource-based policies** – Policies attached directly to your gateway resources to control which principals can invoke them. For more information, see [Resource-based policies for Amazon Bedrock AgentCore](security.md#resource-based-policies).
**Note**
If you prefer not to set up custom permissions, you can use the following options for easy setup: \$1 Attach the [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html) to an IAM identity to allow it to create, manage, and invoke gateways. \$1 Use the AWS Management Console or AgentCore CLI to create an AgentCore gateway service role with the proper permissions and gateway targets with the proper resource-based policies to allow the service role to access them.
Select a topic to learn more:
**Topics**
+ [
## Gateway builder and user permissions
](#gateway-user-permissions)
+ [
## AgentCore Gateway service role permissions
](#gateway-service-role-permissions)
+ [
## Best practices for Gateway permissions
](#gateway-prerequisites-best-practices)
## Gateway builder and user permissions
For an identity to be able to create, manage, or use gateways, you need to attach an identity-based policy to the IAM identity to allow it to perform [Amazon Bedrock AgentCore-related actions](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html) . For comprehensive permissions, you can use the [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html) managed policy.
For greater security and control, you can create your own custom policy by reducing the permissions in the full access policy. For example, the following policy allows an identity to perform actions related to AgentCore Gateway but not to other AgentCore services, such as AgentCore Runtime or AgentCore Browser:
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:*Gateway*",
"bedrock-agentcore:*WorkloadIdentity",
"bedrock-agentcore:*CredentialProvider",
"bedrock-agentcore:*Token*",
"bedrock-agentcore:*Access*"
],
"Resource": "arn:aws:bedrock-agentcore:*:*:*gateway*"
}
]
}
```
The following custom policy is a more restrictive one that only allows read access to gateways and gateway targets
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"bedrock-agentcore:ListGateways",
"bedrock-agentcore:GetGateway",
"bedrock-agentcore:ListGatewayTargets",
"bedrock-agentcore:GetGatewayTarget"
],
"Resource": "arn:aws:bedrock-agentcore:*:*:*gateway*"
}
]
}
```
### Gateway access permissions (inbound authorization)
In addition to gateway-related permissions, you’ll also need to configure permissions for identities to be able to access the gateway during invocation. You’ll configure these permissions when you [set up inbound authorization](gateway-inbound-auth.md).
## AgentCore Gateway service role permissions
When creating a gateway, you need a service role that has permissions to assume an IAM role and to access AWS resources and external services on the IAM role’s behalf. You can create the service role in the following ways:
+ If you create a gateway in the AWS Management Console or through the AgentCore CLI, you can choose to let AgentCore automatically create a service role for you with the necessary permissions. If you prefer this method, you can skip this prerequisite.
+ If you prefer to create your own service role for greater customization, you’ll need to configure the role with the permissions outlined in this topic. To learn how to create a service role and attach permissions to it, see [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-service.html).
The required permissions for a service role are in the following topics:
**Topics**
+ [
### Trust permissions
](#gateway-service-role-permissions-trust)
+ [
### Outbound authorization permissions
](#gateway-service-role-permissions-outbound-auth)
+ [
### Permissions to access AWS resources
](#gateway-service-role-permissions-resources)
### Trust permissions
A service role must have a [trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#term_trust_policy) attached that allows the AgentCore service to assume an IAM identity and carry out actions on its behalf.
The following is an example of a trust policy that you can use.
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "GatewayAssumeRolePolicy",
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/gateway-name-*"
}
}
}
]
}
```
**Note**
Because you won’t know the gateway ARN before you create it, you can omit the `Condition` field when you first create the service role. After you create the gateway, add the `Condition` field back to the policy as a best security practice and do the following: \$1 Replace the `aws:SourceAccount` condition key value with the ID of the account that the gateway belongs to. \$1 Replace the `aws:SourceArn` condition key with the ARN of the gateway.
### Outbound authorization permissions
Depending on the type of outbound authorization you use for your gateway targets, you need to add permissions to the service role to allow it to invoke the target. These permissions allow the gateway service role to retrieve authorization credentials for invoking the target. You can do this in the process of [setting up outbound authorization](gateway-outbound-auth.md).
### Permissions to access AWS resources
Depending on your gateway setup or the targets that you choose to add to the gateway, you might need to add permissions to the gateway service role to allow it to access AWS resources. The following topics cover some resources that your gateway service role might need access to:
#### Access a Lambda function
If you attach a Lambda target to your gateway, you need to add permissions for the AgentCore Gateway service role to be able to invoke the function by doing the following:
+ Attach an identity-based policy to the AgentCore Gateway service role that allows the `lambda:InvokeFunction` action on the Lambda function resource.
+ (If the function is in a different account from the gateway service role) Attach a resource-based policy to the Lambda function that allows the gateway service role principal to perform the `lambda:InvokeFunction` action on the Lambda function resource.
Select a topic to learn how to set up the permissions:
**Topics**
===== Attach an identity-based policy to the gateway service role
To allow the gateway service role to access a Lambda target, attach the following identity-based policy to your AgentCore Gateway service role by choosing the topic at [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) that pertains to your use case and following the steps..
```
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "AmazonBedrockAgentCoreGatewayLambdaProd",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:us-east-1:123456789012:function:FunctionName"
]
}]
}
```
Replace the ARN in the `Resource` field with the ARN of your Lambda function gateway target. If your gateway has multiple Lambda targets, you can add the ARN of each function to the `Resource` list.
===== (If function is in another account) Attach a resource-based policy to the Lambda function
If the Lambda function target is in a different account from the gateway service role, you need to attach a resource-based policy to allow the gateway service role to access it. The following is an example policy that you can use:
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "LambdaAllowGatewayServiceRoleMyFunction",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/MyGatewayExecutionRole"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-1:123456789012:function:MyFunction"
}
]
}
```
Replace the values of the following fields:
+ `AWS` – Use the ARN of your gateway service role.
+ `Resource` – Use the ARN of your Lambda function.
To learn how to attach a resource-based policy to the Lambda function that allows your gateway service role to access the function, select one of the following methods
------
#### [ Console ]
1. ====== To attach a resource-based policy to your Lambda function in the AWS Management Console
1. Follow the steps in the **Console** tab at [Viewing resource-based IAM policies in Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html).
1. In the **Resource-based policy statements** section, choose **Add permissions**.
1. Select ** AWS account** and fill out the following fields:
+ **Statement ID** – A unique identifier for the statement providing permissions for the gateway service role to access the function.
+ **Principal** – Specify the ARN of your gateway service role.
+ **Action** – Select `lambda:InvokeFunction`.
------
#### [ CLI ]
1. To attach a resource-based policy to your Lambda function using the AWS CLI, follow the steps at [Granting Lambda function access to AWS services](https://docs.aws.amazon.com/lambda/latest/dg/permissions-function-services.html) and specify your gateway service role as the `principal`.
You can run the following code in a terminal to add permissions for your gateway service role to access the function in *us-east-1* :
```
aws lambda add-permission \
--function-name "MyFunction" \
--statement-id "GatewayInvoke" \
--action "lambda:InvokeFunction" \
--principal "arn:aws:iam::123456789012:role/MyGatewayServiceRole"
--region us-east-1
```
------
**Example**
#### Access Amazon S3 objects
If you plan to include a gateway target tool definition from an Amazon S3 URI, you’ll need to include permissions for the gateway service role to access the bucket. The [AmazonS3ReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3ReadOnlyAccess.html) policy is an example of a policy that you can attach to the service role. You can scope the `Resource` to the S3 location for greater security.
#### Smithy model permissions
If you plan to add a Smithy target, you need to add permissions for the gateway service role to access AWS services that your Smithy models refer to. To determine which permissions need to be attached to the service role, refer to that service’s documentation.
You can add permissions to the service role by choosing the topic at [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) that pertains to your use case and following the steps.
For example, if your Smithy model target accesses a DynamoDB table, you can attach the following policy to allow the service role to perform DynamoDB operations on the table:
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:Query",
"dynamodb:Scan"
],
"Resource": "arn:aws:dynamodb:*:*:table/*"
}
]
}
```
## Best practices for Gateway permissions
**Follow the principle of least privilege**
+ Grant only the permissions necessary for your Gateway to function
+ Use specific resource ARNs rather than wildcards when possible
+ Regularly review and audit permissions
**Separate roles by function**
+ Use different roles for management and execution
+ Create separate roles for different Gateways with different purposes
**Secure credential storage**
+ Store API keys and OAuth credentials in AWS Secrets Manager
+ Rotate credentials regularly
**Monitor and audit**
+ Enable CloudTrail logging for Gateway operations
+ Regularly review access patterns and permissions usage
**Use conditions in policies**
+ Add conditions to limit when and how permissions can be used
+ Consider using source IP restrictions for management operations
# Set up inbound authorization for your gateway
Before you create your gateway, you must set up inbound authorization. Inbound authorization validates users who attempt to access targets through your AgentCore gateway. AgentCore supports the following types of inbound authorization:
+ **JSON Web Token (JWT)** – A secure and compact token used for authorization. After creating the JWT, you specify it as the authorization configuration when you create the gateway. You can create a JWT with any of the identity providers at [Provider setup and configuration](identity-idps.md).
+ **IAM identity** – Authorizes through the credentials of the AWS IAM identity trying to access the gateway.
+ **No Authorization** – The gateway will not perform any inbound authorization. This makes your gateway accessible to all users to be invoked.
**Important**
Do not use No Authorization gateways for production workloads. No Authorization gateways should only be used for testing and development purposes where security is not a primary concern.
**Note**
If you use the AWS Management Console or AgentCore CLI to create your gateway, you can create a default inbound authorization configuration using Amazon Cognito during gateway creation. If you plan to use the default authorization configuration, you can skip this prerequisite.
If you don’t plan to use the default authorization configuration using Amazon Cognito, select the topic that corresponds to the type of authorization that you plan to use to learn how to set it up:
**Topics**
+ [
## IAM-based inbound authorization
](#gateway-inbound-auth-iam)
+ [
## JSON Web Token (JWT)-based inbound authorization
](#gateway-inbound-auth-jwt)
+ [
## No Authorization
](#gateway-inbound-auth-none)
## IAM-based inbound authorization
IAM-based inbound authorization lets you use the gateway caller’s IAM credentials for authorization. You can use this option if you want to create an IAM identity through which users that call your gateway can be authenticated.
**To set up IAM-based inbound authorization**
1. Create or use an existing IAM identity for your gateway callers.
1. Create an identity-based IAM policy that contains the following permissions:
+ `bedrock-agentcore:InvokeGateway` – After you create the gateway, you should modify this policy such that the `Resource` field is scoped to the gateway that you create as a security best practice.
1. Attach the policy to the gateway caller identity.
**Example policy**
The following example shows a policy you could attach to an identity to allow it to invoke a gateway with the ID `my-gateway-12345`
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowGatewayInvocation",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:InvokeGateway"
],
"Resource": [
"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/my-gateway-12345"
]
}
]
}
```
**Resources**
+ For more information about AWS Identity and Access Management, see [Identity and access management for Amazon Bedrock AgentCore](security-iam.md).
+ For more information about Amazon Bedrock AgentCore actions, resources, and condition keys that you can specify in IAM policies, see [Actions, resources, and condition keys for Amazon Bedrock AgentCore](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html).
## JSON Web Token (JWT)-based inbound authorization
A JSON Web Token (JWT) is a secure and compact token used for authorization. You can create a JWT with a supported identity provider. After you create a JWT, you can retrieve it and specify it as the authorization configuration when you create the gateway.
**Important**
Using inbound authorization based on JWT tokens will result in logging of some claims of the JWT token in CloudTrail. The entry includes the [Subject](http://openid.net/specs/openid-connect-core-1_0.html#Claims) of the provided web identity token. We recommend that you avoid using any personally identifiable information (PII) in this field. For example, you could instead use a GUID or a pairwise identifier, as [suggested in the OIDC specification](http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes).
You can use the AgentCore CLI to set up a default JWT, or create one manually with a supported identity provider. To learn more about different methods for setting up a JWT, select from the following topics:
**Topics**
+ [
### Set up a default JWT
](#gateway-inbound-auth-jwt-default)
+ [
### Set up a JWT manually
](#gateway-inbound-auth-jwt-manual)
### Set up a default JWT
The AgentCore CLI lets you easily create a default authorization configuration using Amazon Cognito that you can then use when creating a gateway. When you run `agentcore create` , the CLI prompts you to configure inbound authorization and can automatically set up a Amazon Cognito user pool for you.
```
agentcore create
```
After the command completes, the AgentCore CLI provides authentication and authorization information:
+ You’ll use the authorizer configuration when you create the gateway.
+ For inbound authorization when invoking your gateway, you’ll need to obtain an access token by using your client ID, client secret, and the token endpoint. For more information on how to obtain your access token, see the **Example** at [Use an AgentCore gateway](gateway-using.md) or [The token issuer endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html) in the Amazon Cognito Developer Guide.
### Set up a JWT manually
Amazon Bedrock AgentCore supports JWTs from all identity providers. You can see some examples at [Provider setup and configuration](identity-idps.md).
In the process of creating the JWT, take note of the following values, which you’ll fill out in the [CustomJWTAuthorizerConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CustomJWTAuthorizerConfiguration.html) when you create a gateway, if they’re applicable to your use case:
+ **Discovery URL** – The URL from which login credentials and the token endpoint can be retrieved.
+ **Client ID** – The public identifier of a client application that requests a token, validated against the `client_id` claim.
+ **Client secret** – The private key that authenticates access for the client application to retrieve a token.
+ **Allowed audience** – The identifier that validates the intended recipients or consumers of a token via the `aud` claim.
+ **Allowed scopes** – The scopes that define the limitations of an application’s access to a user’s account. For more information, see [OAuth Scopes](https://oauth.net/2/scope/).
+ **Other required claim values** – Depending on the authorizer you use, you might need to specify required custom claim fields and rules to match the claim field value to for authentication.
You’ll need these values to do the following:
+ Create the gateway by specifying values in the [authorizer configuration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_AuthorizerConfiguration.html).
+ Obtain authorization credentials to invoke the gateway. To learn how to obtain your credentials, look up your identity provider’s documentation. For example, if you used Amazon Cognito, see [The token issuer endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html) in the Amazon Cognito Developer Guide.
## No Authorization
You can create a gateway that is configured with no authorization by using `authorizerType=NONE` . The gateway will not perform any authorization on the incoming gateway request and the request can be unauthenticated.
**Important**
Do not use No Authorization gateways for production workloads unless you have implemented all the security best practices listed below. No Authorization gateways are most appropriate for testing and development purposes.
**Security Best Practices**
1. Use the `bedrock-agentcore:GatewayAuthorizerType` condition key to selectively allow/deny access within your organization for creating gateways with `authorizerType=NONE`
1. Do not use No Authorization gateways out of convenience for testing. They should be used for gateways you intend to make public but have implemented your own custom throttling rules and checks to ensure your public gateway can handle unauthenticated users
1. Do not use No Authorization gateways with targets that may respond with sensitive information. Although targets are configured with their own authorization configurations, it is best to add another security layer on the gateway.
# Set up outbound authorization for your gateway
Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users that were authenticated and authorized during inbound authorization.
AgentCore Gateway supports the following types of outbound authorization:
+ **No authorization (not recommended)** – Some target types provide you the option to bypass outbound authorization. This less secure option is not recommended.
+ **IAM-based outbound authorization** – Use the [gateway service role](gateway-prerequisites-permissions.md#gateway-service-role-permissions) to authenticate access to the gateway target with [AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html).
+ **OAuth** – An open authorization framework that allows a client application to access resources. You can use OAuth with a [built-in identity provider](identity-idps.md) or with a custom one. For more information, see [OAuth 2.0](https://oauth.net/2/) . You can use the following types of OAuth authorization grants:
+ **Client credentials grant** – Machine-to-machine authentication (also known as 2-legged OAuth). The client application access resources on the application’s behalf, rather than on behalf of the user.
+ **Authorization code grant** – User-delegated access (also known as 3-legged OAuth). The user provides consent for the client application to access resources on behalf of the user.
+ **API key** – Use the AgentCore service to generate an API key to authenticate access to the gateway target.
The type of outbound authorization that you can set up is dependent on the gateway target type to which you authorize access:
| Target type | No authorization | Gateway service role | OAuth (client credentials) | OAuth (authorization code) | API key |
| --- | --- | --- | --- | --- | --- |
| API Gateway stage | Yes | Yes | No | No | Yes |
| Lambda function | No | Yes | No | No | No |
| MCP server | Yes | Yes | Yes | No | No |
| OpenAPI schema | No | No | Yes | Yes | Yes |
| Smithy schema | No | Yes | Yes | No | No |
**Note**
If you use an integration provider template as a target, review the supported authorization types for different templates at [Built-in templates from integration providers as targets](gateway-target-integrations.md).
Before adding a target to your gateway, you must set up authorization for it through one of the supported methods.
**Note**
You can skip this prerequisite if you plan to use the AWS Management Console or AgentCore CLI to create your gateway. If you use either of these tools, you can let AgentCore automatically create a service role for you with the necessary permissions to access the target. Each time you add a target, the necessary permissions will be automatically attached to your service role.
Select a topic to learn how to set up that type of authorization:
**Topics**
+ [
## Set up IAM-based outbound authorization with a gateway service role
](#gateway-outbound-auth-iam)
+ [
## Set up outbound authorization with an OAuth client
](#gateway-outbound-auth-oauth)
+ [
## Set up outbound authorization with an API key
](#gateway-outbound-auth-api-key)
## Set up IAM-based outbound authorization with a gateway service role
IAM-based outbound authorization lets you use the gateway service role’s IAM credentials to authorize with [AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) . This option lets the Amazon Bedrock AgentCore service authenticate to gateway targets on your gateway callers' behalf.
If you use this option, verify that the gateway service role has `bedrock-agentcore:InvokeGateway` permissions. The gateway uses the service role credentials for authentication during invocation.
**Additional configuration for MCP server targets**
When you use IAM-based outbound authorization with an MCP server target, you must provide additional configuration for SigV4 signing. In the `credentialProviderConfigurations` , include an `iamCredentialProvider` with the following fields:
+ **service** (required) – The AWS service name used for SigV4 signing. For example, `bedrock-agentcore` for MCP servers hosted on Amazon Bedrock AgentCore.
+ **region** (optional) – The AWS Region for SigV4 signing. If you don’t specify a Region, the gateway uses its own Region.
For Lambda, API Gateway, and Smithy targets, do not include the `iamCredentialProvider` field. These target types only support the basic `GATEWAY_IAM_ROLE` configuration with `credentialProviderType` only. For more information about specifying the credential provider configuration, see [AgentCore Gateway service role (IAM) authorization](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-service-role).
## Set up outbound authorization with an OAuth client
To set up outbound authorization with an OAuth client, you use the AgentCore Identity service and specify client credentials that you receive from creating a client in either a built-in identity provider (see [Provider setup and configuration](identity-idps.md) or a custom identity provider.
**To set up outbound authorization with an OAuth client**
1. Register your client application with a supported third-party provider.
1. You’ll receive a client ID, client secret, and possibly other values that you’ll reference when you set up the outbound authorization.
1. Follow one of the steps below, depending on your requirements:
+ To configure outbound authorization in the console using a built-in identity provider, follow the steps at [Add OAuth client using included provider](identity-add-oauth-client-included.md).
+ To configure outbound authorization in the console using a custom identity provider, follow the steps at [Add OAuth client using custom provider](identity-add-oauth-client-custom.md).
+ To configure outbound authorization using the API, send a [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html) with one of the [AgentCore control plane endpoints](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp) . For examples, see [Examples for setting OAuth client authorization](#gateway-outbound-auth-oauth-examples).
**Note**
The shape of the JSON object that the `oauth2ProviderConfigInput` field maps to depends on the provider that you use and must be congruent with the `credentialProviderVendor` value that you specify. To see examples of different configurations for different credential providers, see the outbound authorization examples in your credential provider of choice at [Provider setup and configuration](identity-idps.md).
1. Take note of the generated credential ARN ( `credentialProviderArn` in the API) and the AWS Secrets Manager secret ARN ( `secretArn` in the API). You’ll use these values when you create your gateway target.
1. (If you’re using a custom gateway service role) Attach the following identity-based policy to your gateway service role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GetWorkloadAccessToken",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
],
"Resource": [
"arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
]
},
{
"Sid": "GetResourceOauth2Token",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetResourceOauth2Token",
],
"Resource": [
"arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/oauth2credentialprovider/CredentialName"
]
},
{
"Sid": "GetSecretValue",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
]
}
]
}
```
Replace the values of the following fields:
+ In the `GetWorkloadAccessToken` statement, replace the *GatewayName* in the `Resource` list with the name of your gateway.
+ In the `GetResourceOauth2Token` statement, replace the value in the `Resource` list with the ARN of the credential that you just generated.
+ In the `GetSecretValue` statement, replace the value in the `Resource` list with the ARN of the AWS secret returned in the response when you generated the credential.
### Examples for setting OAuth client authorization
The following examples show you how to set authorization through an OAuth client for your gateway target:
**Example**
1. The AgentCore CLI credential commands must be run inside an existing agentcore project. If you don’t have one yet, create a project first with `agentcore create`.
```
agentcore add credential \
--name oauth-credential-provider \
--type oauth \
--discovery-url \
--client-id \
--client-secret
agentcore deploy
```
1.
```
aws bedrock-agentcore-control create-oauth2-credential-provider \
--name oauth-credential-provider \
--credential-provider-vendor CustomOAuth2 \
--oauth2-provider-config-input '{
"customOAuth2ProviderConfig": {
"oauthDiscovery": {
"discoveryUrl": ""
},
"clientId": "",
"clientSecret": ""
}
}'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control")
client.create_oauth2_credential_provider(
name="oauth-credential-provider",
credentialProviderVendor="CustomOAuth2",
oauth2ProviderConfigInput={
"oauthDiscovery": {
"discoveryUrl": ""
},
"clientId": "",
"clientSecret": ""
}
)
```
## Set up outbound authorization with an API key
To set up outbound authorization with an API key, you use the AgentCore Identity service and specify an API key that you receive from a supported identity provider.
**To set up outbound authorization with an OAuth client**
1. Register your client application with a supported third-party provider.
1. Set up an API key for the provider’s service. Take note of the following values, which you’ll specify when you add the gateway target:
+ **Credential location** – Whether the API key should be placed in the header or as a query parameter.
+ **Credential prefix** – The prefix for the credential (ex. Bearer).
1. Follow one of the steps below, depending on your requirements:
+ To create an API key in the AgentCore console, follow the steps at [Add API key](identity-add-api-key.md) and specify the value of the API key.
+ To create an API key using the AgentCore API, send a [CreateApiKeyCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateApiKeyCredentialProvider.html) request with one of the [AgentCore control plane endpoints](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp) and specify the value of the API key in the `apiKey` field. For examples, see [Examples for setting an API key](#gateway-outbound-auth-api-key-examples).
1. Take note of the following values, which you’ll specify when you add the gateway target:
+ **Credential provider ARN** – An Amazon Resource Name (ARN) generated for the credential provider.
+ **Name** – The name you gave to the API key.
+ **Secret ARN** – An AWS Secrets Manager secret ARN generated for the API key.
1. (If you’re using a custom gateway service role) Attach the following identity-based policy to your gateway service role:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GetWorkloadAccessToken",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
],
"Resource": [
"arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/GatewayName-*"
]
},
{
"Sid": "GetResourceApiKey",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetResourceApiKey",
],
"Resource": [
"arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/TokenVaultId/apikeycredentialprovider/Name"
]
},
{
"Sid": "GetSecretValue",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:123456789012:secret:SecretId"
]
}
]
}
```
Replace the values of the following fields:
+ In the `GetWorkloadAccessToken` statement, replace the *GatewayName* in the `Resource` list with the name of your gateway.
+ In the `GetResourceApiKey` statement, replace the value in the `Resource` list with the ARN of the credential that you just generated.
+ In the `GetSecretValue` statement, replace the value in the `Resource` list with the ARN of the AWS secret returned in the response when you generated the credential.
### Examples for setting an API key
The following examples show you how to set an API key for your gateway target:
**Example**
1. The AgentCore CLI credential commands must be run inside an existing agentcore project. If you don’t have one yet, create a project first with `agentcore create`.
```
agentcore add credential \
--name api-key-credential-provider \
--type api-key \
--api-key
agentcore deploy
```
1.
```
aws bedrock-agentcore-control create-api-key-credential-provider \
--name api-key-credential-provider \
--api-key
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control")
client.create_api_key_credential_provider(
name="api-key-credential-provider",
apiKey=""
)
```
# Set up an Amazon Bedrock AgentCore gateway
Amazon Bedrock AgentCore Gateway provides a unified connectivity layer between agents and the tools and resources they need to interact with. Before setting up your Gateway, it’s important to understand how to specify permissions so that you can secure your gateway properly.
**Topics**
+ [
## Gateway workflow
](#gateway-building-workflow)
+ [
# Create an Amazon Bedrock AgentCore gateway
](gateway-create.md)
+ [
# Add targets to an existing AgentCore gateway
](gateway-building-adding-targets.md)
## Gateway workflow
The Gateway workflow involves the following steps to connect your agents to external tools:
1. **Create the tools for your Gateway** - Define your tools using schemas such as OpenAPI specifications for REST APIs or JSON schemas for Lambda functions. The OpenAPI specifications or tool schemas for your tools are then parsed by Amazon Bedrock AgentCore for creating the Gateway.
1. **Create a Gateway endpoint** - Use the AWS console or AWS SDK to create the gateway that will serve as the MCP entry point. Each API endpoint or function will become an MCP-compatible tool, and will be made available through your MCP server URL. To secure the gateway, you can use inbound authorization to control the ingress to the gateway.
1. **Add targets to your Gateway** - Configure targets that define how the gateway routes requests to specific tools. To securely connect to backend resources on behalf of authenticated users, use Outbound Authorization. Together, Inbound and Outbound Authorization create a secure bridge between users and their target resources, supporting both IAM credentials and OAuth-based authentication flows.
1. **Update your agent code** - Connect your agent to the Gateway endpoint to access all configured tools through the unified MCP interface.
# Create an Amazon Bedrock AgentCore gateway
This guide walks you through the process of creating and configuring an Amazon Bedrock AgentCore Gateway. The Gateway serves as a unified entry point for agents to access tools and resources through the Model Context Protocol (MCP) and creating it is the first step in building your tool integration platform. When you create a gateway, you create a managed service that handles authentication and invokes callable endpoints as tools.
To create a gateway, you set up inbound authorization and configure invocable targets. Targets establish the connection between your gateway and various tool types, including Lambda functions and REST API services. Each target contains configuration details that specify the tool location, authentication requirements, and any necessary request transformation rules.
You can create a gateway in the following ways:
+ ** AWS Management Console** – With the console, you can configure authorization, create the gateway, and add targets all on one page.
+ **AgentCore CLI** – Create gateways and targets with simplified commands that handle common configurations automatically.
+ **Amazon Bedrock AgentCore API** – You can directly invoke the [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) API or through the help of a supported tool. If you use the API, you will add targets to your gateway in a separate step.
**Note**
When you create a gateway, a [workload identity](identity-manage-agent-ids.md) is automatically created for the gateway.
**Gateway features that can be set during creation**
You can activate the following features of the gateway during creation:
+ **Protocol configuration** – Configure how the gateway implements the protocol.
+ **Custom encryption of the gateway** – Specify the Amazon Resource Name (ARN) of a customer-managed AWS KMS key for greater control over the encryption process of your resource. If you don’t include one, AWS encrypts the resource with an AWS-managed key. For more information, see [Encrypt your AgentCore gateway with a customer-managed KMS key](gateway-encryption.md).
+ **Debug mode** – Allow the return of specific error messages during gateway invocation to help you with debugging. For more information, see [Turn on debugging messages](gateway-debug-messages.md).
+ **Semantic search** – Add the `x_amz_bedrock_agentcore_search` to the gateway so that the target can deliver tools that are relevant to the search query. For more information, see [Search for tools in your AgentCore gateway with a natural language query](gateway-using-mcp-semantic-search.md).
**Note**
Note the following for semantic search: ** You can only enable semantic search when creating a gateway. After you’ve created a gateway, you can’t change its configuration to enable semantic search. ** For an identity to create a gateway with semantic search, ensure that it has permissions to use the `bedrock-agentcore:SynchronizeGatewayTargets` IAM action.
+ **Policy engine configuration** – Attach a policy engine to control what actions agents can perform when calling tools through the gateway. Policy engines use Cedar policies to define authorization rules with enforcement modes for logging only or actively enforcing access decisions.
+ **Gateway interceptors** – Allow you to run custom code during each invocation of your gateway. For more information, see [Using interceptors with Gateway](gateway-interceptors.md).
Select a topic to learn how to create a gateway using that method:
**Topics**
+ [
# Create an AgentCore gateway using the AWS Management Console
](gateway-create-console.md)
+ [
# Create an AgentCore gateway using the CLI
](gateway-create-cli.md)
+ [
# Create an AgentCore gateway using the API
](gateway-create-api.md)
# Create an AgentCore gateway using the AWS Management Console
**To create a gateway using the console**
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. From the left navigation pane, select **Gateways**.
1. In the **Gateways** section, choose **Create gateway**.
1. (Optional) In the **Gateway details** section, do the following:
1. Change the generated **Gateway name**
1. Expand the **Additional configurations** section and do the following:
1. In the **Gateway description** field, provide a description for your gateway.
1. In the **Instruction** field, enter any special instructions or context that should be passed to tools when they are invoked.
1. To enable a built-in tool for searching tools in the gateway, select **Enable semantic search** . If you enable this tool, you can’t disable it later. For more information, see [Search for tools in your AgentCore gateway with a natural language query](gateway-using-mcp-semantic-search.md).
1. To enable detailed debugging messages to be returned in the gateway response, select **Exception level debug** . You can disable debugging messages later. For more information, see [Turn on debugging messages](gateway-debug-messages.md).
1. In the **Inbound Auth configurations** section, select one of the following options:
+ To allow Amazon Cognito to create authorization resources for you, select **Quick create configurations with Cognito**.
+ To use an authorization configuration that you have set up already, select **Use existing identity provider configurations** and then configure the following fields:
+ **Discovery URL** – Enter the discovery URL from your identity provider.
+ **Allowed audiences** – Enter the audience value that your gateway will accept. To add more audiences, choose **Add audience**.
+ **Allowed clients** – Enter the public identifier of the client that your gateway will accept. To add more clients, choose **Add client**.
+ **Allowed scopes** – Enter a list of permitted scopes that will be validated against the scope claim in the JWT token. The `allowedScopes` authorization field will be configured as a list of strings.
+ **Required custom claims** – Enter a list of required claims that will be validated against the claim name and value contained in the incoming JWT token. For details on configuring the authorizer, see [Configure inbound JWT authorizer](inbound-jwt-authorizer.md)
1. In the **Permissions** section, do the following:
1. To use an IAM service role to invoke the gateway on the user’s behalf, select **Use an IAM service role**.
1. (If you use an IAM service role) Choose one of the following options under **IAM role** :
+ To create a service role with the necessary permissions to access your gateway, choose **Create and use a new service role** and optionally change the generated **Service role name**.
+ To use an existing service role, choose **Use an existing service role** and then select a role from the **Service role name** dropdown menu. Make sure that the service role that you choose has the necessary permissions. For more information, see [AgentCore Gateway service role permissions](gateway-prerequisites-permissions.md#gateway-service-role-permissions).
1. (Optional) By default, your gateway is encrypted with an AWS managed key. To encrypt your gateway with a custom KMS key, expand the **KMS key** section, select **Customize encryption settings (advanced)** , and choose a customer managed key. For more information, see [Encrypt your AgentCore gateway with a customer-managed KMS key](gateway-encryption.md).
1. In the **Target: \$1\$1target-name\$1** section, do the following:
1. (Optional) Change the generated **Target name**.
1. (Optional) Provide a **Target description**.
1. For the **Target type** , choose an option. For more information about different target types, see [Add targets to an existing AgentCore gateway](gateway-building-adding-targets.md).
1. Select or enter how the target type is defined.
1. For the **Outbound Auth configurations** , select an outbound authorization method. Then, select or provide the necessary details and any optional additional configurations. For more information, see [Set up outbound authorization for your gateway](gateway-outbound-auth.md).
1. To add more targets, choose **Add another target** and repeat the target configuration steps.
1. Choose **Create gateway**.
After creating your gateway, you can view its details, including the endpoint URL and associated targets.
# Create an AgentCore gateway using the CLI
You can use the AgentCore CLI to create gateways with simplified commands. The CLI handles common configurations automatically, including IAM role creation and authorization setup.
**Example**
1. Create a gateway without authorization:
```
agentcore add gateway \
--name MyGateway \
--authorizer-type NONE \
--runtimes MyAgent
agentcore deploy
```
Create a gateway with JWT authorization:
```
agentcore add gateway \
--name MyGateway \
--authorizer-type CUSTOM_JWT \
--discovery-url https://your-idp.example.com/.well-known/openid-configuration \
--allowed-audience your-audience
agentcore deploy
```
Semantic search is enabled by default. To disable it, pass the `--no-semantic-search` flag:
```
agentcore add gateway \
--name MyGateway \
--authorizer-type NONE \
--runtimes MyAgent \
--no-semantic-search
agentcore deploy
```
1. You can also use the AgentCore CLI interactive terminal UI. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** :
1. In the **Add Resource** menu, select **Gateway** and press **Enter**.
![\[TUI Add Resource menu with Gateway highlighted\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-resource.png)
1. Enter a name for your gateway and press **Enter**.
![\[TUI gateway wizard Name step with text input\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select the authorizer type for your gateway. Choose **None** , **Custom JWT** , or **IAM** , then press **Enter**.
![\[TUI gateway wizard Authorizer step showing None selected\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-none.png)
1. (Optional) Configure advanced settings such as semantic search and debug exception level. Use **Space** to toggle options, then press **Enter** to continue.
![\[TUI gateway wizard Advanced Configuration step with Semantic Search enabled\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the gateway configuration summary and press **Enter** to confirm.
![\[TUI gateway wizard Review Configuration summary\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
After creating the gateway, you can add targets using the `agentcore add gateway-target` command. For more information about CLI commands, see the [Get started with AgentCore Gateway](gateway-quick-start.md).
# Create an AgentCore gateway using the API
To create a AgentCore gateway using the API, make a [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) request with one of the [AgentCore control plane endpoints](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp).
Minimally, you must specify the following fields:
+ `name` – The name of the gateway.
+ `roleArn` – The ARN of the gateway service role. For more information, see [AgentCore Gateway service role permissions](gateway-prerequisites-permissions.md#gateway-service-role-permissions).
+ `authorizerType` – The type of authorizer to use for the gateway. Depends on the inbound authorization that you set up. For more information, see [Set up inbound authorization for your gateway](gateway-inbound-auth.md).
+ `protocolType` – The protocol type for the gateway.
The following optional fields add metadata to your gateway:
+ `description` – A description of the gateway.
+ `tags` – A dictionary of key-value pairs specifying tags that you can use to label your gateway for monitoring purposes.
The remaining fields depend on your gateway configuration and whether you want to toggle custom features for your gateway:
+ `clientToken` – A client token value to ensure that a request completes no more than once. If you don’t include this token, one is randomly generated for you. If you don’t include a value, one is randomly generated for you. For more information, see [Ensuring idempotency](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html).
+ `authorizerConfiguration` – If your authorizer type is `CUSTOM_JWT` , you must include this field to specify the gateway authorization and authentication parameters. For more information, see [The authorizer configuration](#gateway-create-api-authorizer-config).
+ `kmsKeyArn` – To encrypt your gateway with a KMS key include the ARN of the key in this field. For more information, see [Encrypt your AgentCore gateway with a customer-managed KMS key](gateway-encryption.md).
+ `exceptionLevel` – To turn on debugging messages when invoking the gateway, set this value to `DEBUG` . For more information, see [Turn on debugging messages](gateway-debug-messages.md) . For examples of creating a gateway with this setting, see [Create a gateway with debugging messages](#gateway-create-ex-debug).
+ `interceptorConfigurations` – To turn on custom code that is run when invoking your gateway, include this field. For more information, see [Using interceptors with Gateway](gateway-interceptors.md) . For examples of creating a gateway with interceptors, see [Create a gateway with interceptor configurations](#gateway-create-ex-basic-interceptors).
+ `protocolConfiguration` – To include customizations for the gateway protocol, configure the settings in this field. For options in this configuration, see [GatewayProtocolConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GatewayProtocolConfiguration.html).
+ One example option is the addition of a tool search tool in your gateway. For more information, see [Search for tools in your AgentCore gateway with a natural language query](gateway-using-mcp-semantic-search.md) . For examples of creating a gateway with this search tool, see [Create a gateway with semantic search](#gateway-create-ex-semantic).
## The authorizer configuration
If your authorizer type is `CUSTOM_JWT` , you must also include an authorizer configuration in the `authorizerConfiguration` field. The basic structure of the authorizer configuration is as follows:
```
{
"customJWTAuthorizer": {
"discoveryUrl": "string",
"allowedAudience": ["string"],
"allowedClients": ["string"],
"allowedScopes": ["string"],
"customClaims": see below
}
}
```
You must provide the discovery URL for the authentication token. The remaining fields define restrictions for the authentication claims:
+ `allowedAudience` – The audiences or services that can handle the JWT.
+ `allowedClients` – The clients that are allowed to create a JWT.
+ `allowedScopes` – The scopes of that limit the set of claims.
+ `customClaims` – An array of objects that allows you to define custom fields and values that limit the claims to be authenticated. Each object is a `CustomClaimValidationsType` object contains the following fields:
+ `inboundTokenClaimName` – The name of the custom claim field to check.
+ `inboundTokenClaimValueType` – The data type of the claim value to check for.
+ `authorizingClaimMatchValue` – Defines the value to match the claim value to. Contains the following fields:
+ `claimMatchOperator` – Defines the relationship to look for between the match value and claim value.
+ `claimMatchValue` – An object that contains only one of the following fields:
+ matchValueString – Used in the following situations:
+ If the `inboundTokenClaimValueType` is `STRING` and the `claimMatchOperator` is `EQUALS` , specify a string that you want the claim value to match with for authentication.
+ If the `inboundTokenClaimValueType` is `STRING_ARRAY` and the `claimMatchOperator` is `CONTAINS` , specify a string that you want the claim value array to contain for authentication.
+ `matchValueArray` – If the `inboundTokenClaimValueType` is `STRING_ARRAY` and the `claimMatchOperator` is `CONTAINS_ANY` , specify an array of values that you want to check for authentication. If any of the values in the claim value array matches any of the values in the `matchValueArray` , the claim can be authenticated.
The following examples show the structure of the CustomClaimValidationsType objects that you can specify:
**Example**
1.
```
{
"inboundTokenClaimName": "string",
"inboundTokenClaimValueType": "STRING",
"authorizingClaimMatchValue": {
"claimMatchValue": {
"matchValueString": "string"
},
"claimMatchOperator": "EQUALS"
}
}
```
1.
```
{
"inboundTokenClaimName": "string",
"inboundTokenClaimValueType": "STRING_ARRAY",
"authorizingClaimMatchValue": {
"claimMatchValue": {
"matchValueString": "string"
},
"claimMatchOperator": "CONTAINS"
}
}
```
1.
```
{
"inboundTokenClaimName": "string",
"inboundTokenClaimValueType": "STRING_ARRAY",
"authorizingClaimMatchValue": {
"claimMatchValue": {
"matchValueStringList": ["string"]
},
"claimMatchOperator": "CONTAINS_ANY"
}
}
```
To see examples of how to create a gateway, expand the section that corresponds to your use case:
**Topics**
## Create a gateway: basic example (Custom JWT authorization)
This section provides basic examples of creating a gateway.
**Note**
Note the following: \$1 The values for the authorization configuration are from when you set up [inbound authorization](gateway-inbound-auth.md) . \$1 If you choose an option that involves specifying an overt gateway service role ARN, ensure that you specify an existing one that you’ve set up. For more information, see [AgentCore Gateway service role permissions](gateway-prerequisites-permissions.md#gateway-service-role-permissions).
Select one of the following methods:
**Example**
1. The AgentCore CLI provides a simple way to create a gateway in a command line interface.
To create the gateway, you use the `agentcore add gateway` command. The gateway service role and Amazon Cognito authorization are automatically configured for you during deployment.
**Using default arguments**
Run the following command in a terminal to create a gateway with no authorization (the default). To add Custom JWT authorization, specify the authorizer flags as shown in the next example:
```
agentcore add gateway --name my-gateway
```
**Specifying arguments**
The following command shows how to create a gateway with Custom JWT authorization and explicit configuration:
```
agentcore add gateway \
--name my-gateway \
--authorizer-type CUSTOM_JWT \
--discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
--allowed-audience "api.example.com"
agentcore deploy
```
After deployment, the `gatewayUrl` shown by **agentcore status** is the endpoint to use when you invoke the gateway.
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** :
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select **Custom JWT** as the authorizer type and press **Enter** :
![\[Gateway wizard: select Custom JWT authorizer\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-jwt.png)
1. Configure advanced options:
![\[Gateway wizard: advanced configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration summary and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
1. Run the following code in a terminal to create a basic gateway with the AWS CLI:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}'
```
The `gatewayUrl` in the response is the endpoint to use when you invoke the gateway.
1. The following Python code shows how to create a basic gateway with the AWS Python SDK (Boto3):
```
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = 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/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
```
## Create a gateway: basic example (IAM authorization)
This section provides basic examples of creating a gateway using IAM authorization. With IAM authorization, you don’t need an authorizer configuration.
**Note**
The AgentCore CLI does not support creating gateways with IAM authorization. Use the AWS Command Line Interface or AWS Python SDK (Boto3) to create a gateway with IAM authorization.
Select one of the following methods:
**Example**
1. Run the following in a terminal:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/MyAgentCoreServiceRole \
--protocol-type MCP \
--authorizer-type AWS_IAM
```
1.
```
import boto3
# Create the AgentCore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = agentcore_client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/MyAgentCoreServiceRole",
protocolType="MCP",
authorizerType="AWS_IAM"
)
```
## Create a gateway: basic example (NONE authorizer)
This section provides basic examples of creating a gateway with a NONE authorizer type. This represents a gateway that will not perform authentication or authorization for any incoming requests.
**Note**
\$1 The NONE authorizer type represents a gateway that will not perform authentication or authorization for any incoming requests. See [inbound authorization](gateway-inbound-auth.md) for security concerns and details around using this configuration. \$1 If you choose an option that involves specifying an overt gateway service role ARN, ensure that you specify an existing one that you’ve set up. For more information, see [AgentCore Gateway service role permissions](gateway-prerequisites-permissions.md#gateway-service-role-permissions).
Select one of the following methods:
**Example**
1. The AgentCore CLI provides a simple way to create a gateway with NONE authorizer type in a command line interface.
The following command shows how to create a gateway with NONE authorizer type:
```
agentcore add gateway \
--name my-gateway \
--authorizer-type NONE
agentcore deploy
```
After deployment, the `gatewayUrl` shown by **agentcore status** is the endpoint to use when you invoke the gateway.
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** :
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select **NONE** as the authorizer type and press **Enter** :
![\[Gateway wizard: select NONE authorizer\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-none.png)
1. Configure advanced options:
![\[Gateway wizard: advanced configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration summary and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
1. Run the following code in a terminal to create a gateway with NONE authorizer type using the AWS CLI:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type NONE
```
The `gatewayUrl` in the response is the endpoint to use when you invoke the gateway.
1. The following Python code shows how to create a gateway with NONE authorizer type using the AWS Python SDK (Boto3):
```
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway",
roleArn="arn:aws:iam::123456789012:role/my-gateway-service-role",
protocolType="MCP",
authorizerType="NONE"
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
```
## Create a gateway with semantic search
This section provides basic examples of creating a gateway with a tool to allow you to semantically search for relevant tools. To learn how to use this tool, see [Search for tools in your AgentCore gateway with a natural language query](gateway-using-mcp-semantic-search.md).
Select one of the following methods:
**Example**
1. By default, semantic search is enabled when you create a gateway using the AgentCore CLI. To disable it, use the `--no-semantic-search` flag. To create a gateway with default semantic search enabled:
```
agentcore add gateway --name my-gateway
agentcore deploy
```
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** . Semantic search is enabled by default in the advanced options:
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select the authorizer type and press **Enter** :
![\[Gateway wizard: select authorizer type\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-jwt.png)
1. In advanced options, verify that semantic search is enabled (this is the default):
![\[Gateway wizard: advanced configuration with semantic search enabled\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration summary and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
1. Turn on semantic search when creating a gateway in the AWS CLI by specifying `searchType` as `SEMANTIC` in the `--protocol-configuration` object, as in the following example:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--protocol-configuration '{
"mcp": {
"searchType": "SEMANTIC"
}
}'
```
The `gatewayUrl` in the response is the endpoint to use when you invoke the gateway.
1. Turn on semantic search when creating a gateway using the AWS Python SDK (Boto3) by specifying `searchType` as `SEMANTIC` in the `protocolConfiguration` object, as in the following example:
```
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = 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/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
protocolConfiguration={
"mcp": {
"searchType": "SEMANTIC"
}
}
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
```
## Create a gateway with debugging messages
You can create a gateway with debugging messages by specifying the `exceptionLevel` value as `DEBUG` . This section provides examples of creating a gateway with debugging messages. To learn more, see [Turn on debugging messages](gateway-debug-messages.md).
**Note**
The AgentCore CLI does not set `exceptionLevel` to `DEBUG` by default. You must pass the `--exception-level DEBUG` flag when creating the gateway. You can turn off debugging messages by sending an [UpdateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateGateway.html) request and omitting the `exceptionLevel` argument.
Select one of the following methods:
**Example**
1. When you create a gateway using the AgentCore CLI, pass the `--exception-level` flag to enable debugging messages:
```
agentcore add gateway --name my-gateway --exception-level DEBUG
agentcore deploy
```
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** . In advanced options, you can enable debugging messages by setting the exception level to `DEBUG` :
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select the authorizer type and press **Enter** :
![\[Gateway wizard: select authorizer type\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-jwt.png)
1. In advanced options, set the exception level to `DEBUG` :
![\[Gateway wizard: advanced configuration with debug mode enabled\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration summary and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
1. Run the following code in a terminal to create a gateway with debugging messages turned on in the AWS CLI:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--exception-level DEBUG
```
The `gatewayUrl` in the response is the endpoint to use when you invoke the gateway.
1. The following Python code shows how to create a basic gateway with the AWS Python SDK (Boto3):
```
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = 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/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
exceptionLevel="DEBUG"
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
```
## Create a gateway with interceptor configurations
This section provides examples of creating a gateway that has interceptors configured. Interceptors will be invoked at runtime of the gateway for each request.
**Note**
\$1 Interceptors will be invoked at runtime of the gateway for each request. \$1 If you choose an option that involves specifying an overt gateway service role ARN, ensure that you specify an existing one that you’ve set up. For more information, see [AgentCore Gateway service role permissions](gateway-prerequisites-permissions.md#gateway-service-role-permissions).
Select one of the following methods:
**Example**
1. With the AgentCore CLI, first create the gateway and then configure interceptors using the AWS CLI or AWS Python SDK (Boto3).
Create the gateway:
```
agentcore add gateway \
--name my-gateway \
--authorizer-type CUSTOM_JWT \
--discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
--allowed-audience "api.example.com"
agentcore deploy
```
After deployment, configure interceptors on the gateway using the AWS CLI `update-gateway` command or the AWS Python SDK (Boto3) as shown in the other tabs.
1. Run `agentcore` to open the TUI, then select **add** and choose **Gateway** . After creating the gateway, configure interceptors using the AWS CLI or AWS Python SDK (Boto3):
1. Enter the gateway name:
![\[Gateway wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-name.png)
1. Select **Custom JWT** as the authorizer type and press **Enter** :
![\[Gateway wizard: select Custom JWT authorizer\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-auth-jwt.png)
1. Configure advanced options:
![\[Gateway wizard: advanced configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-advanced.png)
1. Review the configuration summary and press **Enter** to confirm:
![\[Gateway wizard: review configuration\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-confirm.png)
After the gateway is created and deployed, configure interceptors using the AWS CLI `update-gateway` command or the AWS Python SDK (Boto3) as shown in the other tabs.
1. Run the following code in a terminal to create a gateway with interceptor configurations using the AWS CLI:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--interceptor-configurations '[{
"interceptor": {
"lambda": {
"arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
}
},
"interceptionPoints": ["REQUEST"]
}]'
```
The `gatewayUrl` in the response is the endpoint to use when you invoke the gateway.
1. The following Python code shows how to create a gateway with interceptor configurations using the AWS Python SDK (Boto3):
```
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = 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/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
interceptorConfigurations=[{
"interceptor": {
"lambda": {
"arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
}
},
"interceptionPoints": ["REQUEST"]
}]
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
```
## Create a gateway with a policy engine configuration
You can create a gateway with a policy engine configuration. A policy engine is a collection of policies that evaluates and authorizes agent tool calls. When associated with a gateway, the policy engine intercepts all agent requests and determines whether to allow or deny each action based on the defined policies. The enforcement `mode` specifies whether to test policies ( `LOG_ONLY` ) or enforce them ( `ENFORCE` ).
**Example**
1. First, add a policy engine to your project. Then, create a gateway that references the policy engine:
```
agentcore add policy-engine \
--name MyPolicyEngine
agentcore add gateway \
--name MyGateway \
--authorizer-type CUSTOM_JWT \
--discovery-url https://cognito-idp.us-west-2.amazonaws.com/pool-id/.well-known/openid-configuration \
--allowed-clients clientId \
--policy-engine MyPolicyEngine \
--policy-engine-mode LOG_ONLY
agentcore deploy
```
To enforce policies instead of only logging decisions, change `--policy-engine-mode` to `ENFORCE`.
1. Run the following command to create a gateway with a policy engine configuration using the AWS CLI:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/pool-id/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--policy-engine-configuration '{
"arn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:policy-engine/policy-id",
"mode": "LOG_ONLY"
}' \
--exception-level DEBUG
```
The `gatewayUrl` in the response is the endpoint to use when you invoke the gateway.
# Add targets to an existing AgentCore gateway
After creating a gateway, you can add targets, which define the tools that your gateway will host. AgentCore Gateway supports multiple target type that are detailed in the following topics. Each target can have its own credential provider attached, enabling you to securely control access targets. By adding targets, your gateway becomes a single MCP URL that enables access to all of the relevant tools for an agent.
When you add a target, you provide the following required fields:
+ The ID of the gateway to which to add the target.
+ A name for the gateway target. To understand how the target name affects tool names, see [Understand how AgentCore Gateway tools are named](gateway-tool-naming.md).
+ A target configuration. The configuration differs depending on the gateway protocol type and your gateway target type. For more information, see [TargetConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_TargetConfiguration.html) and its daughter pages.
+ A credential provider configuration. The configuration depends on the [outbound authorization](gateway-outbound-auth.md).
You can optionally provide the following fields:
+ A description of the gateway target.
+ A client token value to ensure that a request completes no more than once. If you don’t include this token, one is randomly generated for you. If you don’t include a value, one is randomly generated for you. For more information, see [Ensuring idempotency](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html).
Select a topic to learn how to add a target to an existing gateway using that method:
**Topics**
+ [
# Add a target using the AWS Management Console
](gateway-add-target-console.md)
+ [
# Add a target using the CLI
](gateway-add-target-cli.md)
+ [
# Add a target using the API
](gateway-add-target-api.md)
# Add a target using the AWS Management Console
In the AWS Management Console, you can add gateway targets when you create the gateway. After you’ve created a gateway, you can add targets by doing the following:
**To add a target to an existing gateway**
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. Choose **Gateways**.
1. Select the gateway to which you want to add a target.
1. In the **Targets** section, choose **Add**.
1. (Optional) Change the auto-generated **Target name**.
1. (Optional) Provide an **Target description**.
1. Select the **Target type** and fill in the fields that appear.
1. (If applicable) Choose whether to define the target inline or by selecting an S3 location.
1. Select a supported outbound authorization configuration and choose the outbound authorization resource, if applicable.
1. (Optional, if applicable) Expand **Additional configurations** and configure them.
1. Choose **Add target**.
# Add a target using the CLI
You can use the AgentCore CLI to add targets to an existing gateway with simplified commands.
**Example**
1. Add an MCP server target:
```
agentcore add gateway-target \
--name MyMCPTarget \
--type mcp-server \
--endpoint https://your-mcp-server.example.com/mcp \
--gateway MyGateway
agentcore deploy
```
Add a Lambda function target:
```
agentcore add gateway-target \
--name MyLambdaTarget \
--type lambda-function-arn \
--lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyFunction \
--tool-schema-file tools.json \
--gateway MyGateway
agentcore deploy
```
Add an OpenAPI schema target:
```
agentcore add gateway-target \
--name MyOpenAPITarget \
--type open-api-schema \
--schema path/to/openapi-spec.json \
--outbound-auth none|api-key|oauth \
--gateway MyGateway
agentcore deploy
```
1. You can also use the AgentCore CLI interactive terminal UI. Run `agentcore` to open the TUI, then select **add** and choose **Gateway Target** :
1. In the **Add Resource** menu, select **Gateway Target** and press **Enter**.
![\[TUI Add Resource menu with Gateway Target option visible\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-add-resource.png)
1. Select the target type for your gateway. The wizard shows the available target types, including MCP Server endpoint, API Gateway REST API, OpenAPI Schema, Smithy Model, and Lambda function.
![\[TUI target type selection showing MCP Server endpoint\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-mcp.png)
1. Follow the remaining wizard prompts to provide the target name, endpoint or schema details, and outbound authorization configuration. The specific fields depend on the target type you selected.
For more CLI examples, see the [Get started with AgentCore Gateway](gateway-quick-start.md).
# Add a target using the API
To add a target using the API, make a [CreateGatewayTarget](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGatewayTarget.html) request with one of the [AgentCore control plane endpoints](https://docs.aws.amazon.com/general/latest/gr/bedrock_agentcore.html#bedrock_agentcore_cp) and define a target configuration that matches the target type.
**Note**
To add an integration provider template as a gateway target, you must use the AWS Management Console. For more information, see [Built-in templates from integration providers as targets](gateway-target-integrations.md).
When you create a gateway target, you specify the following configurations depending on what you set up when you fulfilled the prerequisites:
+ **A credential provider configuration** – To specify the authorization type and credentials to access the target.
+ **A target configuration** – To specify the target, tools, and how the gateway communicates with the target.
To learn more about each type of configuration, see the following topics:
**Topics**
+ [
# Specify the authorization type and credentials to access the gateway target
](gateway-building-adding-targets-authorization.md)
+ [
# Define the gateway target configuration
](gateway-add-target-api-target-config.md)
# Specify the authorization type and credentials to access the gateway target
In the [CreateGatewayTarget](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGatewayTarget.html) request body, you specify the credential provider configuration in the `credentialProviderConfigurations` array. The configuration depends on the outbound authorization type that you set up. For reference information about the API structure for the credential provider configuration, see [CredentialProviderConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CredentialProviderConfiguration.html) . For more information on outbound authorization, see [Set up outbound authorization for your gateway](gateway-outbound-auth.md).
To learn more about a credential provider configuration, select a topic:
**Topics**
+ [
## AgentCore Gateway service role (IAM) authorization
](#gateway-building-adding-targets-authorization-service-role)
+ [
## OAuth authorization
](#gateway-building-adding-targets-authorization-oauth)
+ [
## API key authorization
](#gateway-building-adding-targets-authorization-api-key)
## AgentCore Gateway service role (IAM) authorization
If you’re using IAM authorization through an AgentCore Gateway service role for your target, specify the `credentialProviderType` as `GATEWAY_IAM_ROLE` . The configuration depends on your target type.
**For Lambda, API Gateway, and Smithy targets**
The `iamCredentialProvider` configuration is not needed because the target service name is already known to the AgentCore Gateway service. Use only the `credentialProviderType` configuration, as shown in the following example:
```
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
```
**For MCP server targets**
For MCP server targets, you must also provide an `iamCredentialProvider` with the service name used for [AWS Signature Version 4 (Sig V4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) signing. The `service` field is required. The `region` field is optional and defaults to the gateway’s Region.
```
{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}
```
The following table describes the fields in the `iamCredentialProvider` object:
| Field | Required | Description |
| --- | --- | --- |
| `service` | Yes | The AWS service name used for SigV4 signing. This value must match the service name that the target expects when verifying the SigV4 signature. The following are common values: `bedrock-agentcore` – For MCP servers hosted on Amazon Bedrock AgentCore, such as the runtime (see [Deploy MCP servers in AgentCore Runtime](runtime-mcp.md) ) or another gateway. `execute-api` – For MCP servers behind Amazon API Gateway. `lambda` – For MCP servers behind Lambda Function URLs. |
| `region` | No | The AWS Region for SigV4 signing. If omitted, defaults to the gateway’s Region. |
## OAuth authorization
If you’re using OAuth authorization, you specify the `credentialProviderType` as `OAUTH` . In the object that the `credentialProvider` field maps to, map an `oauthCredentialProvider` field name to an [OAuthCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_OAuthCredentialProvider.html) object and provide the values based on your outbound authorization setup.
The structure of the [OAuthCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_OAuthCredentialProvider.html) differs depending on the type of authentication pattern that you set up. To learn more about different authentication patterns, see [Supported authentication patterns](common-use-cases.md).
+ If you set up machine-to-machine authentication, also known as a client credentials grant or 2-legged OAuth (2LO), follow the structure in the **Client credentials** tab.
+ If you set up user-delegated access, also known as an authorization code grant or 3-legged OAuth (3LO), follow the structure in the **Authorization code** tab.
Select one of the following methods:
**Example**
1. Specify the `grantType` as `CLIENT_CREDENTIALS` , as in the following example:
```
{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "string",
"grantType": "CLIENT_CREDENTIALS",
"scopes": [
"string",
...
],
"customParameters": {
"string": "string"
}
}
}
}
```
1. Specify the `grantType` as `AUTHORIZATION_CODE` and include, in the `defaultReturnUrl` field, the URL to which to redirect the end user’s browser after obtaining the authorization code, as in the following example:
```
{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "string",
"grantType": "AUTHORIZATION_CODE",
"defaultReturnUrl": "string",
"scopes": [
"string",
...
],
"customParameters": {
"string": "string"
}
}
}
}
```
To learn more about 3LO authentication, see [OAuth 2.0 authorization URL session binding](oauth2-authorization-url-session-binding.md).
## API key authorization
If you set up API key authorization, you specify the `credentialProviderType` as `API_KEY` . In the object that the `credentialProvider` field maps to, map an `apiKeyCredentialProvider` field name to an [ApiKeyCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_ApiKeyCredentialProvider.html) object and provide the values based on your outbound authorization setup. The following JSON shows the structure:
```
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "string",
"credentialLocation": "HEADER" | "QUERY_PARAMETER",
"credentialParameterName": "string",
"credentialPrefix": "string"
}
}
}
```
# Define the gateway target configuration
The target configuration depends on the target type that you’re adding to the gateway. For more information about supported gateway target types, see [Supported targets for Amazon Bedrock AgentCore gateways](gateway-supported-targets.md).
Select a topic to see examples of adding a target type:
**Topics**
+ [
## Add a Lambda target
](#gateway-add-target-api-lambda)
+ [
## Add an API Gateway stage target
](#gateway-add-target-api-gateway)
+ [
## Add an OpenAPI target
](#gateway-add-target-api-openapi)
+ [
## Add a Smithy target
](#gateway-add-target-api-smithy)
+ [
## Add an MCP server target
](#gateway-add-target-api-MCPserver)
## Add a Lambda target
You can add a Lambda target to your gateway using the AgentCore CLI by specifying the `--type` as `lambda-function-arn` and providing the Lambda ARN and a tool schema file.
**Target configuration**
The target configuration (or payload) for a Lambda function contains the following fields:
+ **lambdaArn** – The ARN of the Lambda function to use as your target.
+ **toolSchema** – The tool schema for the gateway target.
For more information about Lambda targets, see [AWS Lambda function targets](gateway-add-target-lambda.md).
Select one of the following methods:
**Example**
1. To add a Lambda function as a target, run `agentcore add gateway-target` with the `--type lambda-function-arn` option. Provide the Lambda ARN and a JSON file containing the tool schema:
```
agentcore add gateway-target \
--name MyLambdaTarget \
--type lambda-function-arn \
--lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MyFunction \
--tool-schema-file tools.json \
--gateway MyGateway
agentcore deploy
```
1. With the AgentCore CLI, you can easily create a Lambda target with default configurations.
```
# Import dependencies
from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient
# Initialize the client
client = GatewayClient(region_name="us-east-1")
# Create a lambda target.
lambda_target = client.create_mcp_gateway_target(
gateway=gateway,
name=None, # If you don't set one, one will be generated.
target_type="lambda",
target_payload=None, # Define your own lambda if you pre-created one. Otherwise leave this as None and one will be created for you.
credentials=None, # If you leave this as None, one will be created for you
)
```
The following is an example argument you can provide for the `target_payload` . If you omit the `target_payload` argument, this payload is used:
```
{
"lambdaArn": "",
"toolSchema": {
"inlinePayload": [
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "the location e.g. seattle, wa"
}
},
"required": [
"location"
]
}
},
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {
"timezone": {
"type": "string"
}
},
"required": [
"timezone"
]
}
}
]
}
}
```
1. The following Python code shows how to add a Lambda target using the AWS Python SDK (Boto3):
```
import boto3
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a Lambda target
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="LambdaTarget",
targetConfiguration={
"mcp": {
"lambda": {
"lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:YourLambdaFunction",
"toolSchema": {
"inlinePayload": [
{
"name": "get_weather",
"description": "Get weather for a location",
"inputSchema": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
},
{
"name": "get_time",
"description": "Get time for a timezone",
"inputSchema": {
"type": "object",
"properties": {"timezone": {"type": "string"}},
"required": ["timezone"],
},
},
]
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
1. In the AgentCore CLI interactive terminal UI, run `agentcore` , select **add** , choose **Gateway Target** , and then select **Lambda function** :
![\[TUI target type selection with Lambda function highlighted\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-lambda.png)
The wizard then prompts you for the target name, Lambda function ARN, tool schema file, and outbound authorization configuration.
## Add an API Gateway stage target
To add a stage of an API Gateway REST API as a target, specify the ARN of the API and stage and define settings to filter tools in the API gateway or to override names and descriptions of tools in the gateway:
The following examples show how to add an API Gateway target. The following configurations are also applied:
+ The tools filtered for are the GET and POST methods for the `/products` path.
+ GET /products is renamed as `get_items`.
Select one of the following methods:
**Example**
1. To add an API Gateway REST API stage as a target, run `agentcore add gateway-target` with the `--type api-gateway` option:
```
agentcore add gateway-target \
--name MyAPIGatewayTarget \
--type api-gateway \
--rest-api-id your-rest-api-id \
--stage your-stage \
--gateway MyGateway
agentcore deploy
```
1. The following command uses the AWS CLI:
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "SearchAPITarget" \
--target-configuration '{
"mcp": {
"apiGateway": {
"restApiId": rest-api-id,
"stage": stage,
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/products",
"methods": [
"GET",
"POST"
]
}
],
"toolOverrides": [
{
"path": "/products",
"method": "GET",
"name": "get_items",
"description": "Gets information for items in the list of products."
}
]
}
}
}
}'
--credential-provider-configurations '[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]'
```
1. The following code shows uses the AWS Python SDK (Boto3):
```
import boto3
# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create an API gateway REST API target with gateway service role authentication
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="SearchAPITarget",
targetConfiguration={
"mcp": {
"apiGateway": {
"restApiId": rest-api-id,
"stage": stage,
"apiGatewayToolConfiguration": {
"toolFilters": [
{
"filterPath": "/products",
"methods": [
"GET",
"POST"
]
}
],
"toolOverrides": [
{
"path": "/products",
"method": "GET",
"name": "get_item",
"description": "Gets information for a specific item in the product list."
}
]
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
1. In the AgentCore CLI interactive terminal UI, run `agentcore` , select **add** , choose **Gateway Target** , and then select **API Gateway REST API** :
![\[TUI target type selection showing API Gateway REST API option\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-apigw.png)
The wizard then prompts you for the target name, REST API ID, stage, and outbound authorization configuration.
## Add an OpenAPI target
Select one of the following methods:
**Example**
1. To add an OpenAPI schema target, run `agentcore add gateway-target` with the `--type open-api-schema` option and provide the path to your OpenAPI specification file:
```
agentcore add gateway-target \
--name MyOpenAPITarget \
--type open-api-schema \
--schema path/to/openapi-spec.json \
--outbound-auth none|api-key|oauth \
--gateway MyGateway
agentcore deploy
```
1. The following Python code shows how to add an OpenAPI target using the AWS Python SDK (Boto3). The schema has been uploaded to an S3 location whose URI is referenced in the `target_payload` . Outbound authorization for the target is through an API key.
```
import boto3
# Create the client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create an OpenAPI target with API Key authentication
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="SearchAPITarget",
targetConfiguration={
"mcp": {
"openApiSchema": {
"s3": {
"uri": "s3://your-bucket/path/to/open-api-spec.json",
"bucketOwnerAccountId": "123456789012"
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "API_KEY",
"credentialProvider": {
"apiKeyCredentialProvider": {
"providerArn": "arn:aws:agent-credential-provider:us-east-1:123456789012:token-vault/default/apikeycredentialprovider/abcdefghijk",
"credentialLocation": "HEADER",
"credentialParameterName": "X-API-Key"
}
}
}
]
)
```
1. In the AgentCore CLI interactive terminal UI, run `agentcore` , select **add** , choose **Gateway Target** , and then select **OpenAPI Schema** :
![\[TUI target type selection showing OpenAPI Schema option\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-openapi.png)
The wizard then prompts you for the target name, path to the OpenAPI specification file, and outbound authorization configuration.
## Add a Smithy target
Select one of the following methods:
**Example**
1. To add a Smithy model target, run `agentcore add gateway-target` with the `--type smithy-model` option and provide the path to your Smithy model file:
```
agentcore add gateway-target \
--name MySmithyTarget \
--type smithy-model \
--schema path/to/smithy-model.json \
--gateway MyGateway
agentcore deploy
```
1. The following Python code shows how to add a Smithy model target using the AWS Python SDK (Boto3):
```
import boto3
# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create a Smithy model target
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="DynamoDBTarget",
targetConfiguration={
"mcp": {
"smithyModel": {
"s3": {
"uri": "s3://your-bucket/path/to/smithy-model.json",
"bucketOwnerAccountId": "123456789012"
}
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE"
}
]
)
```
1. In the AgentCore CLI interactive terminal UI, run `agentcore` , select **add** , choose **Gateway Target** , and then select **Smithy Model** :
![\[TUI target type selection showing Smithy Model option\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-smithy.png)
The wizard then prompts you for the target name, path to the Smithy model file, and outbound authorization configuration.
## Add an MCP server target
You can add an MCP server target using the AgentCore CLI or AWS Python SDK (Boto3). The following examples show how to create an MCP server target with different outbound authorization types.
**MCP server with IAM (SigV4) authorization**
The following example creates an MCP server target with IAM authorization. The gateway signs requests to the MCP server using SigV4 with the gateway service role’s credentials. You must specify the `service` name for signing. The `region` is optional and defaults to the gateway’s Region.
The value of `service` depends on where your MCP server is hosted. The following are common values:
+ `bedrock-agentcore` – For MCP servers hosted on Amazon Bedrock AgentCore, such as the runtime (see [Deploy MCP servers in AgentCore Runtime](runtime-mcp.md) ) or another gateway.
+ `execute-api` – For MCP servers behind Amazon API Gateway.
+ `lambda` – For MCP servers behind Lambda Function URLs.
Select one of the following methods:
**Example**
1.
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}]'
```
1. In the AgentCore CLI interactive terminal UI, run `agentcore` , select **add** , choose **Gateway Target** , and then select **MCP Server endpoint** :
![\[TUI target type selection with MCP Server endpoint highlighted\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/gateway-target-type-mcp.png)
The wizard then prompts you for the target name, MCP server endpoint URL, and outbound authorization configuration.
1.
```
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-server.bedrock-agentcore.us-west-2.api.aws"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": {
"service": "bedrock-agentcore",
"region": "us-west-2"
}
}
}
]
)
```
**MCP server with OAuth authorization**
The following example creates an MCP server target with OAuth (client credentials) authorization.
Select one of the following methods:
**Example**
1.
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier "your-gateway-id" \
--name "MyMCPTarget" \
--target-configuration '{
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
}' \
--credential-provider-configurations '[{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
"scopes": []
}
}
}]'
```
1. To add an MCP server target with OAuth authorization, run `agentcore add gateway-target` with the `--type mcp-server` option and specify the OAuth credentials:
```
agentcore add gateway-target \
--type mcp-server \
--name MyMCPTarget \
--endpoint https://my-mcp-server.example.com \
--gateway MyGateway \
--outbound-auth oauth \
--oauth-client-id my-client \
--oauth-client-secret my-secret \
--oauth-discovery-url https://auth.example.com/.well-known/openid-configuration
agentcore deploy
```
1.
```
import boto3
agentcore_client = boto3.client('bedrock-agentcore-control')
target = agentcore_client.create_gateway_target(
gatewayIdentifier="your-gateway-id",
name="MyMCPTarget",
targetConfiguration={
"mcp": {
"mcpServer": {
"endpoint": "https://my-mcp-server.example.com"
}
}
},
credentialProviderConfigurations=[
{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/oauth2credentialprovider/my-oauth-provider",
"scopes": []
}
}
}
]
)
```
# Use an AgentCore gateway
After [setting up your gateway with targets](gateway-building.md) , you can configure your application or agent to use the gateway through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) . The MCP provides a standardized way for agents to discover and invoke tools.
**Note**
AgentCore Gateway supports the following MCP versions: \$1 2025-06-18 \$1 2025-03-26
You can use the following MCP operations with an AgentCore gateway:
| Operation | Description |
| --- | --- |
| tools/call | Invokes a specific tool with the provided arguments |
| tools/list | Lists all available tools provided by the gateway |
The following topics describe how to invoke your AgentCore gateway:
**Topics**
+ [
# Authorize and authenticate to an AgentCore gateway and gateway target
](gateway-using-auth.md)
+ [
# List available tools in an AgentCore gateway
](gateway-using-mcp-list.md)
+ [
# Call a tool in a AgentCore gateway
](gateway-using-mcp-call.md)
+ [
# Search for tools in your AgentCore gateway with a natural language query
](gateway-using-mcp-semantic-search.md)
+ [
# Create an agent that uses your AgentCore gateway
](gateway-agent-integration.md)
# Authorize and authenticate to an AgentCore gateway and gateway target
To invoke your gateway and gateway target, you’ll need to make sure that the following credentials that you set up while fulfilling the [prerequisites](gateway-prerequisites.md) are recognized during gateway invocation:
+ [Inbound authorization](gateway-inbound-auth.md) – Authorization and authentication to the gateway.
+ [Outbound authorization](gateway-outbound-auth.md) – Authorization and authentication to the gateway target.
To learn how to obtain and configure credentials, review the provider documentation for the methods that you choose.
The following sectiions provide examples of obtaining and configuring credentials for different use cases.
**Topics**
+ [
# Example: Authorization for the default gateway and target created by the AgentCore CLI
](gateway-using-auth-ex-starter.md)
+ [
# Example: Authentication with an authorization code grant when invoking a gateway
](gateway-using-auth-ex-3lo.md)
# Example: Authorization for the default gateway and target created by the AgentCore CLI
If you used the AgentCore CLI to create a gateway and a Lambda target, the CLI configures JWT-based inbound authorization and IAM-based outbound authorization for you automatically.
**Note**
If you invoke your gateway using `agentcore invoke` , the CLI handles authentication automatically. The steps below are only needed if you want to invoke the gateway programmatically (for example, using the AWS SDK or `curl` ).
For programmatic access, you’ll authorize with the following:
+ **Inbound authorization using JWT** – Obtain the access token from the Amazon Cognito authorization that was automatically set up for you and include it in the authorization header. See the example below to learn how to obtain the token.
+ **Outbound authorization using IAM** – The AgentCore CLI configures the following permissions for you, so you don’t need any additional setup:
+ Your gateway service role has permissions to invoke all functions in Lambda (provided by the [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html) managed policy).
+ The created Lambda function is configured with your gateway service role as a `Principal` that can invoke it.
You can obtain the access token created for your gateway by the AgentCore CLI with the help of Amazon Cognito by collecting the following information:
+ **Token endpoint** – Find at the **Discovery URL** in the authorizer configuration for the gateway. If you use the API, you can find the discovery URL by sending a [ListGateways](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_ListGateways.html) request or a [GetGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GetGateway.html) request for your gateway.
+ **Client ID** – Find in the Amazon Cognito user pool information. If you use the API, you can send a [ListUserPools](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUserPools.html) request or a [DescribeUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPool.html) request for the user pool associated with your gateway.
+ **Client secret** – Find in the Amazon Cognito user pool app client information. If you use the API, you can send a [DescribeUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolClient.html) request, specifying the client ID and user pool ID associated with your gateway.
First, collect these values with one of the following methods. Select one of the following methods:
**Example**
1. Get the **token endpoint** :
1. Open the AgentCore console at [https://console.aws.amazon.com/bedrock-agentcore/home\$1](https://console.aws.amazon.com/bedrock-agentcore/home#).
1. From the left navigation pane, choose **Gateways**.
1. In the **Gateways** section, select your gateway.
1. In the **Inbound Identity** section, note the following values:
+ **Allowed clients** – The client IDs that can access the gateway.
+ **Discovery URL** – The format should be `https://cognito-idp.${Region}.amazonaws.com/${UserPoolId}/.well-known/openid-configuration` . Store the following values:
+ `${UserPoolId}` – Extract from the Discovery URL.
+ **Token endpoint** – Select the Discovery URL link and find the value in the `token_endpoint` field.
1. Get the **client ID** and **client secret** :
1. Open the Amazon Cognito console at [https://console.aws.amazon.com/cognito](https://console.aws.amazon.com/cognito).
1. From the left navigation pane, select **User pools**.
1. Select the user pool ID associated with your gateway.
1. From the left navigation pane, choose **App clients**.
1. Select an app client whose **Client ID** matches the allowed clients for your token endpoint. Store the ID value.
1. Under **Client secret** , select **Show client secret** and store that value.
1. Run the AgentCore `get-gateway` command in a terminal and specify your gateway ID in the `--gateway-identifier` argument, as in the following example:
```
aws bedrock-agentcore-control get-gateway --gateway-identifier my-gateway-id
```
1. From the response, note the `discoveryUrl` from the `authorizerConfiguration` field:
+ Store the `${UserPoolId}` from the URL. The format should be `https://cognito-idp.${Region}.amazonaws.com/${UserPoolId}/.well-known/openid-configuration`.
+ Store the `allowedClients` values. These are the client IDs that can access the token endpoint.
+ Navigate to the `discoveryUrl` in a browser and store the `token_endpoint` value.
1. Run the Amazon Cognito `describe-user-pool-client` command in a terminal and specify the user pool ID in the `--user-pool-id` argument and an allowed client ID in the `--client-id` field, as in the following example:
```
aws cognito-idp describe-user-pool-client --user-pool-id my-user-pool-id --client-id my-client-id
```
1. Store the `ClientSecret` value.
1. Run the following Python code to store the token endpoint, client ID, and client secret as variables:
```
import requests
import boto3
# Initialize AWS clients
agentcore_client = boto3.client("bedrock-agentcore-control")
cognito_client = boto3.client("cognito-idp")
# Replace with your actual gateway ID
gateway_id = "my-gateway-id"
# Get discovery URL and first allowed client
auth_config = agentcore_client.get_gateway(gatewayIdentifier=gateway_id)["authorizerConfiguration"]["customJWTAuthorizer"]
discovery_url, client_id = auth_config["discoveryUrl"], auth_config["allowedClients"][0]
# Get token endpoint from discovery URL
discovery_url_json = requests.get(discovery_url).json()
token_endpoint, user_pool_id = discovery_url_json["token_endpoint"], discovery_url_json["issuer"].split("/")[-1]
# Get client secret
client_secret = cognito_client.describe_user_pool_client(
UserPoolId=user_pool_id,
ClientId=client_id
)["UserPoolClient"]["ClientSecret"]
```
Second, use the values you gathered to access the token from the token endpoint. Select one of the following methods:
**Example**
1. Run the following command in a terminal, replacing the token endpoint, client ID, and client secret values.
```
curl --http1.1 -X POST ${TokenEndpoint} \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=${ClientId}&client_secret=${ClientSecret}"
```
The token is in the `access_token` field of the response, while the `token_type` field should specify `Bearer`.
1. Run the following Python code to obtain your access token. The code assumes that you stored the `token_endpoint` , `client_id` , and `client_secret` values from the previous step:
```
import requests
import json
def get_access_token(token_endpoint, client_id, client_secret):
headers={
"Content-Type": "application/x-www-form-urlencoded"
}
payload={
"grant_type": "client_credentials",
"client_id": client_id,
"client_secret": client_secret
}
response = requests.post(token_endpoint, headers=headers, data=payload)
return response.json()
# Replace the argument values as necessary, if you didn't previously store them as these variables
access_token_response = get_access_token(
token_endpoint=token_endpoint,
client_id=client_id,
client_secret=client_secret
)
access_token = access_token_response["access_token"]
```
# Example: Authentication with an authorization code grant when invoking a gateway
If you set up your gateway target with an authorization code grant (for more information, see [OAuth authorization](gateway-building-adding-targets-authorization.md#gateway-building-adding-targets-authorization-oauth) ), the `defaultReturnUrl` that you specified when creating the gateway will be the link that the user’s browser redirects to after authentication.
You can use the `_meta` field in the `params` object of the request body to modify default configurations. With 3LO authentication, you map the `_meta` field to the following object:
```
{
"aws.bedrock-agentcore.gateway/credentialProviderConfiguration": {
"oauthcredentialProvider": {
"returnUrl": "string",
"forceAuthentication": bool
}
}
}
```
You can do the following:
+ To override the default return URL with a different one, specify a new `returnUrl`.
+ To remove the previous authentication from the token vault and return a new authorization URL when the request is made, set the `forceAuthentication` value to `true`.
For example, the following request would call the `LinkedIn3LO___gateUserInfo` tool through the gateway target, force the user to authenticate with a new authorization URL, and redirect the user to `https://your-public-domain.com/callback` after authentication:
```
{
"jsonrpc": "2.0",
"id": 24,
"method": "tools/call",
"params": {
"name": "LinkedIn3LO___getUserInfo",
"arguments": {},
"_meta": {
"aws.bedrock-agentcore.gateway/credentialProviderConfiguration": {
"oauthCredentialProvider": {
"returnUrl": "https://your-public-domain.com/callback",
"forceAuthentication": true
}
}
}
}
}
```
# List available tools in an AgentCore gateway
To list all available tools that an AgentCore gateway provides, make a POST request to the gateway’s MCP endpoint and specify `tools/list` as the method in the request body:
```
POST /mcp HTTP/1.1
Host: ${GatewayEndpoint}
Content-Type: application/json
Authorization: ${Authorization header}
${RequestBody}
```
Replace the following values:
+ `${GatewayEndpoint}` – The URL of the gateway, as provided in the response of the [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) API.
+ `${Authorization header}` – The authorization credentials from the identity provider when you set up [inbound authorization](gateway-inbound-auth.md).
+ `${RequestBody}` – The JSON payload of the request body, as specified in [Listing tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools) in the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) . Include `tools/list` as the `method`.
**Note**
For a list of optionally supported parameters for `tools/list` , see the `params` object in the request body at [Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) in the [Model Context Protocol documentation](https://modelcontextprotocol.io/specification/2025-06-18) . At the top of the page next to the search bar, you can select the MCP version whose documentation you want to view. Make sure that the version is one [supported by Amazon Bedrock AgentCore](gateway-using.md).
The response returns a list of available tools with their names, descriptions, and parameter schemas.
## Code samples for listing tools
To see examples of listing available tools in the gateway, select one of the following methods:
**Example**
1.
```
import requests
import json
def list_tools(gateway_url, access_token):
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {access_token}"
}
payload = {
"jsonrpc": "2.0",
"id": "list-tools-request",
"method": "tools/list"
}
response = requests.post(gateway_url, headers=headers, json=payload)
return response.json()
# Example usage
gateway_url = "https://${GatewayEndpoint}/mcp" # Replace with your actual gateway endpoint
access_token = "${AccessToken}" # Replace with your actual access token
tools = list_tools(gateway_url, access_token)
print(json.dumps(tools, indent=2))
```
1.
```
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def execute_mcp(
url,
token,
headers=None
):
default_headers = {
"Authorization": f"Bearer {token}"
}
headers = {**default_headers, **(headers or {})}
async with streamablehttp_client(
url=url,
headers=headers,
) as (
read_stream,
write_stream,
callA,
):
async with ClientSession(read_stream, write_stream) as session:
# 1. Perform initialization handshake
print("Initializing MCP...")
_init_response = await session.initialize()
print(f"MCP Server Initialize successful! - {_init_response}")
# 2. List available tools
print("Listing tools...")
cursor = True
tools = []
while cursor:
next_cursor = cursor
if type(cursor) == bool:
next_cursor = None
list_tools_response = await session.list_tools(next_cursor)
tools.extend(list_tools_response.tools)
cursor = list_tools_response.nextCursor
tool_names = []
if tools:
for tool in tools:
tool_names.append(tool.name)
tool_names_string = "\n".join(tool_names)
print(
f"List MCP tools. # of tools - {len(tools)}"
f"List of tools - \n{tool_names_string}\n"
)
async def main():
url = "https://${GatewayEndpoint}/mcp"
token = "your_bearer_token_here"
# Optional additional headers
additional_headers = {
"Content-Type": "application/json",
}
await execute_mcp(
url=url,
token=token,
headers=additional_headers
)
# Run the async function
if __name__ == "__main__":
asyncio.run(main())
```
1.
```
from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client
import os
def create_streamable_http_transport(mcp_url: str, access_token: str):
return streamablehttp_client(mcp_url, headers={"Authorization": f"Bearer {access_token}"})
def get_full_tools_list(client):
"""
List tools w/ support for pagination
"""
more_tools = True
tools = []
pagination_token = None
while more_tools:
tmp_tools = client.list_tools_sync(pagination_token=pagination_token)
tools.extend(tmp_tools)
if tmp_tools.pagination_token is None:
more_tools = False
else:
more_tools = True
pagination_token = tmp_tools.pagination_token
return tools
def run_agent(mcp_url: str, access_token: str):
mcp_client = MCPClient(lambda: create_streamable_http_transport(mcp_url, access_token))
with mcp_client:
tools = get_full_tools_list(mcp_client)
print(f"Found the following tools: {[tool.tool_name for tool in tools]}")
run_agent(, )
```
1.
```
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
def list_tools(
url,
headers
):
mcp_client = MultiServerMCPClient(
{
"agent": {
"transport": "streamable_http",
"url": url,
"headers": headers,
}
}
)
tools = asyncio.run(mcp_client.get_tools())
tool_details = []
tool_names = []
for tool in tools:
tool_names.append(f"{tool.name}")
tool_detail = f"{tool.name} - {tool.description} \n"
tool_properties = tool.args_schema.get('properties', {})
properties = []
for property_name, tool_property in tool_properties.items():
properties.append(f"{property_name} - {tool_property.get('description', None)} \n")
tool_details.append(f"{tool_detail}{"\n".join(properties)}")
tool_details_string = "\n".join(tool_details)
tool_names_string = "\n".join(tool_names)
print(
f"Langchain: List MCP tools. # of tools - {len(tools)}\n",
f"Langchain: List of tool names - \n{tool_names_string}\n"
f"Langchain: Details of tools - \n{tool_details_string}\n"
)
```
**Note**
If search is enabled on the gateway, then the search tool, `x_amz_bedrock_agentcore_search` will be listed first in the response.
# Call a tool in a AgentCore gateway
To call a specific tool, make a POST request to the gateway’s MCP endpoint and specify `tools/call` as the method in the request body, name of the tool, and the arguments:
```
POST /mcp HTTP/1.1
Host: ${GatewayEndpoint}
Content-Type: application/json
Authorization: ${Authorization header}
${RequestBody}
```
Replace the following values:
+ `${GatewayEndpoint}` – The URL of the gateway, as provided in the response of the [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) API.
+ `${Authorization header}` – The authorization credentials from the identity provider when you set up [inbound authorization](gateway-inbound-auth.md).
+ `${RequestBody}` – The JSON payload of the request body, as specified in [Calling tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#calling-tools) in the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) . Include `tools/call` as the `method` and include the `name` of the tool and its `arguments`.
The response returns the content returned by the tool and associated metadata.
## Code samples for calling tools
To see examples of listing available tools in the gateway, select one of the following methods:
**Example**
1. The following curl request shows an example request to call a tool called `searchProducts` through a gateway with the ID `mygateway-abcdefghij`.
```
curl -X POST \
https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"jsonrpc": "2.0",
"id": "invoke-tool-request",
"method": "tools/call",
"params": {
"name": "searchProducts",
"arguments": {
"query": "wireless headphones",
"category": "Electronics",
"maxResults": 2,
"priceRange": {
"min": 50.00,
"max": 200.00
}
}
}
}'
```
1.
```
import requests
import json
def call_tool(gateway_url, access_token, tool_name, arguments):
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {access_token}"
}
payload = {
"jsonrpc": "2.0",
"id": "call-tool-request",
"method": "tools/call",
"params": {
"name": tool_name,
"arguments": arguments
}
}
response = requests.post(gateway_url, headers=headers, json=payload)
return response.json()
# Example usage
gateway_url = "https://${GatewayEndpoint}/mcp" # Replace with your actual gateway endpoint
access_token = "${AccessToken}" # Replace with your actual access token
result = call_tool(
gateway_url,
access_token,
"openapi-target-1___get_orders_byId", # Replace with <{TargetId}__{ToolName}>
{"orderId": "ORD-12345-67890", "customerId": "CUST-98765"}
)
print(json.dumps(result, indent=2))
```
1.
```
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import asyncio
async def execute_mcp(
url,
token,
tool_params,
headers=None
):
default_headers = {
"Authorization": f"Bearer {token}"
}
headers = {**default_headers, **(headers or {})}
async with streamablehttp_client(
url=url,
headers=headers,
) as (
read_stream,
write_stream,
callA,
):
async with ClientSession(read_stream, write_stream) as session:
# 1. Perform initialization handshake
print("Initializing MCP...")
_init_response = await session.initialize()
print(f"MCP Server Initialize successful! - {_init_response}")
# 2. Call specific tool
print(f"Calling tool: {tool_params['name']}")
tool_response = await session.call_tool(
name=tool_params['name'],
arguments=tool_params['arguments']
)
print(f"Tool response: {tool_response}")
return tool_response
async def main():
url = "https://${GatewayEndpoint}/mcp"
token = "your_bearer_token_here"
tool_params = {
"name": "LambdaTarget___get_order_tool",
"arguments": {
"orderId": "order123"
}
}
await execute_mcp(
url=url,
token=token,
tool_params=tool_params
)
if __name__ == "__main__":
asyncio.run(main())
```
1. NOTE: This is for invoking agent
```
from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client
def create_streamable_http_transport(mcp_url: str, access_token: str):
return streamablehttp_client(mcp_url, headers={"Authorization": f"Bearer {access_token}"})
def run_agent(mcp_url: str, access_token: str):
mcp_client = MCPClient(lambda: create_streamable_http_transport(mcp_url, access_token))
with mcp_client:
result = mcp_client.call_tool_sync(
tool_use_id="tool-123", # A unique ID for the tool call
name="openapi-target-1___get_orders", # The name of the tool to invoke
arguments={} # A dictionary of arguments for the tool
)
print(result)
url = {gatewayUrl}
token = {AccessToken}
run_agent(url, token)
```
1. NOTE: This is for invoking agent
```
import asyncio
from langgraph.prebuilt import create_react_agent
def execute_agent(
user_prompt,
model_id,
region,
tools
):
model = ChatBedrock(model_id=model_id, region_name=region)
agent = create_react_agent(model, tools)
_response = asyncio.run(agent.ainvoke({
"messages": user_prompt
}))
_response = _response.get('messages', {})[1].content
print(
f"Invoke Langchain Agents Response"
f"Response - \n{_response}\n"
)
return _response
```
## Errors
The `tools/call` operation can return the following types of errors:
+ Errors returned as part of the HTTP status code:
**AuthenticationError**
The request failed due to invalid authentication credentials.
**HTTP Status Code** : 401
**AuthorizationError**
The caller does not have permission to invoke the tool.
**HTTP Status Code** : 403
**ResourceNotFoundError**
The specified tool does not exist.
**HTTP Status Code** : 404
**ValidationError**
The provided arguments do not conform to the tool’s input schema.
**HTTP Status Code** : 400
**ToolExecutionError**
An error occurred while executing the tool.
**HTTP Status Code** : 500
**InternalServerError**
An internal server error occurred.
**HTTP Status Code** : 500
+ MCP errors. For more information about these types of errors, [Error Handling](https://modelcontextprotocol.io/specification/2024-11-05/server/tools#error-handlinghttps://modelcontextprotocol.io/specification/2024-11-05/server/tools#error-handling) in the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) documentation.
# Search for tools in your AgentCore gateway with a natural language query
If you enabled semantic search for your gateway when you created it, you can call the `x_amz_bedrock_agentcore_search` tool to search for tools in your gateway with a natural language query. Semantic search is particularly useful when you have many tools and need to find the most appropriate ones for your use case. To learn how to enable semantic search during gateway creation, see [Create an Amazon Bedrock AgentCore gateway](gateway-create.md).
To search for a tool using this AgentCore tool, make the following POST request with the `tools/call` method to the gateway’s MCP endpoint:
```
POST /mcp HTTP/1.1
Host: ${GatewayEndpoint}
Content-Type: application/json
Authorization: ${Authorization header}
{
"jsonrpc": "2.0",
"id": "${RequestName}",
"method": "tools/call",
"params": {
"name": "x_amz_bedrock_agentcore_search",
"arguments": {
"query": ${Query}
}
}
}
```
Replace the following values:
+ `${GatewayEndpoint}` – The URL of the gateway, as provided in the response of the [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) API.
+ `${Authorization header}` – The authorization credentials from the identity provider when you set up [inbound authorization](gateway-inbound-auth.md).
+ `${RequestName}` – A name for the request.
+ `${Query}` – A natural language query to search for tools.
The response returns a list of tools that are relevant to the query.
## Code samples for tool searching
To see examples of using natural language queries to find tools in the gateway, select one of the following methods:
**Example**
1.
```
import requests
import json
def search_tools(gateway_url, access_token, query):
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {access_token}"
}
payload = {
"jsonrpc": "2.0",
"id": "search-tools-request",
"method": "tools/call",
"params": {
"name": "x_amz_bedrock_agentcore_search",
"arguments": {
"query": query
}
}
}
response = requests.post(gateway_url, headers=headers, json=payload)
return response.json()
# Example usage
gateway_url = "https://${GatewayEndpoint}/mcp" # Replace with your actual gateway endpoint
access_token = "${AccessToken}" # Replace with your actual access token
results = search_tools(gateway_url, access_token, "find order information")
print(json.dumps(results, indent=2))
```
1.
```
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import asyncio
async def execute_mcp(
url,
token,
tool_params,
headers=None
):
default_headers = {
"Authorization": f"Bearer {token}"
}
headers = {**default_headers, **(headers or {})}
async with streamablehttp_client(
url=url,
headers=headers,
) as (
read_stream,
write_stream,
callA,
):
async with ClientSession(read_stream, write_stream) as session:
# 1. Perform initialization handshake
print("Initializing MCP...")
_init_response = await session.initialize()
print(f"MCP Server Initialize successful! - {_init_response}")
# 2. Call specific tool
print(f"Calling tool: {tool_params['name']}")
tool_response = await session.call_tool(
name=tool_params['name'],
arguments=tool_params['arguments']
)
print(f"Tool response: {tool_response}")
return tool_response
async def main():
url = "https://${GatewayEndpoint}/mcp"
token = "your_bearer_token_here"
tool_params = {
"name": "x_amz_bedrock_agentcore_search",
"arguments": {
"query": "How do I find order details?"
}
}
await execute_mcp(
url=url,
token=token,
tool_params=tool_params
)
if __name__ == "__main__":
asyncio.run(main())
```
1.
```
from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client
def create_streamable_http_transport(mcp_url: str, access_token: str):
return streamablehttp_client(mcp_url, headers={"Authorization": f"Bearer {access_token}"})
def get_full_tools_list(client):
"""
List tools w/ support for pagination
"""
more_tools = True
tools = []
pagination_token = None
while more_tools:
tmp_tools = client.list_tools_sync(pagination_token=pagination_token)
tools.extend(tmp_tools)
if tmp_tools.pagination_token is None:
more_tools = False
else:
more_tools = True
pagination_token = tmp_tools.pagination_token
return tools
def run_agent(mcp_url: str, access_token: str):
mcp_client = MCPClient(lambda: create_streamable_http_transport(mcp_url, access_token))
with mcp_client:
tools = get_full_tools_list(mcp_client)
print(f"Found the following tools: {[tool.tool_name for tool in tools]}")
result = mcp_client.call_tool_sync(
tool_use_id="tool-123", # A unique ID for the tool call
name="x_amz_bedrock_agentcore_search", # The name of the tool to invoke
arguments={"query": "find order information"} # A dictionary of arguments for the tool
)
print(result)
url = {gatewayUrl}
token = {AccessToken}
run_agent(url, token)
```
1.
```
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
url = ""
headers = {}
def filter_search_tool(
):
mcp_client = MultiServerMCPClient(
{
"agent": {
"transport": "streamable_http",
"url": url,
"headers": headers,
}
}
)
tools = asyncio.run(mcp_client.get_tools())
builtin_search_tool = []
for tool in tools:
if tool.name == "x_amz_bedrock_agentcore_search":
builtin_search_tool.append(tool)
return builtin_search_tool
def execute_agent(
user_prompt,
model_id,
region,
tools
):
model = ChatBedrock(model_id=model_id, region_name=region)
agent = create_react_agent(model, filter_search_tool())
_response = asyncio.run(agent.ainvoke({
"messages": user_prompt
}))
_response = _response.get('messages', {})[1].content
print(
f"Invoke Langchain Agents Response"
f"Response - \n{_response}\n"
)
return _response
```
# Create an agent that uses your AgentCore gateway
After creating and testing your gateway, you can create and connect AI agents to your gateway. An agent connected to your gateway is able to call the tools in the gateway and use a [Amazon Bedrock model](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) to respond to queries.
To learn how to create an agent, connect it to a gateway, and invoke it to answer queries, select one of the following methods:
**Example**
1.
```
from strands import Agent
from strands.models import BedrockModel
from strands.tools.mcp.mcp_client import MCPClient
from mcp.client.streamable_http import streamablehttp_client
def _invoke_agent(
bedrock_model,
mcp_client,
prompt
):
with mcp_client:
tools = mcp_client.list_tools_sync()
agent = Agent(
model=bedrock_model,
tools=tools
)
return agent(prompt)
def _create_streamable_http_transport(headers=None):
url = {gatewayUrl}
access_token = {AccessToken}
headers = {**headers} if headers else {}
headers["Authorization"] = f"Bearer {access_token}"
return streamablehttp_client(
url,
headers=headers
)
def _get_bedrock_model(model_id):
return BedrockModel(
inference_profile_id=model_id,
temperature=0.0,
streaming=True,
)
mcp_client = MCPClient(_create_streamable_http_transport)
if __name__ == "__main__":
user_prompt = "What orders do I have?"
_response = _invoke_agent(
bedrock_model=_get_bedrock_model("us.anthropic.claude-sonnet-4-20250514-v1:0"),
mcp_client=mcp_client,
prompt=user_prompt
)
print(_response)
```
1.
```
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from langgraph.prebuilt import create_react_agent
from langchain_mcp_adapters.tools import load_mcp_tools
# Replace with actual values and the Amazon Bedrock model of your choice
gateway_url = "${GatewayUrl}"
access_token = "${AccessToken}"
model = ChatBedrock(model_id="anthropic.claude-3-sonnet-20240229-v1:0", region_name="us-west-2")
async with streamablehttp_client(gateway_url, headers={"Authorization": f"Bearer {access_token}"}) as (read, write, _):
async with ClientSession(read, write) as session:
# Initialize the connection
await session.initialize()
# Get tools
tools = await load_mcp_tools(session)
agent = create_react_agent(model, tools)
math_response = await agent.ainvoke({"messages": "what's (3 + 5) x 12?"})
```
1.
```
#!/bin/bash
# Script to add MCP server to Claude
# Server configuration
SERVER_NAME=${ServerName} # Write your server name
GATEWAY_MCP_SERVER_URL=${GatewayUrl} # The gateway MCP URL
AUTH_TOKEN=${AuthToken} # Claude authentication token
echo "Adding MCP server to Claude..."
echo "Server Name: $SERVER_NAME"
echo "Server URL: $SERVER_URL"
echo ""
# Add the MCP server
claude mcp add "$SERVER_NAME" "$GATEWAY_MCP_SERVER_URL" \
--transport http \
--header "Authorization: Bearer $AUTH_TOKEN"
# Check if the command was successful
if [ $? -eq 0 ]; then
echo "MCP server added successfully!"
echo ""
echo "You can now check mcp server health with: claude mcp list"
else
echo "Failed to add MCP server"
exit 1
fi
```
# Fine-grained access control for Amazon Bedrock AgentCore Gateway
Amazon Bedrock AgentCore Gateway provides fine-grained access control capabilities that allow you to control which users and agents can access specific tools and resources. You can implement access control through gateway interceptors for custom logic, or use resource-based policies for standard AWS-style access control. For information about resource-based policies, see [Resource-based policies for Amazon Bedrock AgentCore](security.md#resource-based-policies).
## Using interceptors for access control
Gateway interceptors provide the most flexible way to implement fine-grained access control. REQUEST interceptors execute before the gateway makes a call to the target, allowing you to:
+ Validate user permissions based on JWT claims or custom logic
+ Control access to specific tools or MCP operations
+ Implement role-based or attribute-based access control
+ Filter or modify requests based on user context
+ Return authorization errors for unauthorized requests
For detailed information on implementing and configuring interceptors, including examples of authorization logic, see [Using interceptors with Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-interceptors.html).
## Access control levels
Fine-grained access control in Gateway can be implemented at multiple levels:
**Gateway-level access**
Controls which users or agents can connect to and authenticate with the gateway through OAuth authorization servers or AWS IAM authentication.
**Tool-level access**
Controls access to specific tools within a gateway using interceptor logic to validate permissions before tool execution.
**Operation-level access**
Controls access to specific MCP operations (such as `tools/list` or `tools/call` ) using interceptors to validate operation permissions.
**Parameter-level access**
Controls access to specific parameters or data within operations using interceptors to filter or validate request parameters.
## Implementation approaches
You can implement fine-grained access control using:
**JWT claims validation**
Use interceptors to examine JWT claims such as user roles, departments, or custom attributes to make authorization decisions.
**IAM principal matching**
For IAM-authenticated gateways, implement access control by matching against the caller’s IAM ARN. Use pattern matching on `principal.id` in Cedar policies to restrict access based on AWS accounts, roles, or users.
**External authorization services**
Configure interceptors to call external authorization services or databases to validate user permissions.
**Request context filtering**
Use interceptors to modify requests based on user context, such as adding user-specific filters or limiting data scope.
## Best practices
+ **Principle of least privilege** - Grant users only the minimum access required to perform their tasks.
+ **Use structured claims** - Leverage JWT claims to carry user context and authorization information to your interceptors.
+ **Implement fail-safe defaults** - Design interceptors to deny access by default when authorization cannot be determined.
+ **Log authorization decisions** - Ensure your interceptors log access decisions for auditing purposes.
# Debug and assess your gateway
You can use different tools to help debug your gateway before putting it into a production environment, including built-in AWS and AgentCore Gateway tools, as well as external tools such as the MCP inspector.
You can also debug, monitor, troubleshoot, and assess your gateway’s performance and tool integrations with the help of Amazon CloudWatch. To learn more, see [AgentCore generated gateway observability data](observability-gateway-metrics.md).
The following topics provide more details about different methods that you can use to debug your gateway:
**Topics**
+ [
# Turn on debugging messages
](gateway-debug-messages.md)
+ [
# Use the MCP Inspector
](gateway-using-inspector.md)
+ [
# Log Amazon Bedrock AgentCore Gateway API calls with CloudTrail
](gateway-cloudtrail.md)
# Turn on debugging messages
While your gateway is in development, you can turn on debugging messages to return details on target configuration issues, including lambda function errors, egress authorizer errors, target specification parameter validation errors. After turning on debugging messages, if an issue occurs when you invoke your gateway, the response will return messages to help you debug.
**To turn on debugging messages, do one of the following:**
+ If you use the AgentCore CLI to create a gateway, debugging is automatically turned on.
+ If you use the AWS Management Console to create a gateway, debugging is turned on by default. The option is under **Additional configurations** in the **Gateway details** section.
+ If you use the AWS CLI or an AWS SDK, set the `exceptionLevel` value as `DEBUG` when you make a [CreateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html) or [UpdateGateway](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateGateway.html) request.
When you’re done debugging your gateway, you can update the gateway to turn off debugging messages, such that the message to the end user only shows an unspecified internal error.
**To turn off debugging messages, do one of the following:**
+ In the AWS Management Console, expand **Additional configurations** in the **Gateway details** section when you create or edit a gateway and uncheck the checkbox next to **Exception level debug**.
+ In the AWS CLI or an AWS SDK, omit the `exceptionLevel` field when you make a `CreateGateway` or `UpdateGateway` request to turn off debugging.
## Example gateway responses with debugging turned on and off
As an example, suppose that the user doesn’t have permissions to invoke a Lambda function that is targeted by the gateway. A request that calls this function would return a different message depending on whether debugging is on or off:
+ **Debugging on** – A detailed error message would be returned in the content’s `text` field and also in the `_meta` field in the response, as in the following example:
```
{
"jsonrpc": "2.0",
"id": 24,
"result": {
"content": [
{
"type": "text",
"text": "Access denied while invoking Lambda function arn:aws:lambda:us-west-2:123456789012:function:TestGatewayLambda. Check the permissions on the Lambda function and Gateway execution role, and retry the request."
}
],
"_meta": {
"debug": {
"type": "text",
"text": "Access denied while invoking Lambda function arn:aws:lambda:us-west-2:123456789012:function:TestGatewayLambda. Check the permissions on the Lambda function and Gateway execution role, and retry the request."
}
},
"isError": true
}
}
```
+ **Debugging off** – A generic error message would be returned in the content’s `text` field in the response, as in the following example:
```
{
"jsonrpc": "2.0",
"id": 24,
"result": {
"content": [
{
"type": "text",
"text": "An internal error occurred. Please retry later."
}
],
"isError": true
}
}
```
# Use the MCP Inspector
The MCP Inspector, available through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) , is a developer tool that helps you test and debug MCP servers by through an interactive interface. You can connect your AgentCore gateway to the MCP inspector to help you debug your gateway targets.
For more information about the MCP Inspector, see the [MCP Inspector documentation](https://modelcontextprotocol.io/docs/tools/inspector).
**To connect your gateway to the inspector**
1. Open a terminal and run `npx @modelcontextprotocol/inspector` to do the following:
1. Install the inspector
1. Start the inspector on localhost.
1. Generate a session token for authentication.
1. Open your browser to the inspector interfacee.
1. In the inspector interface, configure the following fields:
+ **Transport Type** – Select **Streamable HTTP**
+ **URL** – Enter the gateway endpoint URL returned when you created your gateway.
+ Expand **Authentication** . The **Custom Headers** section should be pre-populated with one key-value pair.
+ The key’s name should be `Authorization`.
+ Replace the value with your gateway’s [inbound authorization credentials](gateway-inbound-auth.md).
1. Choose **Connect** . You will be connected to your gateway. You can use the MCP Inspector as a tool to examine and test your gateway before integrating it with your agent.
For more information about how you can inspect the MCP server that your gateway is connected to, see **Feature overview** in the [Feature overview](https://modelcontextprotocol.io/docs/tools/inspector) in the [MCP Inspector documentation](https://modelcontextprotocol.io/docs/tools/inspector).
**Important**
The MCP Inspector is a development tool and should not be used in production environments. Always secure your access tokens and gateway credentials.
## Troubleshooting
If you encounter issues when using the MCP Inspector with your gateway, check the following:
+ **Connection issues** : Ensure that your gateway URL is correct and accessible from your network
+ **Authentication issues** : Verify that your access token is valid and has not expired
+ **Tool invocation errors** : Check the error messages in the response and ensure that your input parameters match the tool’s schema
+ **Proxy errors** : If you see errors related to the proxy connection, try restarting the MCP Inspector
# Log Amazon Bedrock AgentCore Gateway API calls with CloudTrail
Amazon Bedrock AgentCore Gateway is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Gateway. CloudTrail captures all API calls for Gateway as events, including calls from the Gateway console and code calls to the Gateway APIs. Using the information collected by CloudTrail, you can determine the request that was made to Gateway, who made the request, when it was made, and additional details. There are two types of events: **Management events** and **Data events**.
For more information about using CloudTrail with Gateway, see the following resources:
+ [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)
+ [Creating a Trail for Your AWS Account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [AWS CloudTrail API Reference](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/)
+ [AWS CloudTrail CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/index.html)
**Topics**
+ [
# Amazon Bedrock AgentCore Gateway event types
](gateway-event-types.md)
+ [
# Enable CloudTrail data event logging for Amazon Bedrock AgentCore Gateway resources
](enabling-cloudtrail-data-event-logging.md)
+ [
# Understanding Amazon Bedrock AgentCore Gateway CloudTrail events
](understanding-gateway-cloudtrail-log-entries.md)
# Amazon Bedrock AgentCore Gateway event types
This section provides information about the types of events that Amazon Bedrock AgentCore Gateway logs to CloudTrail.
**Topics**
+ [
## Amazon Bedrock AgentCore Gateway management events in CloudTrail
](#gateway-management-events)
+ [
## Amazon Bedrock AgentCore Gateway data events in CloudTrail
](#gateway-data-events)
## Amazon Bedrock AgentCore Gateway management events in CloudTrail
Every management event or log entry contains information about who generated the request. The identity information helps you determine the following:
+ Whether the request was made with root user or user credentials.
+ Whether the request was made on behalf of an IAM Identity Center user.
+ Whether the request was made with temporary security credentials for a role or federated user.
+ Whether the request was made by another AWS service.
CloudTrail is active in your AWS account when you create the account and you automatically have access to the CloudTrail *Event history* . The CloudTrail *Event history* provides a viewable, searchable, downloadable, and immutable record of the past 90 days of recorded management events in an AWS Region.
For an ongoing record of events in your AWS account past 90 days, create a trail or a CloudTrail Lake event data store.
Gateway logs management events for the following operations:
| Operation | Description |
| --- | --- |
| CreateGateway | Creates a new gateway |
| CreateGatewayTarget | Creates a new target for a gateway |
| DeleteGateway | Deletes a gateway |
| DeleteGatewayTarget | Deletes a gateway target |
| GetGateway | Gets information about a gateway |
| GetGatewayTarget | Gets information about a gateway target |
| ListGatewayTargets | Lists all targets for a gateway |
| ListGateways | Lists all gateways |
| UpdateGateway | Updates an existing gateway |
| UpdateGatewayTarget | Updates an existing gateway target |
## Amazon Bedrock AgentCore Gateway data events in CloudTrail
Data events provide information about the resource operations performed on or in a resource. These are also known as data plane operations. Data events are often high-volume activities. You must explicitly enable data events because they are not logged by default. The CloudTrail *Event history* doesn’t record data events.
Additional charges apply for logging data events. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/).
To learn how to enable logging data events for the Gateway resource types, see [Enable CloudTrail data event logging for Amazon Bedrock AgentCore Gateway resources](enabling-cloudtrail-data-event-logging.md).
The following table lists the Gateway resource types for which you can enable data events:
| Data event type | resources.type value | Data APIs logged to CloudTrail |
| --- | --- | --- |
| Bedrock-AgentCore gateway | AWS::BedrockAgentCore::Gateway | InvokeGateway |
### Identity information in data events
Amazon Bedrock AgentCore Gateway data events differ from standard AWS data events in how identity information is stored. Because the Data API follows the MCP protocol and uses JSON Web Token (JWT)-based authentication rather than SigV4, Amazon Bedrock AgentCore Gateway data events don’t have standard AWS identity information. Instead, identity is captured by logging specific JWT claims, including the "sub" claim.
**Note**
We recommend that you avoid using any personally identifiable information (PII) in this field. For example, you could use a GUID or a pairwise identifier, as suggested in the [OIDC specification](http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) instead of PII data like email.
### Error information in data events
Amazon Bedrock AgentCore Gateway provides error information as part of the `responseElements` field rather than as top-level `errorCode` and `errorMessage` fields. If you’re looking for specific error types such as AccessDenied events, parse through the `responseElements` field in the CloudTrail event.
### Data event routing
Because Amazon Bedrock AgentCore Gateway uses JWT tokens for authentication rather than SigV4 credentials, data events are only routed to the resource owner account.
# Enable CloudTrail data event logging for Amazon Bedrock AgentCore Gateway resources
You can use CloudTrail data events to get information about Amazon Bedrock AgentCore Gateway requests. To enable CloudTrail data events for Gateway, you must create a trail manually in CloudTrail backed by an Amazon S3 bucket.
**Key considerations**
+ Data event logging incurs additional charges. You must explicitly enable data events as they are not captured by default. Check to ensure that you have data events enabled for your account.
+ With a gateway that is generating a high workload, you could quickly generate thousands of logs in a short amount of time. Be mindful of how long you choose to enable CloudTrail data events for a busy Gateway.
+ CloudTrail stores gateway data event logs in an Amazon S3 bucket of your choosing. Consider using a bucket in a separate AWS account to better organize events from multiple resources into a central place for easier querying and analysis.
When you log data events for a trail in CloudTrail, you must use advanced event selectors to log data events for gateway operations.
**Example**
1. To enable CloudTrail data events for gateway resources using the AWS CLI, you can run the following command in a terminal:
```
aws cloudtrail put-event-selectors \
--trail-name brac-gateway-canary-trail-prod-us-east-1 \
--region us-east-1 \
--advanced-event-selectors '[
{
"Name": "GatewayDataEvents",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": ["Data"]
},
{
"Field": "resources.type",
"Equals": ["AWS::BedrockAgentCore::Gateway"]
}
]
}
]'
```
1. The following example demonstrates how to create a CloudTrail trail with AgentCore Gateway data events using the AWS CDK:
```
import { Construct } from 'constructs';
import { Trail, CfnTrail } from 'aws-cdk-lib/aws-cloudtrail';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Effect, PolicyStatement, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
import { RemovalPolicy } from 'aws-cdk-lib';
export interface DataEventTrailProps {
/**
* Whether to enable multi-region trail
*/
isMultiRegionTrail?: boolean;
/**
* Whether to include global service events
*/
includeGlobalServiceEvents?: boolean;
/**
* AWS region
*/
region: string;
/**
* Environment account ID
*/
account: string;
}
/**
* Creates a CloudTrail trail configured to capture data events for Bedrock Agent Core Gateway
*/
export class BedrockAgentCoreDataEventTrail extends Construct {
/**
* The CloudTrail trail
*/
public readonly trail: Trail;
/**
* The S3 bucket for CloudTrail logs
*/
public readonly logsBucket: Bucket;
constructor(scope: Construct, id: string, props: DataEventTrailProps) {
super(scope, id);
// Create S3 bucket for CloudTrail logs
const bucketName = `brac-gateway-cloudtrail-logs-${props.account}-${props.region}`;
this.logsBucket = new Bucket(this, 'CloudTrailLogsBucket', {
bucketName,
removalPolicy: RemovalPolicy.RETAIN,
});
// Create trail name (suffixing region since regional trail)
const trailName = `brac-gateway-trail-${props.region}`;
// Add CloudTrail bucket policy
this.logsBucket.addToResourcePolicy(
new PolicyStatement({
sid: 'AWSCloudTrailAclCheck',
effect: Effect.ALLOW,
principals: [new ServicePrincipal('cloudtrail.amazonaws.com')],
actions: ['s3:GetBucketAcl'],
resources: [this.logsBucket.bucketArn],
conditions: {
StringEquals: {
'aws:SourceArn': `arn:aws:cloudtrail:${props.region}:${props.account}:trail/${trailName}`,
},
},
}),
);
this.logsBucket.addToResourcePolicy(
new PolicyStatement({
sid: 'AWSCloudTrailWrite',
effect: Effect.ALLOW,
principals: [new ServicePrincipal('cloudtrail.amazonaws.com')],
actions: ['s3:PutObject'],
resources: [this.logsBucket.arnForObjects(`AWSLogs/${props.account}/*`)],
conditions: {
StringEquals: {
's3:x-amz-acl': 'bucket-owner-full-control',
'aws:SourceArn': `arn:aws:cloudtrail:${props.region}:${props.account}:trail/${trailName}`,
},
},
}),
);
// Create CloudTrail trail
this.trail = new Trail(this, 'GatewayDataEventTrail', {
trailName,
bucket: this.logsBucket,
isMultiRegionTrail: props.isMultiRegionTrail ?? false,
includeGlobalServiceEvents: props.includeGlobalServiceEvents ?? true,
enableFileValidation: true,
});
// Add advanced event selectors for Bedrock Agent Core Gateway data events
const cfnTrail = this.trail.node.defaultChild as CfnTrail;
// Define the advanced event selectors
const advancedEventSelectors = [
{
// Log Bedrock Agent Core Gateway Data Events only
fieldSelectors: [
{
field: 'eventCategory',
equalTo: ['Data'],
},
{
field: 'resources.type',
equalTo: ['AWS::BedrockAgentCore::Gateway'],
},
],
},
];
// Clear any existing event selectors and set advanced event selectors
cfnTrail.eventSelectors = undefined;
cfnTrail.advancedEventSelectors = advancedEventSelectors;
}
}
```
# Understanding Amazon Bedrock AgentCore Gateway CloudTrail events
A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information such as the requested action, the date and time of the action, and request parameters.
**Note**
The contents of the requests and responses for data events are redacted, and the JSON Web Token (JWT) claims have HTML entities sanitized for security purposes.
The following sections show examples of CloudTrail events:
**Topics**
+ [
## InvokeGateway data event with authentication error
](#understanding-gateway-cloudtrail-log-entries-data-auth-error)
+ [
## Successful InvokeGateway data event
](#understanding-gateway-cloudtrail-log-entries-data-successful)
+ [
## Management Event
](#understanding-gateway-cloudtrail-log-entries-management)
## InvokeGateway data event with authentication error
The following example shows a CloudTrail log entry that demonstrates the `InvokeGateway` action with an authentication error. The authentication error can be seen in hte `body` field of the `responseElements`.
```
{
"eventVersion": "1.11",
"userIdentity": {
"type": "AWSAccount",
"principalId": "",
"accountId": "anonymous"
},
"eventTime": "2025-07-14T02:14:42Z",
"eventSource": "bedrock-agentcore.amazonaws.com",
"eventName": "InvokeGateway",
"awsRegion": "us-west-2",
"sourceIPAddress": "34.XXX.XXX.206",
"userAgent": "python-httpx/0.28.1",
"requestParameters": {
"body": {
"id": 0,
"method": "initialize",
"params": {
"clientInfo": {
"name": "mcp",
"version": "0.1.0"
},
"protocolVersion": "2025-06-18",
"capabilities": {}
},
"jsonrpc": "2.0"
}
},
"responseElements": {
"body": {
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": -32001,
"message": "Invalid Bearer token"
}
},
"contentType": "application/json",
"statusCode": 401
},
"requestID": "1234abcd-12ab-34cd-56ef-1234567890ab",
"eventID": "12345678-1234-5678-9abc-123456789012",
"readOnly": false,
"resources": [
{
"accountId": "XXXXXXXXXX",
"type": "AWS::BedrockAgentCore::Gateway",
"ARN": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXX:gateway/test-openapi-gateway-b24f8c26-u9p3rjw8qw"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "XXXXXXXXXX",
"sharedEventID": "12345678-xxxx-xxxx-xxxx-123456789012",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "test-openapi-gateway-xxxxxxx-u9p3rjw8qw.gateway.bedrock-agentcore.us-west-2.amazonaws.com"
}
}
```
## Successful InvokeGateway data event
The following example shows a CloudTrail log entry for a successful `InvokeGateway` action:
```
{
"eventVersion": "1.11",
"userIdentity": {
"type": "AWSAccount",
"principalId": "",
"accountId": "anonymous"
},
"eventTime": "2025-07-14T02:14:42Z",
"eventSource": "bedrock-agentcore.amazonaws.com",
"eventName": "InvokeGateway",
"awsRegion": "us-west-2",
"sourceIPAddress": "35.88.103.184",
"userAgent": "python-httpx/0.28.1",
"requestParameters": {
"body": {
"id": 1,
"method": "tools/call",
"params": {
"name": "SmithyTarget___ListTables",
"arguments": "REDACTED"
},
"jsonrpc": "2.0"
}
},
"responseElements": {
"body": {
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": false,
"content": "REDACTED"
}
},
"contentType": "application/json",
"statusCode": 200
},
"additionalEventData": {
"targetId": "0JTXXX4YMA",
"jwt": {
"headers": {
"kid": "hGrcJwz5MX6hNeuL6jdXE4hjK7sT6oj+yN7kN+arRv4=",
"alg": "RS256"
},
"claims": {
"sub": "4ammgxxxxxxxxxxxm3b8c",
"token_use": "access",
"scope": "python-cognito-resource-server-id/write python-cognito-resource-server-id/read",
"auth_time": 1752459276,
"iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_Fxxxxxhtq",
"exp": 1752462876,
"iat": 1752459276,
"version": 2,
"jti": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
"type": "JWS"
},
"downstreamRequestIds": [
"H3RDH6T03DG10996U0M2P1V1IFVV4KQNSO5AEMVJF66Q9ASUAAJG"
]
},
"requestID": "1234abcd-12ab-34cd-56ef-1234567890ab",
"eventID": "12345678-1234-5678-9abc-123456789012",
"readOnly": false,
"resources": [
{
"accountId": "XXXXXXXXXX",
"type": "AWS::BedrockAgentCore::Gateway",
"ARN": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXX:gateway/test-gateway-65129e91-mtzoadyihf"
}
],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "XXXXXXXXXX",
"sharedEventID": "1234abcd-12ab-34cd-56ef-1234567890ab",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "test-gateway-65129e91-xxxxxxxx.gateway.bedrock-agentcore.us-west-2.amazonaws.com"
}
}
```
## Management Event
The following example shows a CloudTrail log entry for a management event:
```
{
"eventVersion": "1.09",
"userIdentity": {
"type": "AssumedRole",
"principalId": "AROXXXXXXXXXXXXNRD7D:xxxxx",
"arn": "arn:aws:sts::XXXXXXXXXXXX:assumed-role/HydraInvocationRole-xxxxxxxxx/xxxx",
"accountId": "XXXXXXXXXXXX",
"accessKeyId": "xxxxxxxxx",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "xxxxxxxx",
"arn": "arn:aws:iam::XXXXXXXXXXXX:role/HydraInvocationRole-xxx",
"accountId": "XXXXXXXXXXXX",
"userName": "HydraInvocationRole-xxxxx"
},
"attributes": {
"creationDate": "2025-07-14T02:42:43Z",
"mfaAuthenticated": "false"
}
},
"invokedBy": "bedrock-agentcore.amazonaws.com"
},
"eventTime": "2025-07-14T02:47:38Z",
"eventSource": "bedrock-agentcore.amazonaws.com",
"eventName": "CreateGateway",
"awsRegion": "us-west-2",
"sourceIPAddress": "bedrock-agentcore.amazonaws.com",
"userAgent": "bedrock-agentcore.amazonaws.com",
"requestParameters": {
"roleArn": "arn:aws:iam::XXXXXXXXXXXX:role/PythonGenesisTestGatewayRole",
"name": "***",
"authorizerConfiguration": {
"customJWTAuthorizer": {
"allowedClients": [
"xxxxxxxxx"
],
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_xxxxx/.well-known/openid-configuration"
}
},
"description": "***",
"protocolType": "MCP",
"authorizerType": "CUSTOM_JWT"
},
"responseElements": {
"authorizerConfiguration": {
"customJWTAuthorizer": {
"allowedClients": [
"xxxxxxxxxxxxxxx"
],
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_xxxxxx/.well-known/openid-configuration"
}
},
"description": "***",
"protocolType": "MCP",
"gatewayArn": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXXXX:gateway/test-openapi-gateway-xxxxxxx-xxxxxx",
"workloadIdentityDetails": {
"workloadIdentityArn": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXXXX:workload-identity-directory/default/workload-identity/test-openapi-gateway-xxxxxx-xxxxx"
},
"createdAt": "2025-07-14T02:47:38.302834063Z",
"gatewayUrl": "https://test-openapi-gateway-xxxxxxx-8fb4mo6pqx.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
"roleArn": "arn:aws:iam::XXXXXXXXXXXX:role/PythonGenesisTestGatewayRole",
"name": "***",
"authorizerType": "CUSTOM_JWT",
"gatewayId": "test-openapi-gateway-9c8f7109-8fb4mo6pqx",
"status": "CREATING",
"updatedAt": "2025-07-14T02:47:38.302845797Z"
},
"requestID": "0fb99b0b-a4d1-xxxx-8aee-c703adaa6bd9",
"eventID": "b12bf859-xxxx-48d7-952a-d5c6ec00fb68",
"readOnly": false,
"resources": [
{
"accountId": "XXXXXXXXXXXX",
"type": "AWS::BedrockAgentCore::Gateway",
"ARN": "arn:aws:bedrock-agentcore:us-west-2:XXXXXXXXXXXX:gateway/test-openapi-gateway-xxxxxxx-8fb4mo6pqx"
}
],
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "XXXXXXXXXXXX",
"eventCategory": "Management"
}
```
# Advanced features and topics for Amazon Bedrock AgentCore Gateway
This chapter covers some advanced topics and additional information that can help supplement your knowledge of gateways and how you can use them effectively in your applications.
**Topics**
+ [
# Encrypt your AgentCore gateway with a customer-managed KMS key
](gateway-encryption.md)
+ [
# Setting up custom domain names for Gateway endpoints
](gateway-custom-domains.md)
+ [
# Using interceptors with Gateway
](gateway-interceptors.md)
+ [
# Header propagation with Gateway
](gateway-headers.md)
+ [
# Performance optimization
](gateway-advanced-performance.md)
# Encrypt your AgentCore gateway with a customer-managed KMS key
By default, Gateway encrypts your data at rest using a service-managed AWS Key Management Service key. However, you can optionally provide your own customer managed KMS key for encrypting data at rest when you:
+ Create a gateway.
+ Update a gateway’s configurations.
Using a customer managed key gives you more control over the encryption process, including the ability to:
+ Rotate the key on your own schedule
+ Control access to the key through IAM policies
+ Disable or delete the key when it’s no longer needed
+ Audit key usage through CloudWatch logs and AWS CloudTrail
For more information, see [AWS Key Management Service Developer Guide](https://docs.aws.amazon.com/kms/latest/developerguide/).
**Note**
If you choose to use a customer managed key, you are responsible for managing the key and its permissions. If the key is disabled or deleted, or if Gateway loses permission to use the key, you will lose access to the encrypted data.
## Prerequisites for encrypting your AgentCore gateway
Before encrypting your gateway, ensure that you have fulfilled the following prerequsites:
+ You have access to a KMS key. For information about creating a KMS key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).
+ The KMS key has a key policy attached to it that allows the following permissions:
+ Permissions that allow the gateway service role to perform the following actions:
+ kms:CreateGrant
+ kms:DescribeKey
+ kms:Decrypt
+ kms:GenerateDataKey
+ (If you enable CloudWatch Logs for your gateway) Permissions that allow the CloudWatch Logs service to decrypt the key.
For more information about controlling IAM permissions for a KMS key, see [KMS key access and permissions](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html) in the AWS Key Management Service Developer Guide.
**Example key policy**
The following example policy provides the necessary permissions to encrypt a gateway and use an encrypted gateway. The fourth statement also allows CloudWatch Logs logging of key usage for the encrypted gateway. The policy contains condition keys to conform to security best practices.
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowServiceRoleDescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
},
"Action": [
"kms:DescribeKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"bedrock-agentcore.us-east-1.amazonaws.com"
]
}
}
},
{
"Sid": "AllowServiceRoleDecryptKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"bedrock-agentcore.us-east-1.amazonaws.com"
]
},
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore-gateway:arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/GatewayId"
}
}
},
{
"Sid": "AllowServiceRoleCreateGrant",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/GatewayServiceRole"
},
"Action": "kms:CreateGrant",
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"bedrock-agentcore.us-east-1.amazonaws.com"
],
"kms:GrantConstraintType": "EncryptionContextSubset"
},
"ForAllValues:StringEquals": {
"kms:GrantOperations": [
"Decrypt",
"GenerateDataKey"
]
},
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore-gateway:arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/GatewayId"
}
}
},
{
"Sid": "AllowKMSDecryptionLogging",
"Effect": "Allow",
"Principal": {
"Service": "delivery.logs.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"kms:EncryptionContext:SourceArn": "arn:aws:logs:us-east-1:123456789012:*"
}
}
}
]
}
```
The policy contains the following statements:
+ **AllowServiceRoleDescribeKKey** – Allows the specified principal to describe the key if the request is made through the AgentCore service. Replace values in the following fields:
+ `Principal` – Replace the `AWS` value with the actual ARN of your gateway service role.
+ `Condition` – In the `kms:ViaService` array, replace *us-east-1* with the actual AWS Region for which you want to allow the key to be described.
+ **AllowServiceRoleDecryptKey** – Allows the specified principal to decrypt the key if the request is made through the AgentCore service and if the ARN of the gateway to which the request is made matches the one in the `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` field. Replace the following values:
+ `Principal` – Replace the `AWS` value with the actual ARN of your gateway service role.
+ `Condition` – Do the following:
+ In the `kms:ViaService` array, replace *us-east-1* with the actual AWS Region for which you want to allow the key to be decrypted.
+ Replace the `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` value with the actual ARN of your gateway.
+ **AllowServiceRoleCreateGrant** – Allows the specified principal to create a grant for a key if the request is made through the AgentCore service and if the ARN of the gateway to which the request is made matches the one in the `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` field. Replace the following values:
+ `Principal` – Replace the `AWS` value with the actual ARN of your gateway service role.
+ `Condition` – Do the following:
+ In the `kms:ViaService` array, replace *us-east-1* with the actual AWS Region for which you want to allow the key to be decrypted.
+ Replace the `kmsEncryptionContext:aws:bedrock-agentcore-gateway-arn` value with the actual ARN of your gateway (if you want to allow).
+ **AllowKMSDecryptionLogging** – Allows the specified principal to decrypt a customer-managed KMS key for auditing key usage through CloudWatch Logs. In the `kms:EncryptionContext:SourceArn` value, replace *us-east-1* and *123456789012* values with your actual AWS Region and account ID.
**Example**
1. ====== To encrypt your gateway with a customer-managed KMS key
1. Follow the **Console** steps at [Create an Amazon Bedrock AgentCore gateway](gateway-create.md) and expand the **KMS key - optional** section.
1. Choose **Customize encryption settings (advanced)**.
1. Select a KMS key and confirm its details.
**Note**
If you don’t see your KMS key, go over the [Prerequisites for encrypting your AgentCore gateway](#gateway-encryption-prereqs) and check that the permissions are properly configured.
1. Continue through the remaining console steps.
1. To encrypt your gateway using the AWS CLI, include the `kms-key-arn` when sending either of the following requests through an [AgentCore control plane](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/) client.:
+ [create-gateway](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/create-gateway.html)
+ [update-gateway](https://docs.aws.amazon.com/cli/latest/reference/bedrock-agentcore-control/update-gateway.html)
The following example shows an example CLI request to create a gateway with a AWS KMS key specified using the `kms-key-arn` argument:
```
aws bedrock-agentcore-control create-gateway \
--name "MyGateway" \
--role-arn "arn:aws:iam::123456789012:role/GatewayRole" \
--protocol-type "MCP" \
--kms-key-arn "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--authorizer-type "CUSTOM_JWT" \
--authorizer-configuration '{
"customJWTAuthorizer": {
"allowedAudience": ["myAudience"],
"discoveryUrl": "https://example.com/.well-known/openid-configuration"
}
}'
```
1. To encrypt your gateway using the AWS Python SDK (Boto3), include the `kms-key-arn` when sending either of the following requests through an [AgentCore control plane](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control.html) client.:
+ [create\$1gateway](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control/client/create_gateway.html)
+ [update\$1gateway](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agentcore-control/client/update_gateway.html)
The following example shows an example Boto3 request to create a gateway with a AWS KMS key specified using the `kmsKeyArn` argument:
```
import boto3
# Create client
agentcore_client = boto3.client('bedrock-agentcore-control')
# Create gateway and specify
gateway = agentcore_client.create_gateway(
name="MyGateway",
roleArn="arn:aws:iam::123456789012:role/GatewayRole",
protocolType="MCP",
kmsKeyArn="arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
authorizerType="CUSTOM_JWT",
authorizerConfiguration= {
"customJWTAuthorizer": {
"allowedAudience": ["myAudience"],
"discoveryUrl": "https://example.com/.well-known/openid-configuration"
}
}
)
```
# Setting up custom domain names for Gateway endpoints
By default, Gateway endpoints are provided with an AWS-managed domain name in the format `.gateway.bedrock-agentcore..amazonaws.com` . For production environments or to create a more user-friendly experience, you may want to use a custom domain name for your gateway endpoint. This section guides you through setting up a custom domain name using Amazon CloudFront as a reverse proxy.
## Prerequisites
Before you begin, ensure you have:
+ A working Gateway endpoint
+ DNS delegation (if your Route 53 domain needs to be publicly reachable)
+ AWS CDK installed and configured (if following the CDK approach)
+ Appropriate IAM permissions to create and manage CloudFront distributions, Route 53 hosted zones, and ACM certificates
## Solution overview
The solution involves the following components:
+ **Route 53 Hosted Zone** : Manages DNS records for your custom domain
+ **ACM Certificate** : Provides SSL/TLS encryption for your custom domain
+ **CloudFront Distribution** : Acts as a reverse proxy, forwarding requests from your custom domain to the Gateway endpoint
+ **Route 53 A Record** : Maps your custom domain to the CloudFront distribution
The following steps will guide you through setting up these components using AWS CDK.
## Implementation steps
### Step 1: Create a Route 53 hosted zone
First, create a Route 53 hosted zone for your custom domain:
```
import { RemovalPolicy } from 'aws-cdk-lib';
import { PublicHostedZone } from 'aws-cdk-lib/aws-route53';
const domainName = 'my.example.com';
const hostedZone = new PublicHostedZone(this, 'HostedZone', {
zoneName: domainName,
});
this.hostedZone.applyRemovalPolicy(RemovalPolicy.RETAIN);
```
**Note**
We apply a removal policy of `RETAIN` to prevent accidental deletion of the hosted zone during stack updates or deletion.
### Step 2: Create a DNS-validated certificate
Next, create an SSL/TLS certificate for your custom domain using AWS Certificate Manager (ACM) with DNS validation:
```
import { RemovalPolicy } from 'aws-cdk-lib';
import { Certificate, CertificateValidation } from 'aws-cdk-lib/aws-certificatemanager';
const certificate = new Certificate(this, 'SSLCertificate', {
domainName: domainName, // route53 hosted zone domain name from step 1
validation: CertificateValidation.fromDns(hostedZone), // route53 hosted zone from step 1
});
this.certificate.applyRemovalPolicy(RemovalPolicy.RETAIN);
```
DNS validation automatically creates the necessary validation records in your Route 53 hosted zone.
### Step 3: Create a CloudFront distribution
Create a CloudFront distribution to act as a reverse proxy for your Gateway endpoint:
```
import {
AllowedMethods,
CachePolicy,
Distribution,
OriginProtocolPolicy,
ViewerProtocolPolicy
} from 'aws-cdk-lib/aws-cloudfront';
import { HttpOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';
const bedrockAgentCoreGatewayHostName = '.gateway.bedrock-agentcore..amazonaws.com'
const bedrockAgentCoreGatewayPath = '/mcp' // can also be left undefined, depending on your requirement
const distribution = new Distribution(this, 'Distribution', {
defaultBehavior: {
origin: new HttpOrigin(bedrockAgentCoreGatewayHostName, {
protocolPolicy: OriginProtocolPolicy.HTTPS_ONLY,
originPath: bedrockAgentCoreGatewayPath,
}),
viewerProtocolPolicy: ViewerProtocolPolicy.HTTPS_ONLY,
cachePolicy: CachePolicy.CACHING_DISABLED, // important since caching is enabled by default and hence is not suitable for a reverse proxy
allowedMethods: AllowedMethods.ALLOW_ALL,
},
domainNames: [domainName], // route53 hosted zone domain name from step 1
certificate: certificate, // ssl certificate for the route53 domain from step 2
});
```
**Important**
Set `cachePolicy: CachePolicy.CACHING_DISABLED` to ensure that CloudFront doesn’t cache responses from your Gateway endpoint, which is important for dynamic API interactions.
Replace `` with your gateway ID and `` with your AWS Region (e.g., `us-east-1` ).
### Step 4: Create a Route 53 A record
Create a Route 53 A record that points your custom domain to the CloudFront distribution:
```
import { ARecord, RecordTarget } from 'aws-cdk-lib/aws-route53';
import { CloudFrontTarget } from 'aws-cdk-lib/aws-route53-targets';
const aRecord = new ARecord(this, 'AliasRecord', {
zone: hostedZone, // route53 hosted zone from step 1
recordName: domainName, // route53 hosted zone domain name from step 1
target: RecordTarget.fromAlias(new CloudFrontTarget(distribution)), // cloufront distribution from from step 3
});
```
This creates an alias record that maps your custom domain to the CloudFront distribution.
### Step 5: Deploy your infrastructure
Deploy your CDK stack to create the resources:
```
cdk deploy
```
The deployment process may take some time, especially for the certificate validation and CloudFront distribution creation.
## Testing your custom domain
After deploying your infrastructure, verify that your custom domain is properly configured:
### Verify DNS resolution
Use the `dig` command to verify that your custom domain resolves to the CloudFront distribution:
```
dig my.example.com
```
The output should show that your domain resolves to CloudFront’s IP addresses.
### Verify SSL certificate
Use `curl` to verify that the SSL certificate is properly configured:
```
curl -v https://my.example.com
```
The output should show a successful SSL handshake with no certificate errors.
## Configuring MCP clients
Once your custom domain is set up and verified, you can configure your MCP clients to use it:
### Cursor configuration
For Cursor, update your configuration file:
```
{
"mcpServers": {
"my-mcp-server": {
"url": "https://my.example.com"
}
}
}
```
### Other MCP clients
For MCP clients that don’t natively support streamable HTTP:
```
{
"mcpServers": {
"my-mcp-server": {
"command": "/path/to/uvx",
"args": [
"mcp-proxy",
"--transport",
"streamablehttp",
"https://my.example.com"
]
}
}
}
```
## Additional considerations
**Cost implications**
Using CloudFront as a reverse proxy incurs additional costs for data transfer and request handling. Review the CloudFront pricing model to understand the cost implications for your specific use case.
**Security considerations**
Consider implementing additional security measures such as:
+ WAF rules to protect your endpoint from common web exploits
+ Geo-restrictions to limit access to specific geographic regions
+ Custom headers or request signing to add an extra layer of authentication
**Monitoring and logging**
Enable CloudFront access logs and configure CloudWatch alarms to monitor the health and performance of your custom domain setup.
**Certificate renewal**
ACM certificates issued through DNS validation are automatically renewed as long as the DNS records remain in place. Ensure that you don’t delete the validation records.
**OAuth protected resource endpoint with custom domains**
By default, the `/.well-known/oauth-protected-resource` endpoint returns a resource URL that contains the gateway domain instead of your custom domain. This can cause OAuth clients to fail authentication when using custom domains.
To resolve this issue, you can implement a Lambda@Edge function that intercepts the OAuth discovery response and generates a new response with the correct custom domain URL. Here’s the approach:
+ **Use Lambda@Edge with ORIGIN\$1RESPONSE event type** : Create a function that triggers on origin responses to intercept the OAuth protected resource endpoint response.
+ **Generate a new response** : Lambda@Edge cannot read origin response bodies, so instead of modifying the existing response, generate a completely new JSON response with the custom domain.
+ **Associate with CloudFront behavior** : Configure the Lambda@Edge function to trigger specifically for the `/.well-known/oauth-protected-resource` path pattern.
After implementing this solution, the OAuth protected resource endpoint will return the correct custom domain:
```
curl https://my-custom-domain.com/.well-known/oauth-protected-resource
{
"authorization_servers": ["https://my-org.okta.com/oauth2/default"],
"resource": "https://my-custom-domain.com/mcp"
}
```
**Note**
While Lambda@Edge provides a solution for this issue, implementing custom domains for AgentCore Gateway without built-in support requires additional complexity that may not be optimal for all customers. Consider this approach as a workaround until native support for OAuth discovery with custom domains becomes available.
## Troubleshooting
**DNS resolution issues**
If your custom domain doesn’t resolve correctly:
+ Verify that the A record is correctly configured in your Route 53 hosted zone
+ Check that your domain’s name servers are correctly set at your domain registrar
+ Allow time for DNS propagation (up to 48 hours in some cases)
**SSL certificate issues**
If you encounter SSL certificate errors:
+ Verify that the certificate is issued and active in the ACM console
+ Check that the certificate is correctly associated with your CloudFront distribution
+ Ensure that the certificate covers the exact domain name you’re using
**Gateway connectivity issues**
If your custom domain doesn’t connect to your gateway:
+ Verify that the origin domain and path in your CloudFront distribution are correct
+ Check that your gateway endpoint is accessible directly
+ Review CloudFront distribution logs for any errors
## Conclusion
Setting up a custom domain name for your Gateway endpoint enhances the professional appearance of your application and provides flexibility in managing your API endpoints. By following the steps outlined in this guide, you can create a secure and reliable custom domain configuration using CloudFront as a reverse proxy.
For more information about Gateway features and capabilities, see [Amazon Bedrock AgentCore Gateway: Securely connect tools and other resources to your Gateway](gateway.md).
# Using interceptors with Gateway
Configuring interceptors on your gateway allows you to run custom code during each invocation of your gateway. This section provides guidance on implementing and configuring interceptors for your Gateway.
**Topics**
+ [
## Overview
](#gateway-interceptors-overview)
+ [
## Security best practices
](#gateway-interceptors-security)
+ [
# Permissions for interceptors
](gateway-interceptors-permissions.md)
+ [
# Types of interceptors
](gateway-interceptors-types.md)
+ [
# Configuration
](gateway-interceptors-configuration.md)
+ [
# Examples
](gateway-interceptors-examples.md)
## Overview
Configuring interceptors on your gateway allows you to run custom code during each invocation of your gateway. This is useful for the following use cases:
+ Implementing fine-grained access control over tools or MCP operations
+ Transforming the target request and gateway response
+ Implementing custom authorization logic
There are two types of interceptors that can be configured on your gateway:
+ **REQUEST interceptors** – Execute before the gateway makes a call to the target. These are useful for request validation, transformation, or custom authorization.
+ **RESPONSE interceptors** – Execute after the target responds but before the gateway sends the response back to the caller. These are useful for response transformation, filtering, or adding custom headers.
A gateway can have at most one REQUEST interceptor and at most one RESPONSE interceptor configured. You can configure both types on the same gateway, but you cannot have multiple interceptors of the same type.
Currently, interceptors can only be configured with Lambda functions.
## Security best practices
When implementing interceptors, it’s important to follow security best practices to protect sensitive information and maintain proper access control.
1. By default, request headers will not be passed to an interceptor unless the `passRequestHeaders` field is set to true. Be careful when using this field as request headers can contain sensitive information such as authentication tokens and credentials. Be sure to verify your interceptor is not logging this sensitive information.
1. Be sure to restrict your gateway execution role to have permissions only to invoke the specific lambda functions you are using as interceptors and not to give wild card lambda permissions to your execution role.
1. Implement idempotent Lambda functions for your interceptors. The gateway may retry requests to interceptor Lambda functions in case of failures or timeouts. Ensure your interceptor logic can handle duplicate invocations safely by implementing idempotency keys, tracking processed requests, or designing stateless operations that produce consistent results when executed multiple times with the same input.
# Permissions for interceptors
When configuring interceptors, your gateway service role must have the lambda:InvokeFunction IAM permissions to invoke the Lambda functions that serve as interceptors. The service role needs specific permissions to execute interceptor functions during request and response processing.
For detailed information about configuring the required permissions for your gateway service role, including permissions to Lambda, see [Gateway service role permissions](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-prerequisites-permissions.html#gateway-service-role-permissions).
# Types of interceptors
There are two types of interceptors that can be configured on your gateway:
## Request interceptors
The REQUEST interceptor gets invoked before gateway makes a call to the target configured on the gateway. You can use the REQUEST interceptor to perform any custom validations or authorizations.
### Request interceptor input payload example
The following example shows the input payload structure that a request interceptor Lambda function receives:
```
{
"interceptorInputVersion": "1.0",
"mcp": {
"rawGatewayRequest": {
"body": ""
},
"gatewayRequest" : {
"path": "/mcp",
"httpMethod": "POST",
"headers": {
"Accept": "application/json",
"Authorization": "",
"SomeHeader": "headerValue1",
"Mcp-Session-Id": "",
"User-Agent": ""
},
"body": {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
}
}
}
```
**Note**
The `headers` field is only included if `passRequestHeaders` is set to `true` in the interceptor configuration. The `gatewayResponse` field is not present for request interceptors since the response has not been generated yet.
### Request interceptor output payload example
The following example shows the output payload structure that a request interceptor Lambda function should return:
```
{
"interceptorOutputVersion": "1.0",
"mcp": {
"transformedGatewayRequest" : {
"body": {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
},
"transformedGatewayResponse" : {
"statusCode": 200,
"body": {
"jsonrpc": "2.0",
"id": 1,
"result": {
"": ""
}
}
}
}
}
```
**Important**
Important notes about request interceptor output: \$1 The `interceptorOutputVersion` must be set to `"1.0"` . \$1 If the interceptor output contains a `transformedGatewayResponse` , the gateway will respond with that content immediately, even if `transformedGatewayRequest` is also provided. \$1 If both REQUEST and RESPONSE interceptors are configured and the REQUEST interceptor output contains a `transformedGatewayResponse` , the RESPONSE interceptor will still be invoked.
## Response interceptors
The RESPONSE interceptor gets invoked before the gateway responds to the caller. You can use the RESPONSE interceptor to perform any custom redactions or additions to the response back to the caller.
### Response interceptor input payload example
The following example shows the input payload structure that a response interceptor Lambda function receives:
```
{
"interceptorInputVersion": "1.0",
"mcp": {
"rawGatewayRequest": {
"body": ""
},
"gatewayRequest" : {
"path": "/mcp",
"httpMethod": "POST",
"headers": {
"Accept": "application/json",
"Authorization": "",
"SomeHeader": "headerValue1",
"Mcp-Session-Id": "",
"User-Agent": ""
},
"body": {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
},
"gatewayResponse" : {
"statusCode": 200,
"headers": {
"SomeHeader": "headerValue1",
"Mcp-Session-Id": ""
},
"body": {
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": []
}
}
}
}
}
```
**Note**
The `headers` field in `gatewayRequest` is only included if `passRequestHeaders` is set to `true` in the interceptor configuration. Response interceptors receive both the original request and the gateway’s response, allowing you to modify the response before it’s returned to the caller.
### Response interceptor output payload example
The following example shows the output payload structure that a response interceptor Lambda function should return:
```
{
"interceptorOutputVersion": "1.0",
"mcp": {
"transformedGatewayRequest" : {
"body": {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
},
"transformedGatewayResponse" : {
"statusCode": 200,
"body": {
"jsonrpc": "2.0",
"id": 1,
"result": {
"": ""
}
}
}
}
}
```
**Important**
Important notes about response interceptor output: \$1 The `interceptorOutputVersion` must be set to `"1.0"` . \$1 If the interceptor output contains a `transformedGatewayResponse` , the gateway will respond with that content immediately, even if `transformedGatewayRequest` is also provided. \$1 If both REQUEST and RESPONSE interceptors are configured and the REQUEST interceptor output contains a `transformedGatewayResponse` , the RESPONSE interceptor will still be invoked.
# Configuration
Interceptors can be configured with an input parameter called `passRequestHeaders`
## Interceptor input configuration
When configuring interceptors, you can specify whether request headers should be passed to the interceptor function using the `passRequestHeaders` field:
**passRequestHeaders**
A boolean value that determines whether request headers are included in the interceptor input payload. When set to `true` , all request headers will be passed to your interceptor Lambda function. When set to `false` (default), headers are not included.
Use caution when setting this to `true` as request headers may contain sensitive information such as authentication tokens and credentials.
## Configuring interceptors during gateway creation
The following examples show how to create a gateway with interceptors that have `passRequestHeaders` set to `true` :
**Example**
1. With the AgentCore CLI, first create and deploy the gateway, then configure interceptors using the AWS CLI or AWS Python SDK (Boto3).
Create the gateway:
```
agentcore add gateway \
--name my-gateway-with-headers \
--authorizer-type CUSTOM_JWT \
--discovery-url "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration" \
--allowed-audience "api.example.com"
agentcore deploy
```
After deployment, configure interceptors on the gateway using the AWS CLI `update-gateway` command or the AWS Python SDK (Boto3) as shown in the other tabs.
1. Use the following AWS CLI command to create a gateway with interceptors configured to pass request headers:
```
aws bedrock-agentcore-control create-gateway \
--name my-gateway-with-headers \
--role-arn arn:aws:iam::123456789012:role/my-gateway-service-role \
--protocol-type MCP \
--authorizer-type CUSTOM_JWT \
--authorizer-configuration '{
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
}' \
--interceptor-configurations '[{
"interceptor": {
"lambda": {
"arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
}
},
"interceptionPoints": ["REQUEST", "RESPONSE"],
"inputConfiguration": {
"passRequestHeaders": true
}
}]'
```
1. Use the following Python code with the AWS Python SDK (Boto3) to create a gateway with interceptors configured to pass request headers:
```
import boto3
# Initialize the AgentCore client
client = boto3.client('bedrock-agentcore-control')
# Create a gateway
gateway = client.create_gateway(
name="my-gateway-with-headers",
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/some-user-pool/.well-known/openid-configuration",
"allowedClients": ["clientId"]
}
},
interceptorConfigurations=[{
"interceptor": {
"lambda": {
"arn":"arn:aws:lambda:us-west-2:123456789012:function:my-interceptor-lambda"
}
},
"interceptionPoints": ["REQUEST", "RESPONSE"],
"inputConfiguration": {
"passRequestHeaders": True
}
}]
)
print(f"MCP Endpoint: {gateway['gatewayUrl']}")
```
## Updating interceptor configurations
You can update existing gateway interceptor configurations to modify the `passRequestHeaders` setting or other parameters using the update gateway API operations.
# Examples
The following example shows a Python Lambda function that can handle both REQUEST and RESPONSE interceptor types. The REQUEST interceptor logs the MCP method and passes the request through unchanged, while the RESPONSE interceptor passes the response through unchanged.
## Pass-through interceptor
This example demonstrates a simple interceptor that logs the MCP method for REQUEST interceptors and passes all requests and responses through unchanged:
```
import json
import logging
# Configure logging
logger = logging.getLogger()
logger.setLevel(logging.INFO)
def lambda_handler(event, context):
"""
Lambda function that handles both REQUEST and RESPONSE interceptor types.
For REQUEST interceptors: logs the MCP method and passes request through unchanged
For RESPONSE interceptors: passes response through unchanged
"""
# Extract the MCP data from the event
mcp_data = event.get('mcp', {})
# Check if this is a REQUEST or RESPONSE interceptor based on presence of gatewayResponse
if 'gatewayResponse' in mcp_data and mcp_data['gatewayResponse'] != None:
# This is a RESPONSE interceptor
logger.info("Processing RESPONSE interceptor - passing through unchanged")
# Pass through the original request and response unchanged
response = {
"interceptorOutputVersion": "1.0",
"mcp": {
"transformedGatewayResponse": {
"body": mcp_data.get('gatewayResponse', {}).get('body', {}),
"statusCode": mcp_data.get('gatewayResponse', {}).get('statusCode', 200)
}
}
}
else:
# This is a REQUEST interceptor
gateway_request = mcp_data.get('gatewayRequest', {})
request_body = gateway_request.get('body', {})
mcp_method = request_body.get('method', 'unknown')
# Log the MCP method
logger.info(f"Processing REQUEST interceptor - MCP method: {mcp_method}")
# Pass through the original request unchanged
response = {
"interceptorOutputVersion": "1.0",
"mcp": {
"transformedGatewayRequest": {
"body": request_body,
}
}
}
return response
```
This Lambda function can be configured as both a REQUEST and RESPONSE interceptor. When configured as a REQUEST interceptor, it will log the MCP method from the incoming request. When configured as a RESPONSE interceptor, it will simply pass the response through unchanged. Both interceptor types return the original data without modification, making this a "pass-through" interceptor.
# Header propagation with Gateway
## What is header and query parameter propagation
Header propagation refers to the systematic forwarding of selective HTTP headers from incoming requests through your gateway to configured targets, and selective forwarding of response headers back to the client. Similar to header propagation, query parameter propagation enables forwarding of URL query parameters from incoming requests to configured targets. This feature can be used for use cases where you need to exchange context, authentication, tracing, and other critical information between client and targets. The pre-allowlisted headers provided in the invoke tool call to gateway or sent from custom interceptor lambda, will be forwarded to the specific targets.
This feature operates as a shared responsibility model:
+ AWS responsibility is to securely pass the headers and query parameters which you have allowlisted for your targets.
+ Your responsibility is to exercise caution and **only allowlist those headers for propagation which are essential to the targets** , ensuring they meet your security and functional requirements.
### Header restrictions
To maintain security and prevent exposure of sensitive information, the following headers are restricted and cannot be configured for propagation:
| |
| --- |
| Authorization\$1 |
| Proxy-Authorization |
| WWW-Authenticate |
| Accept |
| Accept-Charset |
| Accept-Encoding |
| Accept-Language |
| Content-Type |
| Content-Length |
| Content-Encoding |
| Content-Language |
| Content-Location |
| Content-Range |
| Cache-Control |
| ETag |
| Expires |
| If-Match |
| If-Modified-Since |
| If-None-Match |
| If-Range |
| If-Unmodified-Since |
| Last-Modified |
| Pragma |
| Vary |
| Connection |
| Keep-Alive |
| Proxy-Connection |
| Upgrade |
| Host |
| User-Agent |
| Referer |
| From |
| Range |
| Accept-Ranges |
| Transfer-Encoding |
| TE |
| Trailer |
| Server |
| Date |
| Location |
| Retry-After |
| Set-Cookie |
| Cookie |
| Content-Security-Policy |
| Content-Security-Policy-Report-Only |
| Strict-Transport-Security |
| X-Content-Type-Options |
| X-Frame-Options |
| X-XSS-Protection |
| Referrer-Policy |
| Permissions-Policy |
| Cross-Origin-Embedder-Policy |
| Cross-Origin-Opener-Policy |
| Cross-Origin-Resource-Policy |
| Access-Control-Allow-Origin |
| Access-Control-Allow-Methods |
| Access-Control-Allow-Headers |
| Access-Control-Allow-Credentials |
| Access-Control-Expose-Headers |
| Access-Control-Max-Age |
| Access-Control-Request-Method |
| Access-Control-Request-Headers |
| Origin |
| Accept-CH |
| Accept-CH-Lifetime |
| DPR |
| Width |
| Viewport-Width |
| Downlink |
| ECT |
| RTT |
| Save-Data |
| Clear-Site-Data |
| Feature-Policy |
| Expect-CT |
| Public-Key-Pins |
| Public-Key-Pins-Report-Only |
| X-Forwarded-For |
| X-Forwarded-Host |
| X-Forwarded-Proto |
| X-Real-IP |
| X-Requested-With |
| X-CSRF-Token |
| CF-Ray |
| CF-Connecting-IP |
| X-Amz-Cf-Id |
| X-Cache |
| X-Served-By |
| :method |
| :path |
| :scheme |
| :authority |
| :status |
| Link |
| Sec-WebSocket-Key |
| Sec-WebSocket-Accept |
| Sec-WebSocket-Version |
| Sec-WebSocket-Protocol |
| Sec-WebSocket-Extensions |
+ Authorization header cannot be allowlisted during target creation. However it will be forwarded to the target when provided by an interceptor lambda. See [Header propagation from interceptor lambda](#gateway-headers-interceptor-propagation) for details.
**Important**
In addition to restricted headers mentioned above, headers provided in API keys and REST API schema cannot be configured for header propagation.
Additional validation rules apply to allowed headers:
+ Maximum of 10 request headers, 10 response headers, and 10 query parameters per target to prevent abuse and maintain performance
+ Header names must contain only alphanumeric characters, hyphens, and underscores (regex: `^[a-zA-Z0-9_-]+$` )
+ Header values are limited to 4KB maximum to prevent memory exhaustion
+ Header values must contain only printable ASCII characters
+ Headers starting with `X-Amzn-` are prohibited (except for X-Amzn-Bedrock-AgentCore-Runtime-Custom-\$1 headers)
## Configuring header and query parameter propagation
You can configure header and query parameters at the target level when creating or updating gateway targets. Headers and query parameters are specified per target, ensuring that each target receives only the headers it needs.
### Target-level configuration
Configure header propagation by adding `allowedRequestHeaders` , `allowedResponseHeaders` , and `allowedQueryParameters` fields to your target’s `metadataConfiguration` :
```
{
"name": "my-target",
"description": "my target description",
"credentialProviderConfigurations": [{
"credentialProviderType": "OAUTH",
"credentialProvider": {
"oauthCredentialProvider": {
"providerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:credential-provider/example",
"scopes": []
}
}
}],
"targetConfiguration": {
"mcp": {
"mcpServer": {
"endpoint": "https://example.com/mcp"
}
}
},
"metadataConfiguration": {
"allowedRequestHeaders": [
"request-header"
],
"allowedResponseHeaders": [
"response-header"
],
"allowedQueryParameters": [
"query-param"
]
}
}
```
Using the Python SDK:
```
import boto3
# Initialize the client
client = boto3.client('bedrock-agentcore', region_name='us-west-2')
# Create target with header propagation
response = client.create_gateway_target(
gatewayId='gateway-123',
name='mcp-target-with-headers',
description='MCP target with header propagation',
targetConfiguration={
'mcp': {
'mcpServer': {
'endpoint': 'https://example.com/mcp'
}
}
},
metadataConfiguration={
'allowedRequestHeaders': ['x-correlation-id', 'x-tenant-id'],
'allowedResponseHeaders': ['x-rate-limit-remaining'],
'allowedQueryParameters': ['version']
}
)
```
## Header propagation from interceptor lambda
When using custom interceptor lambdas with your gateway, you can dynamically control header propagation by including headers in your interceptor lambda response.
### How interceptor header propagation works
Interceptor lambdas can influence header propagation in the following ways:
+ **Authorization header override:** The `Authorization` header from the interceptor lambda response is automatically propagated to the target. While the `Authorization` header cannot be configured in the target’s allowlist, it will be forwarded to the target when provided by an interceptor lambda.
For example, if you have added a credential provider to the target which provides an authorization token like `Authorization: Bearer client-token` and the interceptor lambda provides `Authorization: Bearer refreshed-token` , the value `Bearer refreshed-token` from the interceptor lambda will be forwarded to the target.
+ **Custom header injection:** Additional headers from the interceptor lambda response are merged with the configured target header allowlist.
+ **Header precedence:** Interceptor lambda-provided headers take precedence over client-provided headers in case of conflicts.
For example, if you allowlist header `x-tenant-id` in the target configuration, and the incoming request provides `x-tenant-id: tenant-123` while the interceptor lambda provides `x-tenant-id: tenant-456` , the value `tenant-456` from the interceptor lambda will be forwarded to the target.
+ **Security validation:** All lambda-provided headers are subject to the same validation rules as configured headers. Except for Authorization header, all other headers must be allowlisted during target creation for them to be forwarded to the targets.
### Implementing header propagation in interceptors
Configure your interceptor lambda to return headers that should be propagated to the target:
```
import json
import boto3
def lambda_handler(event, context):
# Extract request context
request_context = event.get('requestContext', {})
user_identity = request_context.get('identity', {})
# Fetch credentials from secure store (example)
credentials_client = boto3.client('secretsmanager')
secret = credentials_client.get_secret_value(
SecretId=f"mcp-credentials/{user_identity.get('userId')}"
)
credentials = json.loads(secret['SecretString'])
# Return response with headers to propagate
return {
"interceptorOutputVersion": "1.0",
"mcp": {
"transformedGatewayRequest": {
"headers": {
# Authorization header will be propagated automatically
"Authorization": f"Bearer {credentials['access_token']}",
# Custom headers (must be in target allowlist)
"x-tenant-id": user_identity.get('tenantId'),
"x-correlation-id": request_context.get('requestId')
},
"body": event['mcp']['gatewayRequest']['body']
}
}
}
```
**Common use cases for interceptor header propagation include:**
**Credential fetching**
Retrieve short-lived tokens from secure vaults and inject them as Authorization headers, preventing credential exposure in client applications.
**Context injection**
Add tenant identifiers, organization context, or user attributes derived from authenticated user claims rather than trusting client-provided values.
**Header transformation**
Transform or sanitize headers based on business logic, compliance requirements, or security policies before they reach the target.
**Dynamic routing**
Inject routing hints, feature flags, or A/B testing headers based on real-time analysis of user attributes or system state.
### Security considerations
When implementing header propagation with interceptor lambdas, follow these security best practices:
+ **Validate header sources:** Only propagate headers that are explicitly configured in your target allowlist or returned by trusted interceptor lambdas
+ **Sanitize sensitive data:** Remove or mask PII and sensitive information before forwarding headers to external MCP servers
+ **Use least privilege:** Configure interceptor lambda IAM roles with minimal permissions required for credential fetching and context retrieval
+ **Implement audit logging:** Log header transformations and credential fetching activities for security monitoring and compliance
+ **Validate header content:** Ensure that lambda-generated headers meet the same validation rules as configured headers
## Best practices
Follow these best practices when implementing header propagation:
**Use target-specific configuration**
Configure headers per target rather than globally. Different targets may require different headers, and target-specific configuration provides better security isolation.
**Minimize header count**
Only propagate headers that are actually needed by the target. Excessive headers increase request size and processing overhead.
**Use semantic header names**
Choose descriptive header names that clearly indicate their purpose, such as `x-correlation-id` for tracing or `x-tenant-id` for multi-tenancy.
**Implement proper error handling**
Handle cases where required headers are missing or invalid. Consider whether to fail the request or provide default values.
**Monitor header usage**
Use gateway observability features to monitor which headers are being propagated and identify any issues with header validation or processing.
**Test header propagation**
Verify that headers are correctly propagated to your targets during development and testing. Use tools like request logging or debugging endpoints to validate header flow.
# Performance optimization
To optimize the performance of your Gateway implementations, consider the following best practices:
**Minimize tool latency**
The overall latency of your gateway is largely determined by the latency of the underlying tools. To minimize latency:
+ Use Lambda functions in the same region as your gateway
+ Optimize your Lambda functions for fast cold starts
+ Use provisioned concurrency for Lambda functions that require low latency
+ Ensure that REST APIs have low latency and high availability
**Use efficient tool schemas**
Well-designed tool schemas can improve the performance of your gateway:
+ Keep schemas as simple as possible
+ Use appropriate data types for parameters
+ Include clear descriptions for parameters to help agents use the tools correctly
+ Use required fields to ensure that agents provide necessary parameters
**Enable semantic search**
Semantic search helps agents find the right tools for their tasks, improving the overall performance of your agent-gateway interactions. Enable semantic search when creating your gateway:
```
import boto3
# Initialize the AgentCore control client
client = boto3.client('bedrock-agentcore-control', region_name="us-west-2")
# Create a gateway with semantic search enabled
gateway = client.create_gateway(
name="semantic-search-gateway",
description="A gateway with semantic search enabled",
protocolConfiguration={
"mcp": {
"searchType": "SEMANTIC"
}
}
)
```
**Monitor and optimize**
Use the observability features described in the previous section to monitor the performance of your gateway and identify opportunities for optimization:
+ Set up CloudWatch alarms for key metrics
+ Analyze logs to identify patterns and issues
+ Regularly review performance metrics and make adjustments as needed