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

Add MCP server targets to your gateway

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. For more information about the APIs, see CreateGateway, CreateGatewayTarget, UpdateGatewayTarget, and SynchronizeGatewayTargets in the Bedrock AgentCore API Guide.

MCP servers host tools which agents can discover and invoke. In Bedrock AgentCore, you use a gateway to associate targets to tools to connect 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 Get started with Amazon Bedrock AgentCore MCP server.

Key capabilities and limitations

Tool discovery is managed through the synchronization operation provided by the SynchronizeGatewayTargets API as follows.

Implicit Synchronization

Implicity 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 discovery process on-demand operation, allowing users to control when Gateway updates its view of available tools.

Synchronization is a critical mechanisms 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 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/{gatewayIdentifier}/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.

Prerequisites

Before adding an MCP server target, ensure you have:

Configuring permissions

For MCP servers targets, your Gateway's execution role needs permissions added to the role which you use to create the Gateway as 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:GetResourceOauth2Token",
                "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/*"
        }
    ]
}

Adding an MCP server target

You can add an MCP server target to your Gateway using one of the following methods:

CLI

The AgentCore CLI provides a simple way to add MCP server targets:

# Create MCP server as target
{gatewayUrl}/gateways/{gatewayIdentifier}/targets
{
    "name": "myMCPTarget",
    "description": "description of my MCP target",
    "credentialProviderConfigurations": [{
        "credentialProviderType": "OAUTH",
        "credentialProvider": {
            "oauthCredentialProvider": {
                "providerArn": "arn:aws:bedrock-agentcore:{region}:{account}:token-vault/default/oauth2credentialprovider/resource-provider-oauth-test",
                "scopes": []
            }
        }
    }],
    "targetConfiguration": {
        "mcp": {
            "mcpServer": {
                "endpoint": "myMCPServerURL"
            }
        }
    }
}

# SynchronizeGatewayTargets
{gatewayUrl}/gateways/{gatewayIdentifier}/synchronizeTargets
{
    "targetIdList": [
        "<targetId>"
    ]
}

Console

To add an MCP servertarget to an existing gateway

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

2. Select the Gateway to which you want to add a target.

3. Choose the Targets tab.

4. Choose Add target.

5. Enter a Target name.

6. (Optional) Provide an optional Target description.

7. For Target type, choose MCP server.

   1. The MCP server must have tool capabilities.

   2. Supported MCP protocol versions are - 2025-06-18 and 2025-03-26.

8. For MCP endpoint, add the URL/endpoint of the server. The URL should be encoded. Gateway will use the same URL to invoke the server.

9. For Outbound identity type, choose the type of authorization. Otherwise, choose No Authorization.

10. Choose Create gateway.