本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 连接 MCP 服务器
模型上下文协议 (MCP) 服务器通过提供对来自外部可观测性工具、自定义监控系统和操作数据源的数据的访问来扩展 AWS DevOps 代理的调查能力。本指南介绍如何将 MCP 服务器连接到 AWS DevOps 代理。
## 要求
在连接 MCP 服务器之前，请确保您的服务器满足以下要求：
+ **可流式传输 HTTP 传输协议 ** — 仅支持实现可流式传输 HTTP 传输协议的 MCP 服务器。
+ **身份验证支持 ** — 您的 MCP 服务器必须支持以下身份验证方法之一：OAuth 2.0（客户端凭据或 3LO）、 key/token基于 API 的身份验证或 AWS 签名版本 4 (SigV4)。
## 安全注意事项
将 MCP 服务器连接到 AWS DevOps 代理时，请考虑以下安全方面：
+ **工具许可清单 — ** 您应仅将代理空间所需的特定工具列入许可名单，而不是公开 MCP 服务器上的所有工具。有关如何允许每个代理空间列出工具，请参阅在代理空间[中](#configuring-integrations-and-knowledge-connecting-mcp-servers)配置 MCP 工具。
请注意，任何 MCP 工具的最大工具名称长度为 64 个字符。有关每个代理空间允许的最大 MCP 工具数量，请参阅[配额](quotas.md)。
+ **即时注入风险 ** — 自定义 MCP 服务器可能会带来额外的即时注入攻击风险。有关更多信息，请参见[即时注入保护： AWS DevOps 客户端安全](aws-devops-agent-security.md)。
+ **Read-only 工具和访问权限-** 仅将只读 MCP 工具列入许可名单，并确保身份验证凭据仅允许只读访问。
有关即时注入和责任分担模型的更多信息，请参阅[AWS DevOps 代理安全](aws-devops-agent-security.md)。
**注意**
如果您的 MCP 服务器位于私有网络上，请参阅 [连接到私人托管的工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)
## 社区 MCP 服务器
[AWS DevOps 代理工具存储库](https://github.com/aws/tools-for-devops-agent)包括可部署的 MCP 服务器，这些服务器为代理提供用于深度基础设施诊断的自定义工具，例如亚马逊弹性Kubernetes Service (Amazon EKS) 节点日志收集、亚马逊虚拟私有云 (Amazon VPC) DNS 解析探测和亚马逊关系数据库服务 (Amazon RDS) 数据库运行状况检查。存储库由 AWS DevOps 代理服务团队维护，所有贡献在添加之前都要经过相同的安全审查栏。要浏览可用的内容，请参阅 GitHub 网站上的 [ MCP 服务器目录](https://aws.github.io/tools-for-devops-agent/mcp-servers/)。
要使用社区 MCP 服务器，请执行以下操作：
1. 按照服务器自述文件中的部署说明将 MCP 服务器部署到您的 AWS 账户。
1. 按照以下 “注册 MCP 服务器” 中的步骤，在代理空间中[注册已部署的服务器](#registering-an-mcp-server-account-level)作为能力提供者。
## 注册 MCP 服务器（账户级）
MCP 服务器在 AWS 账户级别注册，并在该账户中的所有代理空间之间共享。然后，各个代理空间可以从每台 MCP 服务器中选择所需的特定工具。
### 第 1 步：MCP 服务器详细信息
1. 登录 AWS 管理控制台
1. 导航到 AWS DevOps 代理控制台
1. 转到**能力提供者**页面（可从侧面导航中访问）
1. 在 “**可用**提供商” 部分**中找到 ** MCP 服务器，然后选择注册 ** **
1. 在 ** MCP 服务器详细信息**页面上，输入以下信息：
+ **名称 ** — 输入 MCP 服务器的描述性名称
+ **终端节点 URL ** — 输入 MCP 服务器端点的完整 HTTPS URL
+ **描述**（可选）-添加描述以帮助确定服务器的用途
+ **启用动态客户机注册 **-如果要允许 AWS DevOps 代理自动向 MCP 服务器的授权服务器注册，请选中此复选框
+ **使用私有连接连接到端点 **-如果您想让 AWS DevOps 代理私下向 MCP 服务器发出请求，请选中此复选框。您可以选择现有的私有连接或创建新的私有连接。如果您使用 OAuth 身份验证，则私有连接适用于 MCP 服务器端点和令牌交换端点。确保使用可以将流量路由到两个端点的主机地址配置私有连接。有关更多信息，请参阅 [连接到私人托管的工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。
1. 选择 **Next**（下一步）
**注意**
**MCP 服务器端点 URL 将显示在您账户的 AWS CloudTrail 日志中。
### 第 2 步：授权流程
选择您的 MCP 服务器的身份验证方法：
**OAuth 客户端凭证 ** — 如果您的 MCP 服务器使用 OAuth 客户端凭据流程：
1. 选择 ** OAuth 客户端凭证 **
1. 选择**下一步**。
**OAuth 3LO (Three-Legged OAuth) ** — 如果您的 MCP 服务器使用 OAuth 3LO 进行身份验证：
1. 选择 ** OAuth 3LO **
1. 选择**下一步**。
**API 密钥 ** — 如果您的 MCP 服务器使用 API 密钥身份验证：
1. 选择 ** API 密钥 **
1. 选择**下一步**。
**AWS SigV4 ** — 如果您的 MCP 服务器使用 AWS 签名版本 4 身份验证：
1. 选择 **AWS SigV4 **
1. 选择**下一步**。
### 第 3 步：授权配置
根据所选的身份验证方法配置其他授权参数：
**对于 OAuth 客户端凭证：**
1. **客户端 ID ** — 输入 OAuth 客户端的客户端 ID
1. **客户端密钥 ** — 输入 OAuth 客户端的客户端密钥
1. **交换 URL ** — 输入 OAuth 令牌交换端点 URL
1. **交换参数 ** — 输入用于通过服务进行身份验证的 OAuth 令牌交换参数
1. **添加范围 **-为身份验证添加 OAuth 范围
1. 选择**下一步**。
**对于 OAuth 3LO：**
1. **客户端 ID ** — 输入 OAuth 客户端的客户端 ID
1. **客户端密钥 ** — 如果 OAuth 客户端要求输入 OAuth 客户端的客户端密钥
1. **交换 URL ** — 输入 OAuth 令牌交换端点 URL
1. **授权 URL **-输入 OAuth 授权端点 URL
1. **代码质询支持 **-如果您的 OAuth 客户端支持代码质询，请选中此复选框
1. **添加范围 **-为身份验证添加 OAuth 范围
1. 选择**下一步**。
**对于 API 密钥：**
1. 输入 API 密钥名称
1. 输入请求中将包含 API 密钥的标头的名称
1. 输入您的 API 密钥值
1. 选择**下一步**。
**对于 AWS SigV4：**
AWS SigV4 身份验证允许 AWS DevOps 代理连接到使用 AWS 签名版本 4 进行请求签名的 MCP 服务器。这对于托管在亚马逊 API 网关或其他支持 SigV4 身份验证的 AWS 服务后面的 MCP 服务器很有用。
**注意：使用 SigV4 身份验证的 MCP 服务器不支持**私有连接。您的 MCP 服务器端点必须可公开访问。有关使用其他身份验证方法的私有网络上的 MCP 服务器，请参阅[连接到私人托管的工具](configuring-integrations-and-knowledge-connecting-to-privately-hosted-tools.md)。
1. **配置 IAM 角色 **-选择以下选项之一：
+ **使用现有角色 **-从下拉列表中选择现有的 IAM 角色。该角色必须具有允许 AWS DevOps 代理服务委托人代入的信任策略（请参阅为 SigV4 身份验证[configuring-integrations-and-knowledge-connecting-mcp-servers.html#creating-an-iam-role-for-sigv4-authentication](configuring-integrations-and-knowledge-connecting-mcp-servers.html#creating-an-iam-role-for-sigv4-authentication)创建 IAM 角色）。
+ **手动创建新角色 ** — 按照控制台中显示的分步说明使用正确的信任策略创建新的 IAM 角色。
+ **无需专用角色即可注册 ** — 在不提供 IAM 角色的情况下注册 MCP 服务器。 AWS DevOps 相反，代理使用与您的代理空间关联的 AWS 账户中的 IAM 角色签署请求，并将连接验证推迟到您关联服务器之前。选择此选项可跨与代理空间连接的 AWS 账户进行跨账户访问。有关详细信息，请参阅没有专用角色的[Cross-account 访问权限](configuring-integrations-and-knowledge-connecting-mcp-servers.html#cross-account-access-without-a-dedicated-role)。
1. **AWS 区域 ** — 输入用于 SigV4 签名的 AWS 区域（例如，`us-east-1`）。要使用 Sigv4A 多区域签名，请输入。`*`
1. **服务名称 ** — 输入用于 SigV4 签名的 AWS 服务名称（`execute-api`例如，对于 API 网关）。
1. **自定义标头**（可选）-添加最多 10 个自定义键值标头对，以包含在每个签名请求中。
1. 选择**下一步**。
### 第 4 步：查看并提交
1. 查看所有 MCP 服务器配置的详细信息
1. 选择 “****提交” 完成注册
1. AWS DevOps 代理将验证与您的 MCP 服务器的连接
1. 成功验证后，您的 MCP 服务器将在账户级别注册
**注意：**对于未注册专用角色的服务器， AWS DevOps 代理使用主 AWS 帐户角色将连接验证推迟到关联时间。如果验证失败，则可能需要更正注册期间提供的 MCP 服务器配置（例如终端节点、区域或服务）。有关详细信息，请参阅没有专用角色的[Cross-account 访问权限](configuring-integrations-and-knowledge-connecting-mcp-servers.html#cross-account-access-without-a-dedicated-role)。
## 在代理空间中配置 MCP 工具
在帐户级别注册 MCP 服务器后，您可以配置该服务器中的哪些工具可供特定的代理空间使用：
1. 在 AWS DevOps 代理控制台中，选择您的代理空间
1. 转到 ** “**能力” 选项卡
1. 在 ** MCP 服务器**部分中，选择添加 ** **
1. 选择要连接到此代理空间的已注册 MCP 服务器
1. 配置此 MCP 服务器中的哪些工具应可供代理空间使用：
+ **允许所有工具 **-使 MCP 服务器中的所有工具都可用
+ **选择特定工具 **-允许您选择将哪些工具列入许可名单
1. 选择 “****添加” 将 MCP 服务器连接到您的代理空间
AWS DevOps 代理现在可以在此代理空间进行调查期间使用您的 MCP 服务器上列入许可名单的工具。
## 管理 MCP 服务器连接
**更新身份验证凭据 **-您可以更新已注册的 MCP 服务器的身份验证凭据，而无需取消注册。导航到 AWS DevOps 代理控制台中的**能力提供者**页面，选择您的 MCP 服务器，然后**从 “**操作**” 菜单中选择 “**更新”。您的代理空间关联将被保留。您可以更新的内容取决于身份验证方法：
+ **API 密钥 ** — 输入新的 API 密钥值和标头名称以轮换凭证。更新期间无法更改终端节点。
+ **OAuth 3LO (Three-Legged OAuth) ** — 刷新存储 Re-run 令牌的授权流程。您无需重新输入客户凭证。当您提交时， AWS DevOps 代理会将您重定向到提供商的同意页面以完成重新授权。或者，您可以覆盖授权 URL。如果您将其留空， AWS DevOps 代理会从您的 MCP 服务器的元数据中发现它。
+ **AWS SigV4 ** — 更新服务器名称、终端节点、描述、 AWS 区域、服务、IAM 角色和自定义标头。
使用 OAuth 客户端凭据的 MCP 服务器无法就地更新。要更改这些凭证，请移除所有活动关联，注销 MCP 服务器，然后使用新值重新注册。
**查看连接的 MCP 服务器 ** — 要查看连接到代理空间的所有 MCP 服务器，请选择您的代理空间，转到 “**功能**” 选项卡，然后查看 “**MCP 服务器” 部分。**您也可以在此处更新选定的工具。
**删除 MCP 服务器连接 **-要断开 MCP 服务器与代理空间的连接，请在 “**MCP 服务器” ** 部分选择服务器，然后选择 “删除”。** **要完全删除 MCP 服务器注册，请先将其从所有代理空间中删除，然后删除帐户级别的注册。
## 为 SigV4 身份验证创建 IAM 角色
使用 AWS SigV4 身份验证时， AWS DevOps 代理在您的账户中扮演一个 IAM 角色来签署向您的 MCP 服务器发出的请求。此角色的信任策略必须允许 AWS DevOps 代理服务主体 (`aidevops.amazonaws.com`) 代理，同时混淆代理保护。
### 信任策略
使用以下信任策略创建 IAM 角色。`REGION`替换为您的 AWS 地区（例如，`us-east-1`）`ACCOUNT_ID`和您的 AWS 账户 ID。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "aidevops.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "ACCOUNT_ID"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:aidevops:REGION:ACCOUNT_ID:service/*"
}
}
}
]
}
```
信任政策包括以下条件，以防止出现[混淆的代理问题](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)：
+ `aws:SourceAccount`— 将角色代入限制为来自您 AWS 账户的请求。
+ `aws:SourceArn`— 将角色假设限制为来自您账户中的 AWS DevOps 代理服务资源的请求。
### 权限策略
为角色附加权限策略，以授予调用 MCP 服务器所需的最低权限。例如，如果您的 MCP 服务器托管在亚马逊 API 网关后面，则该角色应具有 API 网关资源的`execute-api:Invoke`权限。
### Multi-region 签名 (Sigv4a)
如果您的 MCP 服务器部署在多个 AWS 区域，则可以使用 [ Sigv4a（签名版本 4a）](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)进行多区域签名。要启用此功能`*`，请在配置 SigV4 授权时输入为 AWS 区域。Sigv4a 使用非对称签名，允许单个签名请求在多个区域有效。
## Cross-account 无需专门角色即可访问
您可以使用**无角色注册，而不是为您的 MCP 服务器注册专用 IAM 角色**：注册没有角色的服务器，使用已与您的 AWS DevOps 代理空间关联的 AWS 账户中的 IAM 角色让代理签署请求。当您的 MCP 服务器需要访问跨越连接到代理空间的主帐户和辅助 AWS 帐户的资源，而不是仅限于一个帐户的单一角色时，这很有用。
### 工作原理
Cross-account 没有专门角色的访问权限的工作原理如下：
1. **在没有角色的情况下注册 MCP 服务器 **-在 SigV4 授权配置步骤中，选择在没有专用角色的情况下**注册。** AWS DevOps 代理注册了服务器，但尚未验证连接，因为没有角色可以用来签署验证请求。
1. **将 MCP 服务器与代理空间关联 ** — 将 MCP 服务器添加到代理空间时， AWS DevOps 代理会使用**主 AWS 帐户（监视器）角色对其进行验证。**它假定该角色并调用`listTools`以确认服务器可访问且配置有效。代理空间必须有一个与之关联的主 AWS 帐户。该账户的角色必须能够调用您的 MCP 服务器。
1. **调查期间 ** — 当代理在操作特定账户时使用 MCP 服务器时，它将使用该账户的角色签署请求，即**主账户的主账户角色**和每个**辅助账户**的相应辅助账户角色。代理将在此 MCP 服务器上使用的每个主帐户或辅助帐户角色都必须能够调用它。
### 要求
在将无角色的 SigV4 MCP 服务器与代理空间关联之前：
+ 代理空间必须有一个与之**关联**的主 AWS 帐户。如果没有主账户，关联就会失败，因为主账户角色会执行`listTools`验证。错误消息是：*“在没有专用角色的情况下注册的 SigV4 MCP 服务器需要在代理空间中关联主帐户。”*
+ **主账户角色**必须授予调用您的 MCP 服务器的权限（`execute-api:Invoke`例如，对于 API Gateway-hosted 服务器）。**您期望代理在此 MCP 服务器上使用的每个**辅助账户角色也必须授予此权限。有关更多信息，请参阅[权限政策](configuring-integrations-and-knowledge-connecting-mcp-servers.html#permissions-policy)。 AWS DevOps 代理在关联时使用主要角色，在调查这些账户时使用次要角色。
## 问题排查
### 关联无角色的 MCP 服务器失败：“需要主账户关联”
如果您注册了没有专用角色的 MCP 服务器且关联失败，请检查错误消息。如果错误表明服务器*需要在代理空间中关联主帐户*，则代理空间没有与其连接的主 AWS 帐户。
AWS DevOps 当您使用代理空间主 AWS 账户的 IAM 角色关联无角色的 SigV4 MCP 服务器时，代理会对其进行验证。要解决这一问题，请执行以下操作：
1. 向代理空间添加主 AWS 帐户（如果还没有主帐户）。
1. 确保该账户的 IAM 角色有权调用您的 MCP 服务器（`execute-api:Invoke`例如，托管在亚马逊 API Gateway 后面的服务器）。
1. 再次关联 MCP 服务器。
## 相关主题
+ AWS DevOps 代理中的安全性
+ 设置代理空间
+ 即时注入保护