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, prompts, and resources that agents can discover and use. In Bedrock AgentCore, you use a gateway to associate targets with these capabilities and connect them to your agent runtime. You connect with external MCP servers through the SynchronizeGatewayTargets API that performs protocol handshakes and indexes available capabilities. For more information about installing and using MCP servers, see Amazon Bedrock AgentCore MCP Server: Vibe coding with your coding assistant.

Key considerations and limitations

Listing Mode

ListingMode can be set as either DYNAMIC or DEFAULT for MCP server targets.

Implicit Synchronization

For targets in DEFAULT mode, CreateGatewayTarget and UpdateGatewayTarget operations automatically trigger capability discovery and indexing. When either operation is called, Gateway fetches available tools using MCP’s tools/list capability, prompts using prompts/list, resources using resources/list and resources/templates/list, and adds the returned capabilities to the unified catalog.

Explicit Synchronization

Capability catalogs for Targets in DEFAULT mode, can be manually refreshed by calling the SynchronizeGatewayTargets API. When called, it updates the Gateway’s list of available capabilities. You should call the API any time an MCP server’s tool, prompt, resource definitions change.

Synchronization is a critical mechanism for maintaining accurate capability catalogs when integrating MCP servers. Implicit synchronization occurs automatically during target creation and updates, where Gateway immediately discovers and indexes tools, prompts, and resources from the MCP server to ensure capabilities are available for semantic search and unified listing. Explicit synchronization is performed on-demand through the SynchronizeGatewayTargets API, allowing discovery of the MCP capability catalog when MCP servers independently modify their capabilities.

When to call SynchronizeGatewayTargets

Whenever an MCP server target has its Listing Mode set to DEFAULT, use the SynchronizeGatewayTargets API after tools, prompts, or resources are added, removed, or modified. Since Gateway pre-computes vector embeddings for semantic search and maintains normalized capability catalogs, synchronization is necessary to ensure your users can discover and invoke the latest available tools, prompts, and resources.

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 capability sets.

Authorization strategy

The following types of the authorization strategy are supported.

Configuration considerations for MCP server targets

The following must be configured.

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.

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.

URL Session Binding

OAuth 2.0 authorization URL session binding 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 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.

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