---
title: "AWS Agent Registry — the org-wide catalog where agents and MCP servers get found"
date: 2026-06-09
service: "Amazon Bedrock AgentCore"
component: "Registry"
tags: [agentcore, agent-registry, discovery, catalog, mcp, a2a, skills, hybrid-search, semantic-search, approval-workflow, curation, registry-record, jwt, iam, eventbridge, preview]
source: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html
verified_on: 2026-06-09
url: https://vanemmerik.ai/aws-ai/2026-06-09.html
---

# AWS Bedrock & AgentCore · Tip of the Day · 2026-06-09

## AWS Agent Registry — when nobody can find the tools you already built

Every AgentCore tip so far has been about *building* a thing — a runtime, a memory, a gateway, a payment. **AWS Agent Registry** (preview) is about 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? The Registry is a fully managed, org-wide catalog that makes agents, tools, and resources discoverable through governed, searchable records.

    aws bedrock-agentcore search-registry-records \
        --search-query "extract structured data from PDFs" \
        --registry-ids "<registryARN>" \
        --region us-east-1

≈ 8 min read · Amazon Bedrock AgentCore · Registry

## 01 · The 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.

> **The shift:** the Registry isn't a runtime — it stores no code and runs nothing. It's a *metadata catalog* with governance and search bolted on, so the things you've already deployed elsewhere stop being invisible.

## 02 · Two resources, four resource types

The model is small. There are exactly two core resources:

- A **registry** is a catalog you create in your account. It has 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. It has 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:

| Type | What it holds | Validated against |
| --- | --- | --- |
| **MCP** | A server definition plus tool definitions (inputs, outputs, examples) | MCP protocol schema |
| **Agent** | An A2A *agent card* describing capabilities, skills, and interface | A2A protocol schema |
| **Skills** | Markdown documentation plus an optional structured definition | (none — descriptor + docs) |
| **Custom** | Any valid JSON for resources that don't fit the above (APIs, Lambdas, knowledge bases, databases) | (your own schema) |

## 03 · The record lifecycle

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

`CREATING → DRAFT → PENDING_APPROVAL → APPROVED`

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*, the record 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 out of 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.

## 04 · Hybrid 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).

## 05 · Filters 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`.

    {"$and": [
      {"descriptorType": {"$eq": "MCP"}},
      {"version": {"$eq": "1.0"}}
    ]}

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`).

## 06 · MCP-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.

## Limits 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 (`CreateRegistry`, `CreateRegistryRecord`, `SubmitRegistryRecordForApproval`, `UpdateRegistryRecordStatus`) is `bedrock-agentcore-control`; search (`SearchRegistryRecords`, `InvokeRegistryMcp`) is `bedrock-agentcore`.

## Try 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: `aws bedrock-agentcore-control 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**.

---

**Verified against the official AWS docs on 2026-06-09.** Sources: [AWS Agent Registry overview](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry.html), [Concepts and terminology](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-concepts.html), [Key capabilities](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-key-capabilities.html), [Get started](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-get-started.html), [Search for registry records](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-search-records.html), [Using the Registry MCP endpoint](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-mcp-endpoint.html). If the docs change, this tip is a snapshot of that day — check the sources for current behaviour.

---

*This page — research, writing, verification, and deployment — was built by Claude Cowork. The tip was generated this morning, cross-checked against the official AWS docs by an independent verification pass, and published to Cloudflare R2 on a schedule. A daily experiment by Monty van Emmerik · [vanemmerik.ai](https://vanemmerik.ai/).*