Creating your Gateway - Amazon Bedrock AgentCore
Create a gateway with semantic search

Amazon Bedrock AgentCore is in preview release and is subject to change.

Creating your Gateway

Once you have set up your identity provider, you can create your Gateway with the AWS Management Console or with the CreateGateway API operation.

When you create a gateway, you can include the following capabilities:

  • Semantic search – Allows using semantic search to deliver contextually relevant tools. For more information, see Create a gateway with semantic search.

  • Debug mode – Allows the return of specific error messages related to the gateway target configuration to help you with debugging. For more information, see Debugging your gateway.

For more details on a specific method, select a tab:

AgentCore SDK

You can create a gateway with the AgentCore SDK:


from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient

# Initialize the Gateway client
client = GatewayClient(region_name="us-west-2")

# EZ Auth - automatically sets up Cognito OAuth
cognito_result = client.create_oauth_authorizer_with_cognito("my-gateway")

# create the gateway.
gateway = client.create_mcp_gateway(
    name=None, # the name of the Gateway - if you don't set one, one will be generated.
    role_arn=None, # the role arn that the Gateway will use - if you don't set one, one will be created.
    authorizer_config=authorization, # Variable from inbound authorization setup steps. Contains the OAuth authorizer details for authorizing callers to your Gateway (MCP only supports OAuth).
    enable_semantic_search=True, # enable semantic search.
    exception_level="DEBUG" # enable debugging
)

print(f"MCP Endpoint: {gateway.get_mcp_url()}")
print(f"OAuth Credentials:")
print(f"  Client ID: {cognito_result['client_info']['client_id']}")
print(f"  Scope: {cognito_result['client_info']['scope']}")
CLI

The AgentCore CLI provides a simple way to create and manage gateways:


# Create a Gateway with Lambda target
agentcore create_mcp_gateway \
  --name my-gateway \
  --target arn:aws:lambda:us-west-2:123456789012:function:MyFunction \
  --execution-role BedrockAgentCoreGatewayRole

The CLI automatically:

  • Detects target type from ARN patterns or file extensions

  • Sets up Cognito OAuth (EZ Auth)

  • Detects your AWS region and account

  • Builds full role ARN from role name

Console
To create your Gateway endpoint

  1. Open the AgentCore console at https://console.aws.amazon.com/bedrock-agentcore/home#.

  2. Choose Gateways.

  3. Choose Create gateway.

  4. In the Gateway details section:

    1. Enter a Gateway name

    2. Expand the Additional configurations section and:

      1. Enter an optional Description for your gateway.

      2. (Optional) For Instructions, enter any special instructions or context that should be passed to tools when they are invoked.

      3. (Optional) Optionally enable Semantic search to enable the built-in tool that can be used to search the tools on the gateway.

  5. In the Inbound Identity section, configure authentication for users accessing your gateway:

    1. For Discovery URL, enter the OpenID Connect discovery URL for your identity provider (for example, https://auth.example.com/.well-known/openid-configuration).

    2. For Allowed audiences, enter the audience values that your gateway will accept. Add multiple audiences by choosing Add audience.

  6. In the Permissions section:

    1. For Service role, choose an existing IAM role or create a new one that allows Amazon Bedrock AgentCore to access your tools on your behalf.

    2. (Optional) For KMS key, choose a customer managed key for encrypting your gateway data, or leave blank to use the default Amazon Bedrock AgentCore managed key.

  7. In the Target configuration section:

    1. Enter a Target name.

    2. (Optional) Provide an optional Target description.

    3. For Target type, choose either:

      • Lambda ARN - To connect to an Lambda function that implements your tools

      • REST API - To connect to a REST API service

    4. Configure the target based on your selection:

      • For Lambda function targets:

        • For Lambda ARN, enter the ARN of your Lambda function.

        • For Tool schema, choose to either provide the schema inline or reference an Amazon S3 location containing your tool schema.

      • For REST API targets:

        • For OpenAPI schema, choose to either provide the schema inline or reference an Amazon S3 location containing your OpenAPI specification.

    5. (Optional) In the Outbound authentication section, configure authentication for accessing external services:

      • For Authentication type, choose OAuth client or API key.

      • Select the appropriate authentication resource from your account.

  8. To add more targets, choose Add another target and repeat the target configuration steps.

  9. Choose Create gateway.

After creating your gateway, you can view its details, including the endpoint URL and associated targets, in the AgentCore console. The gateway endpoint URL follows the format: https://{gatewayId}.gateway.{region}.amazonaws.com/mcp.

Boto3

The following Python code shows how to create a gateway with boto3 (AWS SDK for Python)


import boto3
# create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')
# create a gateway
gateway = agentcore_client.create_gateway(
    name="<target-name e.g. ProductSearch>",
    roleArn="<existing role ARN e.g. arn:aws:iam::123456789012:role/MyRole>",
    protocolType="MCP",
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration= {
        "customJWTAuthorizer": {  
            "discoveryUrl": "<existing discovery URL e.g. https://cognito-idp.us-west-2.amazonaws.com/some-user-pool/.well-known/openid-configuration>",
            "allowedClients": ["<clientId>"]
        }
    }
)
API

Use CreateGateway to create a gateway. The operation requires a gateway name and protocol type, while accepting optional parameters like role ARN for IAM permissions, authorizer configuration for JWT-based authentication, and custom transform configuration for request/response processing.

Example request

The following example creates a Gateway with MCP protocol and JWT authorization:


POST /gateways/ HTTP/1.1
Content-Type: application/json

{
    "name": "my-ai-gateway",
    "description": "Gateway for AI model interactions",
    "clientToken": "12345678-1234-1234-1234-123456789012",
    "roleArn": "arn:aws:iam::123456789012:role/AgentCoreGatewayRole",
    "protocolType": "MCP",
    "protocolConfiguration": {
        "mcp": {
            "version": "1.0",
            "searchType": "SEMANTIC"
        }
    },
    "authorizerConfiguration": {
        "customJWTAuthorizer": {
            "discoveryUrl": "https://auth.example.com/.well-known/openid-configuration",
            "allowedAudience": ["api.example.com"],
            "allowedClients": ["client-app-123"]
        }
    },
    "encryptionKeyArn": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
}

After creating the gateway, you can call CreateGatewayTarget to add targets to the gateway. The operation accepts a gateway identifier in the URI path along with target specifications including the target name and configuration details.

Example request for OpenAPI target

This example creates a target using an OpenAPI schema for a product catalog service:


PUT /gateways/abc123def4/targets/ HTTP/1.1
Content-Type: application/json

{
  "name": "ProductCatalogAPI",
  "description": "Routes to product catalog and inventory service",
  "targetConfiguration": {
    "mcp": {
      "openApiSchema": {
        "s3Uri": "s3://retail-schemas-bucket/catalog/product-api.json"
      }
    }
  }
}

Semantic search enables intelligent tool discovery so that we are not limited by typical list tools limits (typically 100 or so). Our semantic search capability delivers contextually relevant tool subsets, significantly improving tool selection accuracy through focused, relevant results, inference performance with reduced token processing and overall orchestration efficiency and response times.

To enable it, add "searchType": "SEMANTIC" to the CreateGateway request in the MCP object within the protocolConfiguration field:

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

You can only enable it during create, you cannot update a gateway later to be able to support search.

For an identity to create a gateway with semantic search, ensure that it has permissions to use the bedrock-agentcore:SynchronizeGatewayTargets" IAM action.