当发布在 AWS Agent Registry 中的 Model Context Protocol (MCP) 服务器新增工具或更新其 schema 时,注册表中的记录必须同步更新。否则,使用者将发现过时的元数据。对于跨账户管理多个 MCP 服务器的组织,这种同步能确保目录记录在现有治理工作流内保持最新。
在大多数企业部署中,目录的价值取决于其新鲜度。如果开发人员在周一部署了新工具,但注册表记录仍反映上周的 schema,使用者就会对目录失去信任。过时的元数据直接降低注册表的可靠性,导致团队无意中构建基于不准确信息的依赖。
当工程师向 MCP 服务器添加工具但忘记更新目录时,会出现以下问题:使用者完全错过新功能;应用程序可能使用过时的 schema 调用该工具,导致意外的运行时行为或静默的工作流偏差;在多个团队中放大后,这种缺乏自动化会侵蚀对注册表的信任。组织最终会退回到临时发现机制,如硬编码端点、非正式知识共享和过时的文档。
本文概述了一种事件驱动架构,利用 AWS CloudTrail、Amazon EventBridge 和 AWS Lambda 自动完成这些更新。
架构概述
该解决方案将这些服务组合成一个事件驱动管道,自动检测运行时变更并将其同步到注册表。
该架构支持多账户和单账户环境:
单账户设置:对于简单部署,所有组件都位于账户 A 中。事件直接在账户 A 内流动,无需跨账户转发设置。
多账户设置:涉及两个账户,其中来自账户 B 的运行时事件被安全地转发到账户 A。
账户 A(注册表账户)拥有 AWS Agent Registry、Amazon EventBridge 规则、推送同步 Lambda 函数和 CloudTrail 日志。
账户 B(MCP 服务器账户)托管 MCP 服务器运行时和用于身份验证的 Amazon Cognito OAuth 提供程序。
示例使用两个账户,但您可以将架构扩展到多个账户,其中账户 A 作为注册表账户,多个 AWS 账户类似于账户 B 用于不同的 MCP 服务器。
下图显示了账户 B 中 MCP 服务器更新的端到端事件流。捕获的事件被转发到账户 A,在那里 Lambda 函数查询 MCP 服务器以获取其工具并更新匹配的注册表记录。
图 1:跨账户 MCP 服务器更新的端到端事件流,从账户 B 中的 CloudTrail 事件到账户 A 中的注册表记录更新。
该架构使用五个 AWS 服务:
AWS CloudTrail 将 UpdateAgentRuntime API 调用捕获为管理事件。
Amazon EventBridge 将匹配的事件路由到 Lambda 函数,支持跨账户转发。
AWS Lambda 查询 MCP 服务器以获取其当前工具,与注册表进行差异比较,并在更改时更新记录。
AWS Agent Registry 存储 MCP 服务器记录及其工具 schema,作为中央事实来源。
AgentCore Identity(Amazon Bedrock AgentCore 的一项能力)安全地代理 OAuth 令牌交换,因此 Lambda 无需存储密钥即可进行身份验证。
工作原理:业务逻辑流程
部署后,管道运行以下端到端工作流:
触发:账户 B 中的开发人员更新 MCP 服务器,该服务器调用 Amazon Bedrock AgentCore 中的 UpdateAgentRuntime API,AWS CloudTrail 捕获该事件。
路由:Amazon EventBridge 捕获 CloudTrail 事件并将其转发到账户 A 中的中央事件总线。
解析:账户 A 中的同步 Lambda 从事件负载中提取运行时 Amazon Resource Name (ARN),并动态构建 MCP 服务器的调用 URL。这样它就知道要查询账户 B 中的哪个服务器。
身份验证:Lambda 通过 AgentCore Identity 生成安全的 OAuth 持有者令牌。
获取:Lambda 调用 MCP 服务器(先 initialize,然后 tools/list)以检索最新的工具信息。
同步:Lambda 通过 ARN 找到匹配的注册表记录,评估差异,并在 schema 更改时更新注册表。
此流程假设账户 A 中的 Agent Registry 已包含预注册的 MCP 服务器记录(在初始入职期间创建)。此示例中的 Lambda 函数仅更新现有记录,不会生成新记录。
同样的流程适用于单账户设置,其中所有资源(注册表、Lambda、Amazon EventBridge 规则和 MCP 服务器)都位于一个账户中。在这种情况下,跳过跨账户转发步骤。事件直接在同一账户的 Amazon EventBridge 总线内流动。
技术演练
本节以两个账户为例,逐步介绍单个 MCP 服务器更新的工作流,如架构图所示。
对于每个发出 UpdateAgentRuntime 事件的服务器,相同的流程会独立执行。Lambda 一次处理一个事件,随 Amazon EventBridge 调用模型自然扩展。
步骤 1:跨账户设置的事件捕获和路由
当开发人员部署或更新 MCP 服务器时,会调用 UpdateAgentRuntime API,可以由 AgentCore CLI (agentcore deploy) 或直接调用。
AWS CloudTrail 在账户 B 中将其记录为管理事件,交付延迟约为 5-15 分钟。然后事件被传递到账户 A 的默认 Amazon EventBridge 总线。
对于跨账户设置,账户 B 的 Amazon EventBridge 通过跨账户规则将匹配的事件转发到账户 A 的事件总线。
账户 A 中的 Amazon EventBridge 规则目标调用同步 Lambda,将完整的 CloudTrail 事件 JSON 作为输入负载传递。
Amazon EventBridge 规则模式:
{ "source": ["aws.bedrock-agentcore"], "detail-type": ["API Call via AWS CloudTrail"], "detail": { "eventName": ["UpdateAgentRuntime"] } }
步骤 2:提取 MCP 服务器 URL
Lambda 从事件中解析运行时 ARN。它提取托管账户 ID 和 AWS 区域,以动态构建目标 MCP 服务器的 URL 编码调用端点。
从 AWS CloudTrail 事件负载中提取运行时 ARN
def _extract_mcp_url(event): detail = event.get("detail", {}) runtime_arn = detail.get("responseElements", {}).get("agentRuntimeArn", "") if not runtime_arn: return None, None
从 ARN 解析账户 ID(第 5 个冒号分隔段)
arn_parts = runtime_arn.split(":") account_id = arn_parts[4] if len(arn_parts) > 4 else None region = detail.get("awsRegion", "us-west-2")
对 ARN 进行 URL 编码并构建 MCP 调用端点
encoded_arn = runtime_arn.replace(":", "%3A").replace("/", "%2F") mcp_url = (f"https://bedrock-agentcore.{region}.amazonaws.com" f"/runtimes/{encoded_arn}/invocations?qualifier=DEFAULT") return mcp_url, account_id
步骤 3:使用 AgentCore Identity 进行安全身份验证
Lambda 使用两步身份流进行身份验证。它将其执行身份交换为临时工作负载令牌。然后 Lambda 通过目标账户的凭证提供程序将此令牌交换为作用域限定的 OAuth 持有者令牌。
def get_bearer_token(account_id=None): """通过 AgentCore Identity 凭证提供程序获取 OAuth 持有者令牌。
两步过程:
- 从 AgentCore Identity 获取工作负载访问令牌(标识此 Lambda)
- 使用它从凭证提供程序获取 OAuth 令牌(M2M 流)
凭证提供程序将 Cognito/OAuth 配置安全地存储在 AgentCore Identity 中,因此 Lambda 环境变量中无需客户端密钥。 """ acct = account_id or "" provider_name = os.environ.get(f"CREDENTIAL_PROVIDER_{acct}") or os.environ.get("CREDENTIAL_PROVIDER", "") scope_str = os.environ.get(f"CREDENTIAL_SCOPE_{acct}") or os.environ.get("CREDENTIAL_SCOPE", "") scopes = [s.strip() for s in scope_str.split(",") if s.strip()] if scope_str else [] workload_name = os.environ.get("WORKLOAD_IDENTITY_NAME", "") if not provider_name: raise ValueError(f"No CREDENTIAL_PROVIDER configured for account {acct}") if not workload_name: raise ValueError("WORKLOAD_IDENTITY_NAME env var not set") region = os.environ.get("AWS_REGION", "us-west-2") client = boto3.client("bedrock-agentcore", region_name=region)
步骤 1:获取工作负载访问令牌(将此 Lambda 标识为受信任的工作负载)
wat_response = client.get_workload_access_token( workloadName=workload_name, ) print(f"Workload access token response keys: {list(wat_response.keys())}") workload_token = wat_response.get("workloadAccessToken") or wat_response.get("accessToken", "") if not workload_token: raise ValueError(f"No access token in workload response: {list(wat_response.keys())}")
步骤 2:使用工作负载令牌从凭证提供程序获取 OAuth 令牌
response = client.get_resource_oauth2_token( workloadIdentityToken=workload_token, resourceCredentialProviderName=provider_name, oauth2Flow="M2M", scopes=scopes, ) return response["accessToken"]
凭证提供程序按账户(CREDENTIAL_PROVIDER_{ACCT_ID})设置,因此一个 Lambda 可以跨多个账户对 MCP 服务器进行身份验证。
步骤 4:查询 MCP 服务器
使用标准 MCP 可流式 HTTP 机制,Lambda 通过 initialize 请求建立活动会话。会话激活后,它调用 tools/list 获取当前暴露的工具和 schema 的完整数组。
def call_tools_list(mcp_url, token): """调用 MCP 服务器的 initialize + tools/list 方法并返回结果。
MCP streamable-http 要求先 initialize 再 tools/list。 如果服务器使用会话,initialize 返回的 session_id 会传递给 tools/list。 """
验证 URL 方案以防止 file:// 或自定义方案访问
if not mcp_url.startswith("https://"): raise ValueError(f"Only HTTPS URLs are allowed, got: {mcp_url[:50]}")
步骤 1:初始化 MCP 会话
init_payload = { "jsonrpc": "2.0", "id": "init-1", "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "tool-sync-lambda", "version": "1.0.0"}, }, } init_resp = requests.post( mcp_url, json=init_payload, headers=_mcp_headers(token), timeout=30, ) init_resp.raise_for_status() session_id = init_resp.headers.get("Mcp-Session-Id") init_result = _parse_sse_json(init_resp.text) print(f"MCP session initialized, session_id={session_id}")
步骤 2:调用 tools/list
list_payload = { "jsonrpc": "2.0", "id": "list-1", "method": "tools/list", "params": {}, } list_resp = requests.post( mcp_url, json=list_payload, headers=_mcp_headers(token, session_id), timeout=30, ) list_resp.raise_for_status() return _parse_sse_json(list_resp.text)
步骤 5:找到匹配的注册表记录
Lambda 查询中央 Agent Registry 以定位相应记录。它在 APPROVED 记录中搜索 mcpServer.data 包含记录创建期间嵌入的运行时 ARN 的记录(参见部署部分)。
从 MCP URL 解码运行时 ARN 以进行匹配
def _find_record_by_mcp_url(client, registry_id, mcp_url): """搜索注册表记录,找到服务器 schema 包含运行时 ARN 的记录。
尝试三种匹配策略:
- 解码的 ARN(例如 arn:aws:bedrock-agentcore:...:runtime/TrimMCP-xxx)
- URL 编码的 ARN(例如 arn%3Aaws%3Abedrock-agentcore%3A...%2FTrimMCP-xxx)
- 完整 MCP URL 匹配
返回: (record_id, full_record) 元组。如果未找到匹配,两者均为 None。 """
从 MCP URL 提取运行时 ARN 以进行匹配
URL 格式:.../runtimes/arn%3A...%2Fruntime%2F/invocations...
解码得到:arn:aws:bedrock-agentcore:region:account:runtime/id
try: decoded_url = urllib.parse.unquote(mcp_url)
仅提取运行时路径:arn:aws:bedrock-agentcore:...:runtime/xxx
runtime_marker = "/runtimes/" idx = decoded_url.find(ru