Free Intensive Nov 21–22Free 2-day hands-on Vibecoding Intensive on Nov 21–22 at 16:00 MSK (Sat–Sun) · Live Cohort 3 starts Nov 23Join Free →Cohort 3 (Nov 23)
ReleaseInsight · On RadarAWS Machine Learning Blog→ original

AWS Agent Registry adds unified metadata schemas for agents and MCP servers

At companies with dozens of AI agents and MCP servers, it quickly becomes unclear who owns them and whether they have passed a security review. AWS Agent Registry now lets an administrator define a shared set of fields, such as environment, business unit and scan status, and every record must comply with it. The registry will reject "production" if only "prod" is allowed. That is why it is worth agreeing on the field vocabulary with the teams before creating the schema.

AI-processed from AWS Machine Learning Blog; edited by Hamidun News
AWS Agent Registry adds unified metadata schemas for agents and MCP servers
Source: AWS Machine Learning Blog. Collage: Hamidun News.
Listen to article
Article Fact Sheet & Key Figures
ParameterDetails
Primary sourceAWS Machine Learning Blog ↗
Editor-in-Chief
Field typestext, enum, URL and boolean. Schemas can be extended but fields cannot be renamed.
Search filters by fieldsenvironment=prod AND securityScanStatus=PASSED
Key metric #3A record without metadata gets NON_COMPLIANT and cannot move into approval.

When a company has many agents, MCP servers and skills, a mundane problem appears: nobody remembers who owns a given server, which environment it runs in, or whether anyone has checked it for security. AWS Agent Registry is a catalog where such resources are registered, approved and found. Previously, each record had a name, a description, a protocol descriptor and an approval status. There was nowhere to add the organization's own fields, such as business unit, owning team or risk class. Now the registry supports custom metadata schemas.

How the schema works

An administrator defines a set of key-value pairs that every registry record must carry. For each field, they specify a name, a type (text, enum, URL or boolean), allowed values and whether the field is required. Some fields are common to all record types, and others can be added for specific types. For example, in AWS's example, MCP servers received an optional networkEgress field: no outbound traffic, traffic only within a VPC, or a list of allowed internet addresses.

The registry validates values when a record is created or updated. If a team submits "production" instead of the allowed "prod", it receives a ValidationException. A record without metadata is saved with the status NON_COMPLIANT. This lets you keep a draft, but it cannot be submitted for approval until the required fields are filled in. The COMPLIANT status only means that the values match the schema. It is not an approval: approvers still make the decision.

Example: from registration to search

AWS walks through a scenario with a fictional company, AnyCompany. The administrator creates a registry without auto-approval. The required fields are environment, businessUnit and securityScanStatus. Optional fields are filled in later: ownerTeam, cmdbId, dataClassification and a link to the scanner report.

The payments team publishes an MCP server for reading data from the general ledger. It is first recorded with scan status PENDING. Then automation pulls data from existing systems: the security scanner result, the CMDB identifier and the data class. An important API detail: an update replaces the entire metadata map, so the script first reads the current values, adds its own, and writes everything back together.

When a record moves to "pending approval", the registry sends an event to Amazon EventBridge, and a rule triggers a function in AWS Lambda. The function checks four conditions: the record is COMPLIANT, the scan has passed (PASSED), a cmdbId is specified, and the data is public or internal. If a check fails, the record is rejected, and the reason names the specific condition. In production, it is more sensible to send records with confidential data to manual review rather than reject them.

A consumer finds the server through search_discoverable_registry_records. It can combine a natural language query ("ledger lookup") with field filters: environment=prod, businessUnit=payments, securityScanStatus=PASSED. Only approved records appear in the results. An agent does the same through the registry's MCP endpoint. In AWS's example, an agent built with Strands and a model from Amazon Bedrock turns the phrase "the production MCP server for payments that passed the scan" into such a filtered search.

What to consider when designing

AWS offers several practical recommendations.

  • First, agree on the vocabulary with the teams that publish and approve records. A schema can only be extended: you can add fields and allowed values, or make an optional field required. You cannot rename, delete or change the type of a field.
  • Old records are not rewritten when the schema changes. If a record no longer matches the schema, it is marked NON_COMPLIANT but keeps its approval status. Its next update must already conform to the new schema. Editing an approved record creates a draft that must be approved again. Until that approval, consumers see the previous version.
  • Make required only what the publisher can provide at registration. Values that arrive later from CI or scanners can start as temporary, for example PENDING.
  • Do not put secrets, internal addresses or detailed scan results into widely readable metadata. For such data, it is better to store a link to the report behind the access controls of the source system.

Bottom line

The new feature does not add models or change how agents work. It solves a governance problem: a shared vocabulary of facts that administrators, security teams, approvers and the agents themselves all use. If you are building an internal agent catalog, a metadata schema turns approval from reading descriptions into checking structured data, and turns search from guesswork into filters. The limitation is also clear: quality depends on how well you think through the fields in advance, since they cannot be renamed later. AWS has published the code example on GitHub, and details are available in the Agent Registry documentation.

Story

Key Questions Answered

How the schema works?

An administrator defines a set of key-value pairs that every registry record must carry. For each field, they specify a name, a type (text, enum, URL or boolean), allowed values and whether the field is required. Some fields are common to all record types, and others can be added for specific types. For example, in AWS's example, MCP servers received an optional networkEgress field: no outbound traffic, traffic only within a VPC, or a list of allowed internet addresses.

What are the key details on Example: from registration to search?

AWS walks through a scenario with a fictional company, AnyCompany. The administrator creates a registry without auto-approval. The required fields are environment, businessUnit and securityScanStatus. Optional fields are filled in later: ownerTeam, cmdbId, dataClassification and a link to the scanner report. The payments team publishes an MCP server for reading data from the general ledger. It is first recorded with scan status PENDING.

What to consider when designing?

AWS offers several practical recommendations. First, agree on the vocabulary with the teams that publish and approve records. A schema can only be extended: you can add fields and allowed values, or make an optional field required. You cannot rename, delete or change the type of a field. Old records are not rewritten when the schema changes. If a record no longer matches the schema, it is marked NON_COMPLIANT but keeps its approval status. Its next update must already conform to the new schema.

ZK
Zhemal Khamidun — CPO at Alpina Digital, product manager of AlpinaGPT. Building AI products since 2019. Hamidun News is a pet project that grew into a production aggregator with 6,000+ readers.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
What do you think?
Loading comments…