Introduction to AWS Agent Registry updates
AWS describes a push-based architecture for keeping AWS Agent Registry records aligned with the Model Context Protocol (MCP) servers they describe. When a runtime update occurs, an event triggers a Lambda function that retrieves the server’s current tools, compares them with the registry, and updates an existing record when relevant definitions have changed. The aim is to make catalog maintenance part of the deployment workflow instead of a separate task that engineers can forget.
AWS Agent Registry is a capability of Amazon Bedrock AgentCore. In the architecture, it stores MCP server records and tool schemas for consumers to discover. Those records need to reflect changes to the underlying server: adding a tool or changing its schema creates a corresponding need to refresh the catalog. A successful deployment alone does not establish that the discovery information is current.
The approach has two important boundaries. The sample requires an existing registry record created during onboarding; it does not register new servers. Updates also depend on event delivery: AWS reports approximately 5–15 minutes of CloudTrail delivery delay. The design therefore provides automated synchronization after a runtime change, with a delay that matters when assessing metadata freshness.
The architecture and implementation details discussed here come from AWS’s technical walkthrough. That material describes a sample implementation and its intended behavior; it does not supply independent measurements of reliability improvements.
Importance of automated updates
The practical problem is a gap between what a server exposes and what its catalog record advertises. AWS illustrates this with an engineer adding a tool to an MCP server while forgetting to update the catalog. Consumers relying on the registry miss the new capability, even though the server already makes it available. Discovery becomes incomplete because the information describing the runtime has fallen behind the runtime itself.
Schema changes introduce another concern. According to AWS, applications using an outdated schema may encounter unexpected runtime behavior or silent workflow deviations. This makes catalog maintenance relevant to both discovery and execution: a consumer needs to know that a capability exists and have an accurate description of how to call it. A record that remains visible can still be misleading if its tool definitions are obsolete.
AWS also describes a broader organizational consequence. When teams stop trusting the registry, they can fall back on hardcoded endpoints, informal knowledge sharing, and stale documentation. The reason to automate updates is therefore more substantial than reducing administrative effort. A shared catalog is useful only while its consumers can reasonably rely on the information it contains.
The editorial implication is that metadata freshness belongs within the operational workflow for MCP server changes. In this sample, the event that follows a runtime update initiates reconciliation, reducing reliance on an engineer remembering a second maintenance action. The registry still depends on onboarding and governance, but routine changes to tools can be synchronized automatically.
That benefit should be stated precisely. Automation addresses the documented path from an UpdateAgentRuntime event to an existing registry record. It does not establish that every possible change to a server will be detected through that path, nor does the supplied walkthrough quantify how often stale records are eliminated. Its supported contribution is a concrete mechanism for reducing drift after the runtime updates it captures.
Architecture overview for push-based updates
The pipeline combines AWS CloudTrail, Amazon EventBridge, AWS Lambda, AWS Agent Registry, and AgentCore Identity. Each component has a distinct role: CloudTrail captures the runtime update, EventBridge routes the resulting event, Lambda retrieves and compares tool definitions, and the registry receives the refreshed metadata. AgentCore Identity brokers the authentication needed for Lambda to query the MCP server.
In the two-account example, Account A is the registry account. It owns the registry, the EventBridge rule, the push-sync Lambda function, and CloudTrail logs identified in the architecture description. Account B hosts the MCP server runtime and the Amazon Cognito OAuth provider used for authentication. CloudTrail captures the runtime update event in Account B, whose EventBridge configuration forwards matching events to Account A’s event bus.
AWS says the same pattern can extend to multiple MCP server accounts around the central registry account. The sample’s authentication configuration supports this arrangement through account-specific credential providers. Centralizing the synchronization function does not remove the need to configure how it authenticates to each target account.
For a single-account deployment, the resources reside together and the cross-account forwarding step is omitted. Events flow through the account’s own EventBridge bus to the synchronization function. The difference is in routing and resource placement; the core sequence of fetching tools, finding a record, comparing definitions, and updating metadata remains the same.
The supplied EventBridge rule pattern is:
{ "source": ["aws.bedrock-agentcore"], "detail-type": ["API Call via AWS CloudTrail"], "detail": { "eventName": ["UpdateAgentRuntime"] } }
This pattern defines the trigger’s scope. It matches the specified CloudTrail API event rather than describing a periodic sweep of every server. AWS says that UpdateAgentRuntime can be called through the AgentCore CLI command agentcore deploy or directly. The EventBridge target passes the full CloudTrail event JSON to Lambda.
The term push-based also needs a technical distinction. The update event is pushed through the routing pipeline, but the tool definitions are fetched from the MCP server. Lambda does not simply copy schemas out of the deployment event. It uses that event to identify the server, authenticates to it, and asks for the current tool list. This distinction explains why both event routing and successful server access are necessary for synchronization.
Workflow of the update process
Capture the event and identify the server
The workflow begins when a developer updates an MCP server and the UpdateAgentRuntime call is recorded as a CloudTrail management event. AWS reports a delivery delay of approximately 5–15 minutes. In a cross-account setup, EventBridge forwards the matching event from Account B to Account A, where the rule invokes the synchronization Lambda. Single-account deployments skip that forwarding step.
Lambda extracts the runtime ARN, or Amazon Resource Name, from detail.responseElements.agentRuntimeArn in the event. The supplied helper returns no endpoint or account identifier when that ARN is absent. It extracts the account identifier from the ARN and reads the Region from detail.awsRegion, with us-west-2 as the sample’s fallback.
The helper then URL-encodes the ARN and builds the runtime invocation endpoint with qualifier=DEFAULT. This makes the event’s runtime identity the link between the update notification and the server Lambda will query. The account identifier also helps select the authentication configuration for that server.
Authenticate through AgentCore Identity
The sample uses a two-step authentication flow. First, Lambda exchanges its execution identity for a temporary workload access token through get_workload_access_token. It then uses that token with get_resource_oauth2_token to obtain a scoped OAuth bearer token through the credential provider. The supplied call specifies oauth2Flow="M2M".
Credential provider selection uses CREDENTIAL_PROVIDER_{ACCT_ID}, falling back to CREDENTIAL_PROVIDER. Scope selection follows the corresponding CREDENTIAL_SCOPE_{ACCT_ID} and CREDENTIAL_SCOPE settings. The workload identity is configured through WORKLOAD_IDENTITY_NAME. The helper raises an error when the credential provider or workload identity name is missing.
AWS explains that the credential provider stores the Cognito/OAuth configuration securely in AgentCore Identity, so Lambda does not need client secrets in its environment variables. This is the relevant security property of the sample’s authentication design. Its ability to query servers across accounts still depends on the appropriate provider, scope, and workload identity configuration.
Retrieve the current tool definitions
With a bearer token available, Lambda queries the MCP server through streamable HTTP. The supplied helper accepts only HTTPS endpoints. It sends an initialize request before calling tools/list, using protocol version 2025-03-26 in the initialization payload. If initialization returns an Mcp-Session-Id header, that session identifier is passed with the tool-list request.
Both HTTP requests have a 30-second timeout in the supplied code and check for HTTP errors. The helper parses the responses through an SSE JSON parsing function referenced in the sample. These details show that retrieving tools is an authenticated interaction with the running server, rather than a lookup confined to registry storage.
The returned tool definitions provide the runtime-side information for the comparison. Because this retrieval happens after event delivery and authentication, the CloudTrail delay should not be treated as a measured end-to-end synchronization time. The supplied evidence gives no complete timing measurement for the entire sequence.
Find the existing registry record
Lambda next locates the registry record corresponding to the server. AWS’s prose describes searching APPROVED records for the runtime ARN embedded in mcpServer.data during record creation. The helper attempts matches using the decoded ARN, the URL-encoded ARN, and the MCP invocation URL.
This creates a prerequisite for onboarding: the existing record must contain identifying information that the synchronization function can match. If the helper finds no corresponding record, it returns no record identifier. The sample does not create a replacement or a new entry. Automated metadata maintenance therefore depends on successful initial registration.
There is also a material distinction between the narrative and the supplied code. Although the narrative describes searching approved records, the shown helper explicitly skips DRAFT records; it does not show a general condition requiring every remaining record to have status APPROVED. The evidence does not establish how other statuses would be handled beyond that visible check. Teams evaluating the sample should preserve this distinction when assessing its approval behavior.
Compare definitions and update when necessary
AWS describes normalizing tool lists by sorting them by name and comparing three fields: name, description, and inputSchema. This avoids treating a different ordering of otherwise identical tools as a substantive change. It also defines the comparison’s scope: a description change can matter alongside a tool-name or input-schema change.
According to the walkthrough, Lambda updates the registry when the compared definitions differ and logs additions or removals. When no relevant difference is detected, it avoids an unnecessary write. The supplied excerpt ends during the normalization code, however, so it does not provide a complete update handler to reproduce or independently inspect.
The source says each server emitting an UpdateAgentRuntime event follows this workflow independently and that Lambda handles one event at a time under the EventBridge invocation model. The supplied material does not specify retry behavior, ordering guarantees, or recovery from a failed synchronization. Those omissions limit what can be concluded about operational reliability from this sample alone.
Conclusion on the benefits of automation
The strongest benefit of this architecture is the explicit connection between a runtime update and catalog reconciliation. CloudTrail and EventBridge carry the change notification; Lambda obtains the server’s current tool definitions; and an existing registry record is refreshed when the compared metadata differs. The same sequence supports a single account or a central registry serving multiple accounts.
Its value rests on making discovery information follow deployed capabilities with fewer manual maintenance steps. That directly addresses the stale metadata problem AWS describes, while retaining initial registration as a separate prerequisite. Authentication configuration, record matching, and the visible approval-status distinction remain consequential implementation details.
The supported conclusion is a bounded one: this sample offers a practical route to fresher registry metadata after captured runtime updates. It includes a documented event-delivery delay and provides no measured reliability improvement or complete failure-recovery design. Enterprise trust depends on understanding those boundaries as well as automating the update itself.
