本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# MCP 服务器目标
<a name="gateway-target-MCPservers"></a>

MCP 服务器为你在 Bedro AgentCore ck 中与模型和代理进行交互提供本地工具、数据访问或自定义函数。在 Bedrock 中 AgentCore，您可以在创建网关时将预配置的 MCP 服务器定义为目标。

MCP 服务器托管代理可以发现和使用的工具、提示和资源。在 Bedrock 中 AgentCore，您可以使用网关将目标与这些功能关联并将它们连接到您的代理运行时。您可以通过执行协议握手和索引可用功能的 `SynchronizeGatewayTargets` API 与外部 MCP 服务器连接。有关安装和使用 MCP 服务器的更多信息，请参阅 [ Amazon Bedro AgentCore ck MCP 服务器：使用编程助手进行氛围编码。](mcp-getting-started.md)

**Topics**
+ [主要注意事项和局限性](#gateway-target-MCPservers-considerations)
+ [使用授权码流程连接到 OAuth-protected MCP 服务器](#gateway-target-MCPservers-auth-code-grant-flow)
+ [配置权限](#gateway-target-MCPservers-permissions)

## 主要注意事项和局限性
<a name="gateway-target-MCPservers-considerations"></a>

 **上市模式 ** 

ListingMode 可以将 MCP 服务器目标设置为动态或默认。
+ 在动态模式下，当用户调用 MCP 操作时，客户端会发现 MCP 服务器的功能。Gateway 通过将请求转发到 MCP 服务器来检索服务器功能。当前，动态模式无法与语义搜索或出站三足式 OAuth (3LO) 互操作。
+ 除非更改，否则列表模式将设置为默认。在默认模式下，客户端通过 SynchronizeGatewayTargets API 提供的同步操作发现 MCP 服务器的功能。

 **隐式同步 ** 

对于处于 DEFAULT 模式的目标， CreateGatewayTarget UpdateGatewayTarget 操作会自动触发能力发现和索引。调用任一操作时，Gateway 会使用 MCP 的`tools/list`功能获取可用工具，提示使用`prompts/list`，使用`resources/list`和资源`resources/templates/list`，并将返回的功能添加到统一目录中。

 **显式同步 ** 

默认模式下目标的能力目录可以通过调用 API 手动刷新。`SynchronizeGatewayTargets`调用时，它会更新网关的可用功能列表。每当 MCP 服务器的工具、提示、资源定义发生变化时，您都应该调用 API。

在集成 MCP 服务器时，同步是保持精确功能目录的关键机制。隐式同步在目标创建和更新期间自动发生，Gateway 会立即发现来自 MCP 服务器的工具、提示和资源并将其编入索引，以确保具有语义搜索和统一列表功能。显式同步通过 `SynchronizeGatewayTargets` API 按需执行，允许在 MCP 服务器独立修改其功能时发现 MCP 功能目录。

 **什么时候打电话 SynchronizeGatewayTargets ** 

每当 MCP 服务器目标的列表模式设置为 DEFAULT 时，请在添加、删除或修改工具、提示或资源后使用 `SynchronizeGatewayTargets` API。由于 Gateway 会预先计算用于语义搜索的矢量嵌入并维护标准化功能目录，因此必须进行同步以确保您的用户能够发现和调用最新的可用工具、提示和资源。

 **如何调用 API ** 

向 /gateways/ {GatewayS/ {GatewayIdentier} /发出 PUT 请求，并与请求正文中的目标 ID 同步。API 立即返回 202 响应并异步处理同步。监控目标状态 GetGatewayTarget 以跟踪同步进度，因为大型功能集的操作可能需要几分钟。

 **授权策略 ** 

支持以下类型的授权策略。
+ 无授权 — 网关在没有预先配置的授权的情况下调用 MCP 服务器。不推荐使用这种方法。
+ OAuth — 网关支持两级 OAuth（`CLIENT_CREDENTIALS`授权类型）、三级 OAuth（授权类型）和代表代币交换（`AUTHORIZATION_CODE`授权类型）。`TOKEN_EXCHANGE`您可以在同一个账户和区域的 Amazon Bedrock I AgentCore dentity 中配置授权提供商，以便网关调用 MCP 服务器。如果您使用代币交换，请查看该目标类型的代币交换注意事项。
+ IAM（[Amazon 签名版本 4（Sig V4）](https://docs.amazonaws.cn/AmazonS3/latest/API/sig-v4-authenticating-requests.html)）— 网关使用带有网关服务角色证书的 SigV4 对 MCP 服务器的请求进行签名。您可以`IamCredentialProvider`使用 SigV4 签名所需的服务名称和可选区域（默认为网关区域）来配置。
+ API 密钥 — 网关使用 API 密钥凭据提供商向 MCP 服务器进行身份验证。您在与网关相同的账户和区域中配置 Amazon Bedrock I AgentCore dentity 中的 API 密钥提供商。

**重要**  
IAM (SigV4) 出站授权要求 MCP 服务器托管在原生支持 IAM 身份验证的 Amazon 服务后面。网关使用 SigV4 签署出站请求，但不修改目标上的身份验证配置。目标服务必须能够验证 SigV4 签名。  
以下 Amazon 服务本身支持 IAM 身份验证，并且与 MCP 服务器目标的 IAM 出站授权兼容：  
亚马逊基岩网关 AgentCore 
亚马逊 Bedrock AgentCore 运行时（请参阅在 AgentCore 运行时[部署 MCP 服务器）](runtime-mcp.md)
Amazon API Gateway
Lambda 函数 URL
不进行本地验证 SigV4 签名的服务，例如应用程序负载均衡器或直接 Amazon EC2 终端节点，与 IAM 出站授权不兼容。如果您的 MCP 服务器托管在其中一项服务之后，请改用 OAuth 或 API 密钥授权。

 **MCP 服务器目标的配置注意事项 ** 

必须配置以下内容。

1. MCP 服务器必须具有工具功能。提示和资源功能是可选的，在服务器发布提示和资源功能时会自动同步。

1. 支持的 MCP 协议版本为-** 2026-07-28 **、202 ** 5-11-25、2025-06-18 和 2025 ** -03-26。** ** ** **

1. 对于服务器提供的 URL/endpoint 信息，应对 URL 进行编码。网关将使用相同的 URL 来调用服务器。

**注意**  
对于启用 MCP 版本更新的账户，您可以使用该`UpdateGateway`操作修改网关支持的协议版本。否则，当您创建网关时，支持的版本是固定的。

**提示**  
如果您的 MCP 服务器托管在 AgentCore Runtime 上，则可以避免在每次请求时使用 MCP 服务器重复初始化。在网关[上启用 ](gateway-sessions.md) MCP 会话，或在目标中添加`Mcp-Session-Id`为允许的`metadataConfiguration`请求和响应标头。这样可以降低后续工具调用的延迟。本指南适用于版本`2025-11-25`及更早版本。版本`2026-07-28`是无状态的，不使用标`Mcp-Session-Id`头。

 **On-behalf-of 代币交换注意事项 ** 

当您使用代表令牌交换（授权类型）作为 MCP 服务器`TOKEN_EXCHANGE`目标的出站授权时，以下限制适用：
+  **支持 2LO 的授权服务器 ** — 如果您的授权服务器允许机器对机器身份验证（`CLIENT_CREDENTIALS`授权，也称为双边 OAuth），则可以使用默认列表模式。在默认列表模式下，网关在`CreateGatewayTarget`、和期间运行后台同步`UpdateGatewayTarget`，`SynchronizeGatewayTargets`以获取 MCP 服务器的工具（使用`tools/list`）、提示和资源。在这些控制平面操作期间不存在入站用户令牌，因此同步使用机器对机器令牌而不是代表令牌交换。
+  **不支持 2LO 的授权服务器 ** — 如果您的授权服务器不支持机器间身份验证，请改用 DYNAMIC 列表模式。在动态模式下，网关在调用时发现 MCP 服务器的功能。由于存在入站用户令牌并且可以在此时进行交换，因此网关不需要控制平面后台同步。

### 保护抽样和采样请求状态（版本 2026-07-28 及更高版本）
<a name="gateway-target-MCPservers-request-state"></a>

在版本`2026-07-28`及更高版本中，抽取和采样使用多往返请求 (MRTR) 模式。您的 MCP 服务器目标在`input_required`结果中生成该`requestState`值；网关将该值视为不透明。网关不存储`requestState`。它仅在客户端和 MCP 服务器目标之间不变地转发该值时将其保存在内存中，并在请求完成时将其丢弃。

AgentCore 网关和您的 MCP 服务器目标共同负责保护请求状态：
+  **AgentCore Gateway 根据网关的入站授权配置对每个请求**进行身份验证和授权，包括带有的重试。`requestState`无法向您的网关进行身份验证的呼叫者根本无法呈现请求状态。有关更多信息，请参阅为网关[设置入站授权](gateway-inbound-auth.md)。
+  **您的 MCP 服务器目标**负责验证`requestState`其收到的值，因为该值会通过客户端往返传输。MCP 规范要求服务器将客户端视为不可信的中介，并始终验证请求状态。如果状态包含特定于原始用户的数据，则该规范要求服务器以加密方式将该数据绑定到用户。重试时，服务器必须验证该状态是否属于当前经过身份验证的用户。网关不验证出示的呼叫者`requestState`是否与接收到的呼叫者相同。防止一个用户重播另一个用户的请求状态是你的 MCP 服务器的责任。

要保护请求状态，请按照 MCP 规范中的指导进行操作。对状态进行加密或签名（例如，使用 AES-GCM 或签名的 JWT），以确保机密性和完整性。将用户特定状态绑定到原始用户，使状态过期，并将任何纯文本状态值视为不可信输入。有关更多信息，请参阅模型上下文协议网站[上的](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr)多次往返请求。

## 使用授权码流程连接到 OAuth-protected MCP 服务器
<a name="gateway-target-MCPservers-auth-code-grant-flow"></a>

为了支持 MCP 服务器目标的授权码授权类型（三段 OAuth），Amazon Bedrock AgentCore Gateway 提供了两种创建目标的方法。

 **创建 MCP 服务器目标期间的隐式同步 ** 

使用此方法，管理员用户使用响应中返回的授权 URL 在`CreateGatewayTarget``UpdateGatewayTarget`、或`SynchronizeGatewayTargets`操作期间完成授权码流程。这允许亚马逊 Bedrock AgentCore Gateway 预先发现和缓存 MCP 服务器的工具。

**注意**  
您无法删除、更新或同步处于待处理授权状态（`CREATE_PENDING_AUTH``UPDATE_PENDING_AUTH`、或`SYNCHRONIZE_PENDING_AUTH`）的目标。等待授权完成或失败，然后再对目标执行进一步的操作。

 **在创建 MCP 服务器目标期间预先提供架构 ** 

使用这种方法，管理员用户在`CreateGatewayTarget`或使用该`mcpToolSchema`字段进行`UpdateGatewayTarget`操作期间直接提供工具架构，而不是 Amazon Bedrock AgentCore Gateway 从 MCP 服务器动态获取它们。Amazon Bedrock AgentCore Gateway 解析提供的架构并缓存工具定义。

**注意**  
您无法同步配置了静态工具架构的目标 (`mcpToolSchema`)。通过`UpdateGatewayTarget`调用删除静态架构以启用动态工具同步。

 **URL 会话绑定 ** 

 [OAuth 2.0 授权 URL 会话绑定](oauth2-authorization-url-session-binding.md)可验证发起 OAuth 授权请求的用户是否与授予同意的用户相同。用户完成同意后，浏览器会重定向回在目标系统上配置的具有唯一会话 URI 的返回 URL。然后，应用程序负责调用 [ CompleteResourceTokenAuth ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_CompleteResourceTokenAuth.html) API，提供用户的身份和会话 URI。Amazon Bedrock I AgentCore dentity 会验证启动流程的用户是否与在将授权码交换为访问令牌之前完成流程的用户相同。

这样可以防止用户意外共享授权 URL 而其他人完成同意，这会将访问令牌授予错误的一方。授权 URL 和会话 URI 的有效期仅为 10 分钟，这进一步限制了滥用时间。会话绑定在目标创建（隐式同步）和工具调用期间适用。

**注意**  
通过 Amazon 管理控制台执行目标操作（创建、更新或同步）和授权时，将代表资源所有者进行[CompleteResourceTokenAuth](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_CompleteResourceTokenAuth.html)调用，授权后无需采取进一步的操作。

## 配置权限
<a name="gateway-target-MCPservers-permissions"></a>

您用于创建、更新或同步 MCP 服务器目标的 IAM 角色应具有以下示例中所示的权限。

```
{
"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:GetResourceApiKey",
                "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/*"
        }
    ]
}
```