Amazon API Gateway REST API stages as targets

An API Gateway REST API target connects your gateway to a stage 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 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 in the Amazon API Gateway documentation.

Key considerations and limitations

When using an API Gateway REST API stage as a target, keep in mind the following requirements and limitations:

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:

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.

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"]
}

Explicit path and list of methods

Tool Configuration:

{
  "filterPath": "/pets/{petId}",
  "methods": ["GET", "POST"]
}   

Explicit path and list of explicit method (most specific)

Tool Configuration:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["POST"]
    },
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"] 
    }
  ]
}

Mix and match an explicit and wildcard path:

Tool Configuration:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    },
    {
        "filterPath": "/*",
        "methods": ["GET"]
    }
  ]
}

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"
    }
  ]
}

API Gateway export

To set up your API Gateway target, AgentCore Gateway calls the GetExport 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:

Updating operationId on your REST API

You can update your REST API to ensure that the OpenAPI definition returned by GetExport 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, updating the operations that are missing operationId, and reimporting your API.

Set the operationId by updating your REST API's method

You can configure your API Gateway Method to add an operationName using the UpdateMethod command. When your API is exported, the operationName turns into the operationId.

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:

To learn more, see Set up outbound authorization for your gateway.

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) to sign their requests with AWS credentials.

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:

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.