AWS Agent Registry.

Every AgentCore tip so far has been about building a thing — a runtime, a memory, a gateway, a payment. AWS Agent Registry (preview) is the opposite problem: once your org has built fifty MCP servers, twenty agents, and a pile of skills, how does anyone — human or agent — find them? It's a fully managed, org-wide catalog that makes agents, tools, and resources discoverable through governed, searchable records.

01The problem it actually solves

As organizations scale their use of agents and tools, discovery becomes the bottleneck. Teams build MCP servers, deploy agents, and write specialized tools — but without a central catalog those resources stay siloed and hard to find. The result is duplication and technical debt: teams rebuild things that already exist, simply because they couldn't discover them.

AWS Agent Registry is a fully managed discovery service that fixes this with a single searchable catalog. Publishers register their resources; curators approve the ones that meet the org's bar; and consumers — people in an IDE, or agents over MCP — search by natural language or exact name and get back only the approved, vetted records.

02Two resources, four resource types

The model is small. There are exactly two core resources. A registry is a catalog you create in your account: a name (≤ 64 chars), a description, an inbound authorization config (IAM or JWT), and an approval setting. You can run one org-wide registry or split by resource type, by environment (prod / QA / dev), or by team. A registry record is the metadata for one published resource — a name (≤ 255 chars), an optional description (1–4,096 chars), a version, a type, and type-specific descriptor content.

Records come in four types, and the Registry validates the structured ones against their protocol schemas:

03The record lifecycle

A record moves through an explicit set of states, and only one of them is discoverable:

Reconstruction · not a recording of a real run

You CreateRegistryRecord (status CREATING), it settles to DRAFT where the publisher iterates freely, then SubmitRegistryRecordForApproval moves it on. What happens next depends on the registry's auto-approval setting: with auto-approval off, the record goes to PENDING_APPROVAL and waits for a curator; with it on, it jumps straight to APPROVED. A curator can also reject (with feedback the publisher acts on and resubmits) or deprecate an approved record to pull it from discovery. The one rule worth tattooing on: only APPROVED records are ever returned by search or the MCP endpoint — Draft, Pending, Rejected, and Deprecated records are invisible to consumers.

04Hybrid search, and why your descriptions matter

SearchRegistryRecords runs two searches in parallel against the same indexed records and merges them. Semantic search turns your query into a vector and finds conceptually related records even when the words don't match — "book a flight" can surface a record named travel-reservation-service. Keyword search matches exact text, which is what you want for weather-api-v2 or a precise name lookup.

Both always run; results are ranked by a weighted combination of the two. Within keyword search, the record name has the strongest influence, followed by description and descriptor content (which contribute equally). That makes discoverability partly an authoring problem: write names that describe what the resource does, and descriptions in natural language explaining the problem it solves — terse technical labels rank worse. The request itself is small: searchQuery (1–256 chars), exactly one registry in registryIds, and an optional maxResults (1–20, default 10).

05Filters are separate from the query — keep them that way

For attribute constraints, use metadata filters, not prose. Filters support the operators $eq, $ne, $in and the logical $and / $or, over three fields: name, descriptorType, and version.

Filters are applied to both the semantic and keyword passes before scoring, so they shrink the candidate set rather than trimming ranked output. The docs are explicit about an anti-pattern: don't stuff filter-like constraints into the query text. "Find all MCP servers for weather forecasts" sends the whole sentence through semantic search and surfaces conceptually-related-but-wrong records. Put the topic in searchQuery ("weather forecasts") and the constraint in a filter (descriptorType = MCP).

06MCP-native discovery, plus two ways to authorize

Each registry exposes an MCP-compatible endpoint following the 2025-11-25 spec at https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp. It carries exactly one tool, search_registry_records, so any MCP client — Kiro, Claude, a custom agent — can discover org resources without touching the AWS SDK. Authorization for search and MCP invoke is set at registry creation and comes in two flavours:

• IAM — simplest for teams already in AWS; console search is supported. (bedrock-agentcore data plane: search_registry_records.)
• JWT — bring Cognito, Okta, Entra ID, or any OAuth 2.0 IdP. Consumers use corporate credentials; the MCP endpoint supports bearer tokens, pre-registered clients, and dynamic client registration. JWT registries have no console search — use an HTTP client or the MCP endpoint.

Two things that don't change after creation: the auth type (IAM vs JWT) and the JWT discovery URL. And regardless of search auth, control-plane operations always use IAM — creating and managing registries and records is never JWT-gated.

07Limits worth knowing

• Preview. APIs, fields, and shapes may change before GA — treat names and schemas as a snapshot.
• One registry per search. registryIds takes exactly one ARN/ID; searchQuery is 1–256 chars; maxResults is 1–20 (default 10).
• Only APPROVED is discoverable. Search and the MCP endpoint never return Draft, Pending, Rejected, or Deprecated records.
• Eventual consistency. After approval a record usually indexes in seconds, but can take a few minutes — retry with backoff, and use GetRegistryRecord (always current) to confirm status.
• Immutable at creation: the inbound auth type (IAM vs JWT) and the JWT discovery URL can't be changed later. A registry runs one inbound auth type at a time.
• Two service namespaces: management calls (CreateRegistry, CreateRegistryRecord, SubmitRegistryRecordForApproval, UpdateRegistryRecordStatus) use bedrock-agentcore-control; search (SearchRegistryRecords, InvokeRegistryMcp) uses bedrock-agentcore.

08Try it in five minutes

The IAM + auto-approval path is the fastest way to see the whole loop:

• Create a registry with IAM auth and auto-approval on: create-registry --name "MyFirstRegistry" --description "…". Wait for status READY.
• Add a record: create-registry-record --registry-id <id> --name "WeatherServer" --descriptor-type MCP --descriptors '{…}' --record-version "1.0". It lands in DRAFT.
• Submit it: submit-registry-record-for-approval --registry-id <id> --record-id <id>. With auto-approval on, it goes straight to APPROVED.
• Search it: search-registry-records --search-query "weather" --registry-ids <registryARN>. Give the index a few seconds; retry if it's not there yet.

Wire the EventBridge notification (fired on submit-for-approval) into Lambda, SNS, SQS, or Step Functions when you want manual approval to ride your existing review pipeline — the pipeline just calls UpdateRegistryRecordStatus when its checks pass. Every API call is logged to CloudTrail.