# AWS Agent Registry: Discover and manage agents, tools, and resources
AWS Agent Registry: Centrally catalog and discover AI Resources

**Topics**
+ [

## What is AWS Agent Registry?
](#registry-what-is)
+ [

## Why use AWS Agent Registry?
](#registry-why-use)
+ [

## How it works
](#registry-how-it-works)
+ [

## Accessing AWS Agent Registry
](#registry-accessing)
+ [

## Related services
](#registry-related-services)
+ [

# Key capabilities
](registry-key-capabilities.md)
+ [

# Concepts and terminology
](registry-concepts.md)
+ [

# Prerequisites
](registry-prerequisites.md)
+ [

# Sample use cases
](registry-use-cases.md)
+ [

# Get started with AWS Agent Registry
](registry-get-started.md)
+ [

# Creating and managing registries
](registry-managing-registries.md)
+ [

# Creating and managing registry records
](registry-managing-records.md)
+ [

# Curating the registry
](registry-curating.md)
+ [

# Searching the registry
](registry-searching.md)
+ [

# Notifications (Amazon EventBridge)
](registry-eventbridge.md)
+ [

# Log Registry API calls with AWS CloudTrail
](registry-cloudtrail.md)
+ [

# IAM Permissions
](registry-iam-permissions.md)
+ [

# Troubleshooting
](registry-troubleshooting.md)

## What is AWS Agent Registry?


 AWS Agent Registry is a fully managed discovery service that provides a centralized catalog for organizing, curating, and discovering resources across your organization. With AWS Agent Registry, you can publish MCP servers, tools, agents, agent skills, and custom resources into a searchable registry, control access through an approval workflow, and enable both human users and AI agents to discover the right tools and agents using semantic and keyword search.

## Why use AWS Agent Registry?


As organizations scale their use of AI agents and tools, discovering the right resource becomes increasingly difficult. Teams build MCP servers, deploy agents, and create specialized tools — but without a central catalog, these resources remain siloed and hard to find. This also causes duplication of effort and increased technical debt as teams re-build resources that already exist simply because they are unable to discover them. AWS Agent Registry solves this by providing:
+  **Centralized discovery** – A single place to find all published resources across your organization, searchable by both humans and agents.
+  **Governance and curation** – An approval workflow that ensures only records meeting your organization’s criteria for security, compliance, and quality are discoverable. Administrators control what builders in their organization can discover and use, and can remove resources being discoverable at any time.
+  **Flexible resource types** – Register MCP servers, agents, skills, and any custom resource. AWS Agent Registry validates MCP and agent records against their respective protocol schemas, and supports custom metadata for all resource types.
+  **Hybrid search** – Combines semantic understanding with keyword matching so that both natural language queries and exact name lookups return relevant results.
+  **MCP-native access** – The Registry is available at a remote MCP endpoint that lets MCP-compatible clients interact with the registry directly using the Model Context Protocol.
+  **Flexible authorization** – Choose between AWS IAM credentials or JSON Web Tokens (JWT) from your corporate identity provider to control who can search and invoke the registry’s MCP endpoint.

## How it works


 AWS Agent Registry is organized around two core resources:
+  **Registries** – A registry is a catalog that you create in your AWS account. Each registry has its own Name, Description, Authorization configuration (IAM or JWT), approval settings, and set of records. You can create a single organization wide registry, create registries organized by resource type (such as an agent registry, MCP server registry, or skill registry), by stage of development (production, QA, development), by team or business unit — whatever setup works best for you.
+  **Registry records** – A record represents an individual resource published into a registry. Each record captures key metadata that describes the underlying resource — providing information about what it is, what it does, and how it can be found.

### Typical workflow


1.  **Create a registry** – An administrator creates a registry and configures authorization and approval settings.

1.  **Publish records** – A publisher creates registry records describing their MCP servers, agents, or tools, and submits them for approval.

1.  **Curate the registry** – A curator (or the administrator) reviews records pending approval and approves or rejects them; They also deprecate records no longer in use.

1.  **Discover resources** – Consumers/End-Users search for resources relevant to their needs in the registry.

You can learn more about how to configure IAM Permissions specific to each Persona in [Key Personas](registry-concepts.md#registry-concept-personas).

## Accessing AWS Agent Registry


You can interact with AWS Agent Registry by directly invoking the Registry service’s public APIs via the AWS CLI or AWS SDKs, or by invoking the registry’s MCP endpoint with any valid MCP-compatible client.

## Related services

+  [Host agent or tools with Amazon Bedrock AgentCore Runtime](agents-tools-runtime.md) – Deploy and run the agents and MCP servers that you register.
+  [Amazon Bedrock AgentCore Gateway: Securely connect tools and other resources to your Gateway](gateway.md) – Convert APIs and Lambda functions into MCP-compatible tools that can be registered.
+  [Provide identity and credential management for agent applications with Amazon Bedrock AgentCore Identity](identity.md) – Manage identity and credential providers used for JWT-based registry authorization.
+  [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) – Receive notifications when registry records are submitted for approval.
+  [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/) – Log and monitor all API calls made to AWS Agent Registry.

# Key capabilities
Key capabilities

## Flexible resource types


Add records of any type with a flexible structure and custom metadata. AWS Agent Registry directly supports MCP servers, agents, and skills. For MCP Server and Agent records, AWS Agent Registry validates your definitions against the MCP and A2A protocol schemas respectively, ensuring correctness before records are published. You can also register any kind of custom resource — such as agents conforming to protocols other than A2A, APIs, Lambda functions, knowledge bases, or databases — by defining your own metadata schema. This means AWS Agent Registry can serve as a unified catalog for all discoverable resources in your organization, regardless of the underlying technology.

## Hybrid search


 AWS Agent Registry combines semantic search with keyword matching to deliver relevant results for any type of query. When you search using natural language — such as "find a tool that can book flights" — semantic search understands the intent and finds conceptually relevant records, even if those exact words don’t appear in the record metadata. When you search using exact terms — such as "weather-api-v2" — keyword search matches the precise text. Both search modalities run simultaneously on every query, with results ranked by a weighted combination of relevance scores. You can further narrow results using metadata filters on fields such as record name, record types, and version.

## Governance and curation


 AWS Agent Registry gives administrators control over what builders in their organization can discover and use. Administrators can ensure that only records meeting internally defined criteria for security, metadata richness, compliance, safety, and any other organizational standards are approved and made visible in search results. When a curator needs to remove a resource from discovery — whether due to a newly discovered issue, a deprecation, or a policy change — they can deprecate existing approved records, ensuring those resources can no longer be found by builders. For development environments where manual review isn’t needed, administrators can enable auto-approval so that submitted records become discoverable immediately.

## Amazon EventBridge notifications


 AWS Agent Registry sends events to Amazon EventBridge when a record is submitted for approval. You can use these events to trigger automated review workflows, send alerts to curators via email or messaging, or integrate with ticketing systems and approval pipelines. Events are delivered to the default Amazon EventBridge bus in your account and Region, and can be routed to any Amazon EventBridge-supported target including AWS Lambda, Amazon Simple Notification Service, Amazon Simple Queue Service, and AWS Step Functions.

## Integrate with existing approval workflows


Many organizations already have established mechanisms for reviewing and approving resources — processes that include security reviews, compliance checks, safety assessments, and other evaluations. AWS Agent Registry can be integrated with these existing workflows through Amazon EventBridge and the UpdateRegistryRecordStatus API. When a publisher submits a record for approval, AWS Agent Registry sends an Amazon EventBridge notification that can trigger your existing review pipeline. Once your pipeline completes its checks, it calls the UpdateRegistryRecordStatus API to approve or reject the record. By integrating AWS Agent Registry with your existing review pipeline, you can curate the registry directly from your existing approval process without changing how your organization reviews resources.

## Discovering Resources using the Registry’s MCP Server


Each registry exposes an MCP-compatible endpoint that MCP clients can connect to directly using the Model Context Protocol. This allows agents and tools built on MCP to discover and interact with registered resources using standard MCP protocol communication — without needing to use the AWS SDK or integrate with AWS-specific APIs. Any valid MCP-compatible client can connect to the registry’s MCP endpoint and search for available resources in the registry. This enables developers using AI IDEs to easily discover existing agents and tools in the organization and leverage them as they build new agentic workflows.

## Flexible Authorization


 AWS Agent Registry supports two authorization methods for the search and MCP invoke operations, so you can choose the approach that fits your organization:
+  ** AWS IAM** — Use your existing IAM credentials for authorization. This is the simplest option for teams already working within AWS, requiring no additional configuration.
+  **JSON Web Tokens (JWT)** — Integrate the registry with your organization’s existing identity provider — such as Amazon Cognito, Okta, Microsoft Azure AD, or any OAuth 2.0-compatible provider. Your developers and agents can search the registry and invoke the MCP endpoint using their existing corporate credentials, without needing individual IAM access.

Control plane operations (creating, updating, and managing registries and records) always use IAM authorization regardless of the registry’s search authorization setting.

## Record synchronization


 AWS Agent Registry can synchronize record metadata from external sources, keeping your registry up to date. When you configure a record with a URL pointing to an external MCP server, AWS Agent Registry fetches the latest server (Details like Name, Description) and tool metadata (Tool Names, Tool Descriptions) from that URL and updates the record. Synchronization can be used both to create the record the first time by pulling the metadata from the URL provided, or update an existing record with fresh metadata due to changes in the underlying resource. When Synchronization is used for an existing record, a new revision for the existing record is created. Synchronization supports both OAuth and IAM credential providers for authorization.

## CloudTrail integration


 AWS Agent Registry control plane API calls are logged in AWS CloudTrail, providing a complete audit trail of who did what and when. Control plane operations are logged as management events by default.

# Concepts and terminology
Concepts and terminology

## Registry


A registry is a centralized catalog that you create in your AWS account to organize and manage resources. Each registry has a name, a description, an authorization configuration that controls how consumers access the search and MCP APIs, and an approval configuration that determines whether records require manual review before becoming discoverable.

How you organize your registries depends on your needs — for example, dedicated registries for different resource types (an agent registry, an MCP server registry, a skill registry), registries for different stages of development (production, QA, development), independent registries for different teams or business units, or a single registry for your entire organization.

## Registry record


A registry record represents the metadata for an individual resource published into a registry. Each record captures key metadata that describes the underlying resource — providing information about what it is, what it does, and how it can be found. Records have a name, optional description, version, type and resource-type-specific metadata.

## Resource types


 **MCP servers** — Model Context Protocol (MCP) servers provide tools that AI agents can discover and invoke. An MCP server record contains a server definition describing the server’s configuration and tool definitions for all the tools the server provides, including their input parameters and output formats. AWS Agent Registry validates MCP server records against the [MCP protocol schema](https://modelcontextprotocol.io/docs/getting-started/intro) to ensure correctness.

 **Agents** — Agents are autonomous programs that can reason, plan, and take actions to accomplish tasks. An agent record contains an agent card that describes the agent’s capabilities, skills, and communication interface per the A2A [(Agent-to-Agent)](https://a2a-protocol.org/latest/) protocol specification. AWS Agent Registry validates agent records against the A2A protocol schema to ensure correctness.

 **Skills** — Skills are reusable capabilities that can be shared across agents. A skill record contains basic descriptor metadata like Name, Description, optional access information like Package or Repository details, and optional markdown documentation describing what the skill does and how to use it.

 **Custom resources** — For resources that don’t fit the standard types above you can define your own metadata schema using any valid JSON structure.

## Credential provider


When you configure a registry record to synchronize metadata from an external source (outbound authorization) AWS Agent Registry needs credentials to access that source. A credential provider stores the authorization details — either OAuth credentials or an IAM role — that AWS Agent Registry uses to invoke the external resource’s endpoint during synchronization. You reference a credential provider by its ARN when configuring synchronization on a record. For more information, see [Manage credential providers](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html).

 **Registry Authorization is of 2 types -** 

1.  **Inbound Authorization** : This configuration enables Registry Administrators to control how Consumers can search the Registry (via AWS CLI, AWS SDK or by Invoking the MCP Endpoint). Registry supports IAM based and JWT based inbound Authorization. Registry Administrators specify this as part of the workflow for creating a Registry.

1.  **Outbound Authorization:** As part of Synchronizing MCP and A2A Records with their remote endpoints (for records where synchronization is setup), the registry requires outbound credentials to invoke the remote resource at the specified endpoint and retrieve metadata. Publishers provide these credentials as part of setting up the synchronization job for a particular registry record.

## Key Personas


Personas that use the Registry can vary from organization to organization. However, we have seen the following general personas that interact with the Registry, found commonly across organizations.

 **Administrator**   
The Administrator is the owner of the registry infrastructure. They are responsible for creating and configuring registries within the AWS account, deciding how each registry is organized (by team, environment, or resource type), and choosing the authorization method (IAM or JWT) that determines how consumers access the registry. Administrators set up the approval workflow — deciding whether records require manual review or are auto-approved — and configure Amazon EventBridge integrations to connect the registry to the organization’s existing notification and review systems. They manage IAM permissions to control which publishers, curators, and consumers can access each registry. Because they are the admin, they also have full access to create, update, and delete records, and can approve, reject, or deprecate records when needed.

 **Publisher**   
The Publisher is a builder within the organization who has created a resource — an MCP server, an agent, a skill, or some other tool — and wants to make it discoverable to others. Publishers create registry records that describe their resources, providing the metadata, definitions, and version information that will help others find and understand what the resource does. They iterate on records in Draft status, refining descriptions and schemas until the record is ready, then submit it for approval. If a record is rejected, the publisher reviews the curator’s feedback, makes the necessary changes, and resubmits. Publishers can also configure URL-based synchronization so that their records stay in sync with live MCP servers without manual updates.

 **Curator / Approver**   
The Curator is the quality gatekeeper of the registry, and can often be the Administrator of the Registry as well. They are responsible for reviewing records that publishers have submitted for approval, evaluating each record against the organization’s standards for security, compliance, metadata completeness, and any other criteria the organization defines. Curators approve records that meet these standards — making them visible in search results and through the MCP endpoint — and reject records that don’t, providing clear feedback on what needs to be fixed. When a resource is decommissioned, has known issues, or is superseded by a newer version, the curator deprecates the record to remove it from discovery. Curators ensure that the registry remains a trusted, high-quality catalog that builders across the organization can rely on.

 **Consumer**   
The Consumer is anyone — human or agent — who needs to find and use resources. Consumers search the registry using natural language queries or keyword lookups to discover MCP servers, agents, skills, and other resources that have been approved and published. They can also connect to the registry’s MCP endpoint using any MCP-compatible client to discover available tools programmatically. Consumers only see approved records, so they can trust that everything they find in the registry has been reviewed and meets the organization’s quality standards. Consumers may authorize via IAM credentials or JWT tokens from a corporate identity provider, depending on how the registry is configured.

# Prerequisites
Prerequisites

Before you use AWS Agent Registry, complete the following prerequisites.

## AWS account and credentials


You need an AWS account with credentials configured. To configure credentials, install and use the AWS Command Line Interface by following the steps at [Getting started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).

```
# Verify installation
aws --version  # Should show version 2.
```

## Python and AWS SDK


To access your AWS credentials and configure them for use with SDKs, follow the steps at [Using IAM Identity Center to authenticate AWS SDK and Tools](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html) . If you plan to use the AWS Python SDK (Boto3) to interact with AWS Agent Registry programmatically:

1. Install **Python 3.10\$1**.

1. Install the AWS SDK: `pip install boto3` 

1. Verify your credentials are configured: `aws sts get-caller-identity` 

Please refer to [AWS Builder Tools](https://builder.aws.com/build/tools) for more information on how to setup and use AWS SDK.

## IAM permissions


Set up IAM permissions based on the persona that matches your role. The full list of IAM Permissions for Registry can be found in [IAM Permissions](registry-iam-permissions.md).

### Administrator permissions


For administrators who manage the full lifecycle of registries, records, and approve/reject/deprecate records:

```
{
"Version": "2012-10-17",		 	 	 
    "Statement":
    [
        {
            "Sid": "AllowCreatingAndListingRegistries",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:CreateRegistry",
                "bedrock-agentcore:ListRegistries"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:*"
            ]
        },
        {
            "Sid": "AllowGetUpdateDeleteRegistry",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistry",
                "bedrock-agentcore:UpdateRegistry",
                "bedrock-agentcore:DeleteRegistry"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Sid": "AllowCreatingAndListingRecords",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:CreateRegistryRecord",
                "bedrock-agentcore:ListRegistryRecords"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Sid": "AllowRecordLevelOperations",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistryRecord",
                "bedrock-agentcore:UpdateRegistryRecord",
                "bedrock-agentcore:DeleteRegistryRecord",
                "bedrock-agentcore:SubmitRegistryRecordForApproval"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*/record/*"
            ]
        },
        {
            "Sid": "AllowApproveRejectDeprecateRecords",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:UpdateRegistryRecordStatus"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*/record/*"
            ]
        },
        {
            "Sid": "AdditionalPermissionForRegistryManagedWorkloadIdentity",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:*WorkloadIdentity"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:workload-identity-directory/default/*"
            ]
        }
    ]
}
```

### Curator / Approver permissions


For curators who review and approve/reject records but don’t perform administrative operations:

```
{
"Version": "2012-10-17",		 	 	 
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:ListRegistries"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistry"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:ListRegistryRecords"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistryRecord"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*/record/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:UpdateRegistryRecordStatus"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*/record/*"
            ]
        }
    ]
}
```

### Publisher permissions


For publishers who submit MCP servers, agents, or other resources to the registry:

```
{
"Version": "2012-10-17",		 	 	 
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:ListRegistries"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistry"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:CreateRegistryRecord",
                "bedrock-agentcore:ListRegistryRecords"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistryRecord",
                "bedrock-agentcore:UpdateRegistryRecord",
                "bedrock-agentcore:DeleteRegistryRecord",
                "bedrock-agentcore:SubmitRegistryRecordForApproval"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*/record/*"
            ]
        },
        {
            "Sid": "AllowWorkloadIdentityForSynchronization",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetWorkloadAccessToken"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:workload-identity-directory/*"
            ]
        },
        {
            "Sid": "AllowGetResourceOauth2TokenForOauthBasedSynchronization",
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetResourceOauth2Token"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:token-vault/*"
            ]
        },
        {
            "Sid": "AllowPassRoleForIamBasedSynchronization",
            "Effect": "Allow",
            "Action":
            [
                "iam:PassRole"
            ],
            "Resource":
            [
                "arn:aws:iam::<account>:role/<your-sync-role-name>"
            ],
            "Condition":
            {
                "StringEquals":
                {
                    "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
                },
                "StringLike":
                {
                    "iam:AssociatedResourceARN": "arn:aws:bedrock-agentcore:<region>:<account>:registry/*/record/*"
                }
            }
        }
    ]
}
```

### Consumer permissions


For consumers who search for and use approved resources:

```
{
"Version": "2012-10-17",		 	 	 
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:ListRegistries"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetRegistry"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:SearchRegistryRecords",
                "bedrock-agentcore:InvokeRegistryMcp"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:registry/*"
            ]
        }
    ]
}
```

For example IAM policies, see [Identity and access management for Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam.html).

## (Optional) Identity provider for JWT authorization


If you plan to use JWT authorization for inbound identity (to enable consumers to search the registry using Non-IAM identities), set up Amazon Cognito or your own identity provider before creating the registry:

1.  **Create a Cognito User Pool** (or use your existing identity provider)

1.  **Register an App Client** and note the Client ID

1.  **Create a test user** with a username and password

For detailed instructions, see [Configure inbound JWT authorizer](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/inbound-jwt-authorizer.html).

# Sample use cases
Sample use cases

Below you will find some examples use cases where registry can be used.

## Discover Agents or Tools for building an internal workflow


A builder is creating an internal HR workflow that generates a report of employee time-off balances. The workflow needs access to an employee information service, a PTO tracking service, and a document generation service like SharePoint. Rather than asking around or searching through internal wikis, the builder searches the AWS Agent Registry for services matching their needs. They find all three services registered with their connection details and tool schemas, and use this information to construct the workflow — reducing what would have been days of discovery into minutes.

## Add a new capability to a customer-facing agent


A builder maintains an external customer service agent that handles order inquiries. They need to add a new use case: helping customers track delayed package deliveries. The agent already has access to customer information and order history services, but needs a delivery tracking service. The builder searches the registry, finds a registered delivery tracking service with the right capabilities, attaches it to their Gateway, and updates the agent’s policy to allow calls to this new service — all without needing to know which team built the delivery service or how to contact them.

## Manage agent sprawl across teams


An administrator reviewing the registry notices that a new team is building a travel booking agent with capabilities very similar to an existing travel planning agent registered by another team. By discovering this overlap through the registry, the administrator connects the two teams. Instead of duplicating effort, the existing agent is updated with the additional capabilities, and the organization avoids maintaining two agents that do essentially the same thing.

## Share reusable skills across agents


A team has developed a skill for extracting structured data from PDF documents. They received positive feedback about the effectiveness of this skill, and were asked to broadly share this skill across the organization to boost collective productivity. Instead of reaching out to each team independently, they publish the skill to the registry with detailed markdown documentation and a structured definition. Other agent builders discover the skill through search and integrate it into their own agents, accelerating development across the organization.

## Enforce quality standards through curation


A builder submits a new MCP server record to the registry. The submission triggers an Amazon EventBridge notification that kicks off the organization’s standard review pipeline. The automated pipeline checks that the server definition includes complete tool descriptions, that input schemas are properly defined, and that the server meets the organization’s security requirements. The review finds that several tool descriptions are missing required fields. The curator rejects the record with a detailed reason, and the builder receives feedback on what to fix before resubmitting.

## Keep registry records synchronized with live servers


A team deploys MCP servers on AgentCore Runtime whose tool definitions evolve as new features are added. Rather than manually updating registry records every time a tool changes, they configure URL-based synchronization on each record and simply come to the registry periodically to trigger synchronization. When they do so, AWS Agent Registry fetches the latest server and tool metadata from the MCP server’s endpoint, keeping the registry accurate.

# Get started with AWS Agent Registry
Get started with AWS Agent Registry

In this guide, you’ll create your first registry, add a record, approve it, and search for it.

## Prerequisites


Complete the steps in [Prerequisites](registry-prerequisites.md).

## Step 1: Create a registry


Create a registry with IAM authorization and manual approval.

### Console


 **To Create a Registry with IAM based Auth** 

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry**.

1. In the **Registries** section, choose **Create registry**.

1. In the **Registry details** section, for **Name** , enter a name for your registry. The name must start with an alphanumeric character. Valid characters are a–z, A–Z, 0–9, `_` (underscore), `-` (hyphen), `.` (period), and `/` (forward slash). The name can have up to 64 characters.

1. (Optional) Choose **Additional details** to expand the section, and then for **Description** , enter a description to help identify this registry.

1. In the **Search API Authorization** section, for **Auth type** , choose **Use IAM Authorization** . Note - This is Inbound Authorization

1. In the **Record approval** section, turn on or turn off **Auto-approval** :
   + When **Auto-approval** is on, when you submit a record for approval, the record moves directly to **Approved** status and becomes visible in search results shortly after.
   + When **Auto-approval** is off, when you submit a record for approval, the record moves to **Pending approval** status and requires a curator to review and approve it before it’s published.

1. Choose **Create registry**.

 **To Create a Registry with JWT based Auth** Identity provider authorization uses JSON Web Tokens (JWT) to control access to the registry’s search API. You can use Amazon Cognito to quickly set up authorization, or bring your own identity provider to enable OAuth 2.0.

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry**.

1. In the **Registries** section, choose **Create registry**.

1. In the **Registry details** section, for **Name** , enter a name for your registry. The name must start with an alphanumeric character. Valid characters are a–z, A–Z, 0–9, `_` (underscore), `-` (hyphen), `.` (period), and `/` (forward slash). The name can have up to 64 characters.

1. (Optional) Choose **Additional details** to expand the section, and then for **Description** , enter a description to help identify this registry.

1. In the **Search API Authorization** section, for **Auth type** , choose **Use JSON Web Tokens (JWT)** . Note - This is Inbound Authorization

1. For **JWT schema configuration** , choose one of the following options:

   1.  **Quick create configurations with Cognito (recommended)** – AWS Agent Registry creates the authorization configurations on your behalf using Amazon Cognito as the identity provider. No additional configuration is required.

   1.  **Use existing Identity provider configurations** – Bring your own identity provider to enable OAuth 2.0. If you choose this option, complete the following steps:

      1. For **Discovery URL** , enter the discovery URL from your identity provider. AWS Agent Registry uses this URL to automatically fetch the login, token, and verification settings for your provider. You can find this URL in your identity provider’s dashboard or documentation (for example, `https://cognito-identity.amazonaws.com/.well-known/openid-configuration` ).

         Note: Discovery URL cannot be changed after the Registry is created

      1. (Optional) Under **JWT authorization configuration** , select **Allowed audiences** to provide a list of permitted audiences that AWS Agent Registry validates against the `aud` claim in the JWT token. An audience claim ( `aud` ) in OAuth 2.0 specifies which resource server (API) the token is intended for. This ensures the token is the correct recipient before processing the request, preventing a token from being reused at a different API it was not issued for.

      1. (Optional) Select **Allowed clients** to provide a list of permitted client identifiers that AWS Agent Registry validates against the `client_id` claim in the JWT token. A `client_id` is a public, unique identifier for an application that is requesting access tokens to access the registry’s search API. If you enable this option, enter one or more client IDs in the **Clients** field, and then choose **Add client** to add additional clients.

      1. (Optional) Select **Allowed scopes** to provide a list of permitted permissions, defined as scopes. If configured, at least one scope value in the incoming token must match one of the configured values. Scopes act as permissions to limit what an application can do.

      1. (Optional) Select **Custom claims** to provide a set of rules that match specific claims in the incoming token against predefined values. For each rule, specify the claim name, the value type ( **STRING** or **STRING\$1ARRAY** ), and the required match value.

1. In the **Record approval** section, turn on or turn off **Auto-approval** :

   1. When **Auto-approval** is on, when you submit a record for approval, the record moves directly to **Approved** status and becomes immediately visible in search results.

   1. When **Auto-approval** is off, when you submit a record for approval, the record moves to **Pending approval** status and requires a registry admin to review and approve it before it’s published.

1. Choose **Create registry**.

**Note**  
\$1 At least one **JWT authorization configuration** field is required: allowed audiences, allowed clients, allowed scopes, or custom claims. If you configure more than one, AWS Agent Registry verifies all of them. \$1 The discovery URL cannot be changed after the registry is created. \$1 The authorization type (IAM or JWT) cannot be changed after the registry is created. \$1 A registry supports only one form of inbound authorization type at a time — IAM SigV4 or JWT Bearer Token. You cannot use both simultaneously. Search via IAM is only supported via IAM-based registry; and search via Oauth is only supported via Oauth based registry.

After creating the registry, the console navigates to the registry details page. The registry status is initially **Creating** . AWS Agent Registry assigns the registry an ARN, which you can find in the **Registry details** section. The registry status changes to **Ready** after provisioning is complete. You can add records to the registry when its status is **Ready**.

### AWS CLI


```
aws bedrock-agentcore-control create-registry \
  --name "MyFirstRegistry" \
  --description "My first Agent Registry" \
  --region us-east-1
```

The registry status starts as CREATING and transitions to READY when provisioning completes.

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_registry(
    name='my-agent-registry',
    description='My first Agent Registry'
)
print(response['registryArn'])
```

## Step 2: Add a registry record


Create a record for an MCP server in your registry.

### Console


A registry record represents an agent, tool, skill, or custom resource.

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry** , and then choose the name of the registry where you want to add a record.

1. In the **Registry records** section, choose **Create record**.

1. In the **Record details** section, for **Name** , enter a name for the record. The name must start with an alphanumeric character. Valid characters are a–z, A–Z, 0–9, `_` (underscore), `-` (hyphen), `.` (period), and `/` (forward slash). The name can have up to 255 characters.

1. (Optional) For **Description** , enter a description for the record. The description can be 1 to 4,096 characters.

1. For **Record version** , enter a version identifier for the record (for example, `1.0.0` or `v2.1` ).

1. In the **Record type** section, choose the type that matches your resource:

   1.  **MCP** – Protocol designed for AI tool and agent communications. Handles context management and structured message formats. If you choose this type, complete the following steps:

      1. In the **MCP server definition** section, select a schema version from the **Schema version** dropdown (for example, `2025-12-11` ), and then enter [MCP registry](https://registry.modelcontextprotocol.io/) server.json in the **Your MCP server definition** editor. The definition must comply with the official MCP server schema for the selected version. To view the official schema as a reference, turn on **Show official schema**.

      1. (Optional) Select **Add tool definition** to add specific tools available on this server with their input parameters, outputs, and usage examples to enhance discoverability. If you select this option, select a schema version from the **Schema version** dropdown (for example, `2025-11-25` ), and then enter your tool definition in the **Your Tool definition** editor. To view the official tool schema as a reference, turn on **Show official schema**.

   1.  **Agent** – Protocol designed for secure agent-to-agent interactions. Enables distributed workflows and information exchange. If you choose this type, the schema version is `0.3` . Enter your agent card definition in the editor. To view the official schema as a reference, turn on **Show official schema**.

   1.  **Agent Skills** – Register agent skills with markdown documentation and an optional structured definition. If you choose this type, complete the following steps:

      1. For **Skill documentation** , enter the markdown documentation that describes this skill.

      1. (Optional) Select **Include skill definition** to add a structured definition. If you select this option, select a schema version from the **Schema version** dropdown, and then enter the skill definition as a JSON object in the editor.

   1.  **Custom** – Custom protocol implementation for specialized communication patterns. Define your own interface specification and integration requirements. If you choose this type, enter your custom definition as a JSON object in the editor.

1. Choose **Create record**.

**Note**  
If you wish to add a Server or Agent into the registry that does not conform to the standard MCP or A2A Protocol Schemas, use Custom record type to add such a resource into the registry.

After you choose Create record, AWS Agent Registry begins provisioning the record. The record status is initially Creating. When provisioning is complete, the status changes to Draft. To make the record available for others to discover, submit it for approval. For more information, see [Step 3: Submit the record for approval](#registry-get-started-step3).

### AWS CLI


```
aws bedrock-agentcore-control create-registry-record \
  --registry-id <registryId> \
  --name "WeatherServer" \
  --descriptor-type MCP \
  --descriptors '{"mcp": {"server": {"inlineContent": "{\"name\": \"weather/mcp-server\", \"description\": \"Weather data service\", \"version\": \"1.0.0\"}"}}}' \
  --record-version "1.0" \
  --region us-east-1
```

The record is created in CREATING status and transitions to DRAFT when processing completes. For more AWS CLI examples for creating records of other types, refer to the [Create and manage records](registry-create-manage-records.md) section.

### AWS SDK


```
import boto3
import json

client = boto3.client('bedrock-agentcore-control')

server_content = json.dumps({
    "name": "io.example/weather-server",
    "description": "A weather MCP server",
    "version": "1.0.0"
})

tools_content = json.dumps({
    "tools": [{
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "inputSchema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name"
                }
            },
            "required": ["location"]
        }
    }]
})

response = client.create_registry_record(
    registryId='<registryId>',
    name='my-mcp-server',
    descriptorType='MCP',
    descriptors={
        'mcp': {
            'server': {
                'schemaVersion': '2025-12-11',
                'inlineContent': server_content
            },
            'tools': {
                'protocolVersion': '2024-11-05',
                'inlineContent': tools_content
            }
        }
    }
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # CREATING
```

## Step 3: Submit the record for approval


### Console


Submitting a record for approval starts the review process that makes the record available for discovery. You can submit a record from the registry records table or from the record details page.

 **To submit a record for approval from the registry records table** 

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry** , and then choose the registry name.

1. In the **Registry records** section, select the record that you want to submit.

1. Choose **Update status** , and then choose **Submit for approval**.

 **To submit a record for approval from the record details page** 

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry** , and then choose the registry name.

1. In the **Registry records** section, choose the name of the record that you want to submit.

1. Choose **Update status** , and then choose **Submit for approval**.

After you submit a record for approval, the record status changes based on the registry’s approval setting:
+ If the registry has **Auto-approval** turned on, the record status changes directly to **Approved** and becomes visible in search results shortly after.
+ If the registry has **Auto-approval** turned off, the record status changes to **Pending approval** and requires a registry admin to review and approve it before it’s published.

### AWS CLI


```
aws bedrock-agentcore-control submit-registry-record-for-approval \
  --registry-id <registryId> \
  --record-id <recordId> \
  --region us-east-1
```

The record moves to PENDING\$1APPROVAL (or directly to APPROVED if auto-approval is enabled).

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.submit_registry_record_for_approval(
    registryId='<registryId>',
    recordId='<recordId>'
)
print(f"Record ARN: {response['recordArn']}")
print(f"Record ID: {response['recordId']}")
print(f"Status: {response['status']}")  # PENDING_APPROVAL or APPROVED
print(f"Updated At: {response['updatedAt']}")
```

## Step 4: Approve the record


### Console


 **To approve a record from the registry records table** 

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry** , and then choose the registry name.

1. In the **Registry records** section, select the record that you want to approve.

1. Choose **Update status** , and then choose **Approve**.

1. In the confirmation dialog, enter a reason for the status change.

1. Choose **Confirm** 

 **To approve a record from the record details page** 

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry** , and then choose the registry name.

1. In the **Registry records** section, choose the name of the record that you want to approve.

1. In record details page, Choose **Update status** , and then choose **Approve**.

1. In the confirmation dialog, enter a reason for the status change.

1. Choose **Confirm** 

### AWS CLI


```
aws bedrock-agentcore-control update-registry-record-status \
  --registry-id <registryId> \
  --record-id <recordId> \
  --status APPROVED \
  --status-reason "Reviewed and approved" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record_status(
    registryId='<registryId>',
    recordId='<recordId>',
    status='APPROVED',
    statusReason='Meets all requirements'
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # APPROVED
print(f"Reason: {response['statusReason']}")
```

## Step 5: Search the registry


### Console


You can search for approved records in a registry using semantic or keyword search to find agents, MCP servers, skills, and other resources. You can filter results by name, protocol, or version to narrow your search.

**Note**  
\$1 The console search feature is available only for registries that use **Use IAM** as the authorization type. \$1 If your registry uses JSON Web Tokens (JWT), you must call the search API directly using an HTTP client such as curl or Postman, with a valid JWT Bearer Token in the request header. The AWS CLI and AWS SDKs use IAM SigV4 signing and cannot be used with JWT-authorized registries. More details can be found [Search for registry records](registry-search-records.md).

 **To search for registry records** 

1. Open the AWS Agent Registry Page in [AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, choose **Registry** , and then choose the registry name.

1. Choose the **Search records** tab.

1. In the **Search approved records** field, enter your search query.

1. (Optional) To filter results by a specific property, choose the search field to expand the **Properties** menu, and then choose a filter: **Name** , **Descriptor type** , or **Version**.

1. Choose **Search**.

Search returns only records in **Approved** status. Records in other states such as Draft, Pending approval, Rejected, or Deprecated status don’t appear in search results.

### AWS CLI


```
aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registry-id>" \
  --region us-east-1
```

Your approved record should appear in the search results.

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore')

response = client.search_registry_records(
    registryIds=['arn:aws:bedrock-agentcore:us-east-1:<account>:registry/<registryId>'],
    searchQuery='weather forecast tool',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"Record: {record['name']} ({record['recordId']})")
    print(f"  Type: {record['descriptorType']}")
    print(f"  Status: {record['status']}")
    print(f"  Version: {record['version']}")
```

## What you’ve built

+ A **registry** with IAM authorization and manual approval
+ A **registry record** describing an MCP server
+ An **approved record** discoverable through search

## Next steps

+ Set up Amazon EventBridge notifications to automate your approval workflow
+ Add more records for your agents, servers, skills, and custom resources

# Creating and managing registries
Creating and managing registries

A registry is the top-level resource in AWS Agent Registry. Before you can publish records, you need to create a registry and configure its authorization and approval settings. This section covers the supported authorization types and how to create, view, update, and delete registries.

**Topics**
+ [

# Supported Inbound Authorization types
](registry-supported-auth-types.md)
+ [

# Create and manage registries
](registry-create-manage.md)

# Supported Inbound Authorization types
Supported Inbound Authorization types

Inbound authorization allows registry administrators to control which users can search for records in the registry (via AWS CLI, SDK, console, or MCP server). Administrators can configure inbound authorization using IAM or JWT.

## IAM-based authorization


IAM-based authorization uses the caller’s AWS IAM credentials (SigV4 signing) for authorization. Use this option if your consumers already have AWS IAM access.

### To set up IAM-based authorization


1. Create or use an existing IAM identity for your registry consumers.

1. Create an identity-based IAM policy with the following permissions:

   1.  `bedrock-agentcore:SearchRegistryRecords` 

   1.  `bedrock-agentcore:InvokeRegistryMcp` 

   1. You can optionally scope the IAM Permissions to the specific Registry Resource if you want to limit which registry a particular consumer can search in

1. Attach the policy to the consumer identity (IAM User or Role).

### Example policy


```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:SearchRegistryRecords",
      "bedrock-agentcore:InvokeRegistryMcp"
    ],
    "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/<YOUR_REGISTRY_ID>"
  }]
}
```

## JWT-based authorization


JSON Web Token (JWT) authorization lets consumers authorize using tokens from your organization’s identity provider — such as Amazon Cognito, Okta, Microsoft Azure AD, Auth0, or any OAuth 2.0-compatible provider. This is useful when you want to make the registry accessible to a broad set of users through existing corporate credentials, without provisioning individual IAM access.

### Set up a default JWT with Amazon Cognito


When you create a registry through the console and select JWT authorization, you can choose the quick create option. AWS Agent Registry creates an Amazon Cognito user pool and configures the JWT authorization automatically. No additional setup is required.

### Set up a JWT manually with your own identity provider


If you have an existing identity provider, configure JWT authorization manually. You need:
+  **Discovery URL** (required) — The OpenID Connect discovery URL from your identity provider (for example, `https://cognito-idp.us-east-1.amazonaws.com/YOUR_POOL_ID/.well-known/openid-configuration` ). AWS Agent Registry uses this URL to fetch the login, token, and verification settings.

You must also configure at least one of the following JWT authorization rules:
+  **Allowed audiences** — Permitted values for the `aud` claim. An audience claim specifies which resource server the token is intended for, preventing token reuse across different APIs.
+  **Allowed clients** — Permitted values for the `client_id` claim. A client ID is a unique identifier for the application requesting access tokens.
+  **Allowed scopes** — Required permission scopes. At least one scope in the incoming token must match one of the configured values.
+  **Custom claims** — Rules that match specific claims in the incoming token against predefined values. For each rule, specify the claim name, value type (STRING or STRING\$1ARRAY), and the required match value.

If you configure more than one authorization rule, AWS Agent Registry verifies all of them.

## Changing Authorization type


You cannot change authorization Type after a Registry has been created. Additionally, for registries setup with JWT based authorization, the Discovery URL cannot be edited after the Registry has been created.

## Authorization scope


The authorization type you configure only affects the data plane APIs — SearchRegistryRecords and InvokeRegistryMcp. All control plane APIs (CreateRegistry, CreateRegistryRecord, UpdateRegistryRecordStatus, and others) always require IAM authorization, regardless of the registry’s authorization setting.

# Create and manage registries
Create and manage registries

## Create a registry


### Console


1. Open the [Amazon Bedrock AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, under **Discover** , choose **Registry**.

1. In the **Registries** section, choose **Create registry**.

1. For **Name** , enter a name for your registry. The name must start with a letter or digit. Valid characters are a-z, A-Z, 0-9, \$1 (underscore), - (hyphen), . (dot), and / (forward slash). The name can have up to 64 characters.

1. (Optional) Expand **Additional details** and enter a **Description** (1–4,096 characters).

1. (Optional) Expand **Search API Authorization** to configure how consumers authorize when searching the registry (Inbound Authorization). Choose ** AWS IAM** to use standard AWS credentials, or **JSON Web tokens (JWT)** to use your corporate identity provider credentials. If you choose JWT, you can either quick create with Cognito, or bring your own IdP by providing the discovery URL, audience, scope, custom claims and clients.

1. Under **Record approval** , choose whether to enable **Auto-approval** . When auto-approval is off, a curator must review and approve each record before it becomes searchable.

1. Choose **Create registry**.

The registry status starts as **Creating** and transitions to **Ready** when provisioning completes.

**Note**  
For JWT enabled registries, At least one **JWT authorization configuration** field is required: allowed audiences, allowed clients, allowed scopes, or custom claims. If you configure more than one, AWS Agent Registry verifies all of them.

### AWS CLI


 **IAM-based registry:** 

```
aws bedrock-agentcore-control create-registry \
  --name "MyRegistry" \
  --description "Production registry" \
  --region us-east-1
```

 **JWT-based registry:** 

```
aws bedrock-agentcore-control create-registry \
  --name "MyOAuthRegistry" \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{"customJWTAuthorizer": {"discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/<poolId>/.well-known/openid-configuration", "allowedClients": ["<appClientId>"]}}' \
  --region us-east-1
```

### AWS SDK


 **IAM-based registry:** 

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_registry(
    name='MyRegistry',
    description='Production registry'
)
print(response['registryArn'])
```

 **JWT-based registry:** 

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_registry(
    name='MyOAuthRegistry',
    authorizerType='CUSTOM_JWT',
    authorizerConfiguration={
        'customJWTAuthorizer': {
            'discoveryUrl': 'https://cognito-idp.us-east-1.amazonaws.com/<poolId>/.well-known/openid-configuration',
            'allowedClients': ['<appClientId>']
        }
    }
)
print(response['registryArn'])
```

## List registries


### Console


1. Open the [Amazon Bedrock AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, under **Discover** , choose **Registry**.

1. The **Registries** table displays all registries in your account with the following columns:

   1.  **Name** — The registry name (linked to the detail page).

   1.  **Description** — The registry description, if provided.

   1.  **Authorization type** — The inbound authorization method (AWS\$1IAM or CUSTOM\$1JWT).

   1.  **Status** — The current status (Creating, Ready, Updating, Deleting, or a failure state).

   1.  **ARN** — The registry Amazon Resource Name.

   1.  **Created** — The creation timestamp.

   1.  **Last updated** — The last modification timestamp.

1. Use the **Find registries** search bar to filter by name.

1. Use the pagination controls to navigate through results.

### AWS CLI


```
aws bedrock-agentcore-control list-registries \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.list_registries()
for registry in response['registries']:
    print(f"{registry['name']} - {registry['status']} - {registry['registryArn']}")
```

## View registry details


### Console


1. Open the [Amazon Bedrock AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, under **Discover** , choose **Registry**.

1. Choose the registry name from the **Registries** table.

1. The registry detail page has two tabs:

   1.  **Manage records** — View and manage registry records.

   1.  **Search records** — Search for approved records in the registry.

1. The **Registry details** section displays: Name, Status, Description, Auto-approval (Enabled or Disabled), Registry ARN, Last updated date, Created date.

1. The **Registry records** section shows status summary counters (Total submitted, Pending approval, Approved, Deprecated, Rejected) and a records table.

1. The **Search API Authorization** (Inbound Authorization) section shows the current authorization type.

### AWS CLI


```
aws bedrock-agentcore-control get-registry \
  --registry-id "<registryId>" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.get_registry(
    registryId='<registryId>'
)
print(f"Name: {response['name']}")
print(f"Status: {response['status']}")
print(f"ARN: {response['registryArn']}")
```

## Update a registry


### Console


1. Open the [Amazon Bedrock AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, under **Discover** , choose **Registry**.

1. Select the radio button next to the registry you want to edit, then choose **Edit** . Alternatively, choose the registry name and then choose **Edit**.

1. On the **Edit registry** page, update any of the following:

   1.  **Name** — Change the registry name (same naming rules as creation).

   1.  **Description** — Under **Additional details** , update or add a description.

   1.  **Record approval** — Toggle **Auto-approval** on or off. Changes only affect records submitted after the update.

1. Choose **Save changes**.

**Note**  
Updating auto-approval config from OFF to ON only affects records submitted after the change. Existing records already 'Pending Approval' are not affected and must still be approved or rejected by calling UpdateRegistryRecordStatus API. Changing the config from ON to OFF only affects records that are published to 'Pending Approval' after the change is made.

**Note**  
The discovery URL (for a JWT authorized registry) cannot be changed after the registry is created. The inbound authorization type (IAM or JWT) cannot be changed after the registry is created.

### AWS CLI


```
aws bedrock-agentcore-control update-registry \
  --registry-id "<registryId>" \
  --description '{"optionalValue": "Updated description"}' \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry(
    registryId='<registryId>',
    description={'optionalValue': 'Updated description'}
)
print(f"Updated: {response['name']} - Status: {response['status']}")
```

## Delete a registry


### Console


1. Open the [Amazon Bedrock AgentCore console](https://console.aws.amazon.com/bedrock-agentcore/home?region=us-east-1#).

1. In the navigation pane, under **Discover** , choose **Registry**.

1. Select the radio button next to the registry you want to delete, then choose **Delete**.

1. In the confirmation dialog, review the warning: you must first delete all registry records before deleting the registry.

1. Type **delete** in the confirmation field.

1. Choose **Delete**.

The registry status changes to **Deleting** . A success banner confirms when deletion completes.

### AWS CLI


```
aws bedrock-agentcore-control delete-registry \
  --registry-id "<registryId>" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.delete_registry(
    registryId='<registryId>'
)
print(f"Status: {response['status']}")  # DELETING
```

# Creating and managing registry records
Creating and managing registry records

Registry records represent the individual resources published into a registry. Each record captures metadata that describes the underlying resource — what it is, what it does, and how it can be found. This section covers the supported record types, record lifecycle, and how to create and manage records.

**Topics**
+ [

# Supported record types
](registry-supported-record-types.md)
+ [

# Record lifecycle
](registry-record-lifecycle.md)
+ [

# Create and manage records
](registry-create-manage-records.md)
+ [

# Synchronize records from external sources
](registry-sync-records.md)

# Supported record types
Supported record types

 AWS Agent Registry validates record content against official protocol schemas. The console displays the reference schema side-by-side with your input and shows inline validation errors with a **Diagnose with Amazon Q** button. The registry supports all versions of the MCP Protocol Schema and the A2A Schema.

Each record has 3 metadata fields (name, description, recordVersion). Besides, the `descriptorType` and `descriptors` are where you specify the record metadata.

## MCP descriptors


An MCP server record contains following descriptors:
+  **Server** — This descriptor is based on the [official MCP registry](https://registry.modelcontextprotocol.io/) server.json definition. The content would be validated against the selected schema version, which can be [found here](https://github.com/modelcontextprotocol/static/tree/main/schemas) . Current supported `SchemaVersion` include: [2025-12-11](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json) , [2025-10-17](https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json) , [2025-10-11](https://static.modelcontextprotocol.io/schemas/2025-10-11/server.schema.json) , [2025-09-29](https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json) , [2025-09-16](https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json) , [2025-07-09](https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json) . If you do not have a server.json, we recommend you create one with the latest schema.
+  **Tools** — Tools available on the server, validated against the [MCP protocol](https://modelcontextprotocol.io/specification/2025-11-25/schema) . Current supported `protocolVersion` include: [2025-11-25](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.json) , [2025-06-18](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-06-18/schema.json) , [2025-03-26](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.json) , [2024-11-05](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2024-11-05/schema.json).

 **Minimal valid example of server descriptor:** 

```
{
  "name": "my-org/weather-server",
  "description": "Weather data and forecasts via OpenWeatherMap API",
  "version": "1.0.0"
}
```

 **Minimal valid example of tools descriptor:** 

```
{
    "tools":
    [
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "inputSchema":
            {
                "type": "object",
                "properties":
                {
                    "city":
                    {
                        "type": "string"
                    }
                }
            }
        }
    ]
}
```

 **Console:** Select **MCP** under Record type. The editor shows server and tools JSON editors with an optional official schema reference.

## Agent descriptors


Agents are autonomous programs that reason, plan, and take actions. An agent record contains:
+  **Agent card** — Capabilities, skills, and communication interface validated against the [A2A agent card specification](https://a2a-protocol.org/latest/specification/#441-agentcard) . Current supported `schemaVersion` : [0.3](https://github.com/a2aproject/A2A/blob/v0.3.0/specification/json/a2a.json#L138) . Note that the content will be validated against \$1/definitions/AgentCard in the json schema.

 **Minimal valid example:** 

```
{
    "name": "My Agent",
    "description": "Brief description of what this agent does",
    "version": "1.0.0",
    "protocolVersion": "0.3.0",
    "url": "https://api.example.com/a2a",
    "capabilities": {},
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain"],
    "skills": [
        {
            "id": "default-skill",
            "name": "Default Skill",
            "description": "Description of what this skill does",
            "tags": ["general"]
        }
    ]
}
```

 **Console:** Select **Agent** under Record type. The editor shows **Your agent card** alongside an **Official agent card** reference schema with a version dropdown (e.g., 0.3). Toggle **Show official schema** to display the reference.

## AgentSkills descriptors


Skills are reusable capabilities shared across agents. A skill record contains:
+  **Skill markdown (optional)** — Content of SKILL.md, which will be validated against the [official AgentSkills specification](https://agentskills.io/home) . Note that the markdown is only used as metadata for discovery purpose. Registry does not support storing other agent skill files.
+  **Skill definition (optional)** — Structured definition validated against an Amazon pre-defined schema. The supported `schemaVersion` : 0.1.0.

The skill definition schema is defined as follow:

```
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Agent skills skill definition schema",
  "description": "Schema for skill definition metadata. All top-level fields are optional. Unknown fields are allowed for forward compatibility.",
  "type": "object",
  "properties": {
    "_meta": {
      "description": "Extension metadata using reverse DNS namespacing for vendor-specific data.",
      "type": "object"
    },
    "repository": {
      "$ref": "#/definitions/Repository"
    },
    "websiteUrl": {
      "description": "URL to the skill's homepage, documentation, or project website.",
      "type": "string",
      "format": "uri"
    },
    "packages": {
      "description": "Package distribution configurations for the skill.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/Package"
      }
    }
  },
  "definitions": {
    "Repository": {
      "description": "Source code repository metadata for the skill.",
      "type": "object",
      "properties": {
        "url": {
          "description": "Repository URL for browsing source code.",
          "type": "string",
          "format": "uri"
        },
        "source": {
          "description": "Repository hosting service identifier (e.g., 'github', 'gitlab', 'codecommit').",
          "type": "string"
        }
      },
      "required": ["url", "source"]
    },
    "Package": {
      "description": "Package distribution configuration.",
      "type": "object",
      "properties": {
        "registryType": {
          "description": "Package registry type (e.g., 'npm', 'pypi').",
          "type": "string"
        },
        "identifier": {
          "description": "Package identifier in the registry (e.g., '@scope/package-name').",
          "type": "string"
        },
        "version": {
          "description": "Package version. Must be a specific version.",
          "type": "string"
        }
      },
      "required": ["registryType", "identifier"]
    }
  }
}
```

 **A valid example of skill markdown:** 

```
---
name: my-skill
description: Brief description of what this skill does.
---

# My Skill

Describe your skill's purpose, usage, and capabilities here.
```

 **A valid example of skill definition:** 

```
{
  "websiteUrl": "https://example.com/my-skill",
  "repository": {"url": "https://github.com/example/my-skill", "source": "github"}
}
```

 **Console:** Select **Agent Skills** under Record type.

## Custom descriptors


For resources not fitting standard types (Eg - APIs, Lambda functions, knowledge bases, databases, agents using other protocols), you can use custom descriptor. The content must be a valid JSON.

 **Console:** Select **Custom** under Record type. The editor shows a single **Definition** JSON editor with no official schema reference.

**Note**  
The console displays the record type column as **Record type** in the records table. The API uses the field name `descriptorType`.

# Record lifecycle
Record lifecycle

## Status transitions


```
Create → DRAFT → Submit → PENDING_APPROVAL → Approve → APPROVED
                               │                          │
                               │ Reject                   │ Edit (new DRAFT
                               ▼                          │  revision; approved
                          REJECTED ── Approve (direct) ───┘  stays in search)
                               │
                               └── Edit → DRAFT

         Any status → DEPRECATED (terminal)
```

## Transition details

+  **Create** → DRAFT. Edit freely before submitting.
+  **Submit** → PENDING\$1APPROVAL. Auto-approval skips to APPROVED. Amazon EventBridge notification sent.
+  **Approve/Reject** → Curator uses UpdateRegistryRecordStatus. Can directly approve a REJECTED record.
+  **Deprecate** → Terminal from any status. Cannot be undone.

## How edits affect status



| Current status | Effect of edit | 
| --- | --- | 
|  DRAFT  |  Updated in place. Stays DRAFT.  | 
|  PENDING\$1APPROVAL  |  New DRAFT revision. Pending revision discarded. Not visible in search (never approved).  | 
|  APPROVED  |  New DRAFT revision. Approved revision stays visible in search until new revision is approved.  | 
|  REJECTED  |  New DRAFT revision. Must go through normal submit-and-approve flow again.  | 
|  DEPRECATED  |  Deprecated Records cannot be edited; Deprecated is a Terminal state  | 

## Dual-revision behavior


Editing an APPROVED record creates a new DRAFT revision while the approved revision remains active:
+  **Search and MCP endpoint** — Returns the approved revision.
+  **Get and List APIs** — Returns the latest (DRAFT) revision.

Once the edited revision of the record is reviewed and approved, then Search and MCP Endpoint also start showing the new (approved) revision.

## Visibility rules



| API | Returns | 
| --- | --- | 
|  SearchRegistryRecords  |  Only approved revisions  | 
|  InvokeRegistryMcp  |  Only approved revisions  | 
|  GetRegistryRecord  |  Latest revision (any status)  | 
|  ListRegistryRecords  |  Latest revision (any status)  | 

# Create and manage records
Create and manage records

## Create a registry record


### Console


1. Open the registry detail page.

1. In the **Registry records** section, choose **Create record**.

1. Under **Record details** , enter:

   1.  **Name** — Must start with a letter or digit. Valid characters are a-z, A-Z, 0-9, \$1 (underscore), - (hyphen), . (dot), and / (forward slash). The name can have up to 255 characters.

   1.  **Description** (optional) — 1 to 4,096 characters.

   1.  **Record version** — Specify the version of this record (e.g., 1.0.0, v2.1).

1. Under **Record type** , select one of: **MCP** , **Agent** , **Agent Skills** , or **Custom**.

1. A type-specific editor appears. Enter your protocol configuration in JSON format.

   1. For **Agent** and **MCP** types, toggle **Show official schema** to display the reference schema side-by-side for guidance.

   1. The console validates your JSON against the official schema and shows inline errors (e.g., "Missing property 'name'") with a **Diagnose with Amazon Q** button.

1. Choose one of:

   1.  **Create as draft** — Creates the record in Draft status.

   1.  **Create and submit for approval** — Creates the record and immediately submits it for approval.

### AWS CLI


```
aws bedrock-agentcore-control create-registry-record \
  --registry-id <registryId> \
  --name "MyMCPServer" \
  --descriptor-type MCP \
  --descriptors '{"mcp": {"server": {"inlineContent": "{\"name\": \"my/mcp-server\", \"description\": \"My MCP server\", \"version\": \"1.0.0\"}"}}}' \
  --record-version "1.0" \
  --region us-east-1
```

### AWS SDK


```
import boto3
import json

client = boto3.client('bedrock-agentcore-control')

server_content = json.dumps({
    "name": "my/mcp-server",
    "description": "My MCP server",
    "version": "1.0.0"
})

response = client.create_registry_record(
    registryId='<registryId>',
    name='MyMCPServer',
    descriptorType='MCP',
    descriptors={
        'mcp': {
            'server': {
                'inlineContent': server_content
            }
        }
    },
    recordVersion='1.0'
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # CREATING
```

## List registry records


### Console


1. Open the registry detail page.

1. The **Registry records** section displays:

   1.  **Status summary counters** — Total submitted, Pending approval, Approved, Deprecated, Rejected.

   1.  **Records table** with columns: Name, Description, Status, Record type, Record ARN, Last updated.

1. Use the **Search records** bar to filter by name.

1. Use the **Update status** dropdown to perform bulk status changes on selected records.

### AWS CLI


```
aws bedrock-agentcore-control list-registry-records \
  --registry-id "<registryId>" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.list_registry_records(
    registryId='<registryId>'
)
for record in response['registryRecords']:
    print(f"{record['name']} - {record['status']} - {record['descriptorType']}")
```

## View record details


### Console


1. From the registry detail page, choose a record name from the records table.

1. The record detail page displays:

   1.  **Record details** section — Name, Description, Record ARN, Status (shown as a badge next to the record name), Version, Last updated date, Record type, Record ID, Created date.

   1.  **Protocol configuration** section — The descriptor content displayed as formatted JSON (e.g., "Agent card" for A2A records, "Server" and "Tools" for MCP records).

1. Actions available:

   1.  **Update status** dropdown — Submit for approval, Approve, Reject, or Deprecate.

   1.  **Three-dot menu (⋮)** — Edit or Delete.

### AWS CLI


```
aws bedrock-agentcore-control get-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.get_registry_record(
    registryId='<registryId>',
    recordId='<recordId>'
)
print(f"Name: {response['name']}")
print(f"Description: {response['description']}")
print(f"Status: {response['status']}")
print(f"Descriptor Type: {response['descriptorType']}")
print(f"Version: {response['recordVersion']}")
```

## Update a registry record


### Console


1. From the record detail page, choose the three-dot menu (⋮), then choose **Edit**.

1. On the **Edit record** page, update any of the following:

   1.  **Name** , **Description** , **Record version** under Record details.

   1.  **Protocol configuration** in the JSON editor.

1. The console validates your JSON against the official schema and shows inline errors with a **Diagnose with Amazon Q** button.

1. Choose one of:

   1.  **Save changes** — Saves the record as a draft.

   1.  **Save and submit for approval** — Saves and submits in one step.

A success banner confirms: "[Name] is updated and submitted for approval successfully."

### AWS CLI


```
aws bedrock-agentcore-control update-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --description "Updated description" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record(
    registryId='<registryId>',
    recordId='<recordId>',
    description='Updated description'
)
print(f"Updated: {response['name']} - Status: {response['status']}")
```

## Submit a record for approval


### Console


From the record detail page -

1. Choose the **Update status** dropdown

1. Then, choose **Submit for approval**.

   1. Alternatively, use **Create and submit for approval** or **Save and submit for approval** during creation or editing.

**Note**  
If the Registry’s Auto-Approval configuration is set to TRUE, then submitting a record for approval automatically approves it. Otherwise, if the Auto-Approval configuration is set to FALSE, then the record moves to 'Pending Approval' status and waits for the Curator to either Approve it or Reject it. Additionally, an Amazon EventBridge notification is triggered indicating a new record has been requested for approval.

### AWS CLI


```
aws bedrock-agentcore-control submit-registry-record-for-approval \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.submit_registry_record_for_approval(
    registryId='<registryId>',
    recordId='<recordId>'
)
print(f"Status: {response['status']}")  # PENDING_APPROVAL or APPROVED
```

## Delete a registry record


### Console


1. From the record detail page, choose the three-dot menu (⋮), then choose **Delete**.

1. Confirm the deletion by typing in 'delete' when prompted

Deletion is permanent and cannot be undone.

### AWS CLI


```
aws bedrock-agentcore-control delete-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.delete_registry_record(
    registryId='<registryId>',
    recordId='<recordId>'
)
print("Record deleted successfully")
```

## Schema validation


When you create or edit a record, the console and API validate your protocol configuration against the official schema for the selected record type. More details on validations can be found in [Supported record types](registry-supported-record-types.md).

# Synchronize records from external sources
Synchronize records from external sources

## Overview


 AWS Agent Registry can automatically synchronize record metadata from external sources by connecting to the provided URL with outbound credentials. When you provide a URL and credential provider (Optional for public resources that do not require any Authorization to access), the system extracts server and tool definitions and populates the record’s descriptors conforming to the official protocol schemas. It also updates the record’s name, description, and version if those values are found at the source.

**Note**  
At public preview launch, SSE stream from MCP server is not supported yet.

## Synchronize from a public MCP server


For Public MCP servers that don’t require authentication or authorization:

### AWS CLI


```
aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "aws-knowledge-server" \
  --descriptor-type MCP \
  --synchronization-type URL \
  --synchronization-configuration '{
    "fromUrl":
    {
        "url": "https://knowledge-mcp.global.api.aws"
    }
  }' \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.create_registry_record(
    registryId='<registryId>',
    name='aws-knowledge-server',
    descriptorType='MCP',
    synchronizationType='URL',
    synchronizationConfiguration={
        'fromUrl': {
            'url': 'https://knowledge-mcp.global.api.aws'
        }
    }
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # CREATING
```

The record is created in CREATING status. The synchronization time varies from seconds to minutes, depending on the size of the metadata. After synchronization completed, it transitions to DRAFT with descriptors extracted from the MCP server, including server and tools definitions.

## Synchronize from an OAuth-protected MCP server


When the MCP server is protected by OAuth, you will need to create an M2M client on the authorization server, and then configure a [credential provider from AgentCore Identity](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/resource-providers.html) containing the client ID and secret allowlisted to invoke the MCP server. Once you have the credential provider, you can supply it to the registry for synchronization:

```
aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "oauth-mcp-server" \
  --descriptor-type MCP \
  --synchronization-type URL \
  --synchronization-configuration '{
    "fromUrl":
    {
        "url": "$MCP_OAUTH_URL",
        "credentialProviderConfigurations":
        [
            {
                "credentialProviderType": "OAUTH",
                "credentialProvider":
                {
                    "oauthCredentialProvider":
                    {
                        "providerArn": "$OAUTH_PROVIDER_ARN",
                        "grantType": "CLIENT_CREDENTIALS"
                    }
                }
            }
        ]
    }
  }' \
  --region us-east-1
```

 **Additional IAM permissions required:** 

```
{
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetWorkloadAccessToken"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:workload-identity-directory/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action":
            [
                "bedrock-agentcore:GetResourceOauth2Token"
            ],
            "Resource":
            [
                "arn:aws:bedrock-agentcore:*:<account>:token-vault/*"
            ]
        }
    ]
}
```

Limitations:
+ The caller of CreateRegistryRecord or UpdateRegistryRecord must have GetWorkloadAccessToken registry-associated workload identity and GetResourceOauth2Token permission on the credential provider.
+ The credential provider must be coming from the same account.

## Synchronize from an IAM-protected MCP server


For MCP servers on AgentCore Runtime or AgentCore Gateway, specify an IAM role for SigV4 signing. The role must have permission to access the target service. For example: `bedrock-agentcore:InvokeAgentRuntime` or `bedrock-agentcore:InvokeAgentRuntimeForUser` on AgentCore Runtime; `bedrock-agentcore:InvokeGateway` on AgentCore Gateway.

Besides the IAM role, you must specify `service` field for SigV4 signing. If your MCP runs on AgentCore Runtime or AgentCore Gateway, the value should be `bedrock-agentcore` . If your MCP runs on API gateway, it should be `execute-api` , and if your MCP runs on lambda, it should be `lambda`.

 `region` value is optional. By default, the request will be signed with same region as the registry.

```
aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "gateway-mcp-server" \
  --descriptor-type MCP \
  --synchronization-type URL \
  --synchronization-configuration '{
    "fromUrl":
    {
        "url": "$MCP_IAM_URL",
        "credentialProviderConfigurations":
        [
            {
                "credentialProviderType": "IAM",
                "credentialProvider":
                {
                    "iamCredentialProvider":
                    {
                        "roleArn": "$IAM_ROLE_ARN",
                        "service": "$SIGNING_SERVICE",
                        "region": "$SIGNING_REGION"
                    }
                }
            }
        ]
    }
  }' \
  --region us-east-1
```

 **Additional IAM permissions required:** 

```
{
    "Statement":
    [
        {
            "Effect": "Allow",
            "Action":
            [
                "iam:PassRole"
            ],
            "Resource":
            [
                "arn:aws:iam::<account>:role/<sync-role>"
            ],
            "Condition":
            {
                "StringEquals":
                {
                    "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
                }
            }
        }
    ]
}
```

## Synchronize from an A2A agent card


Provide the agent card URL or the agent’s base URL where `.well-known/agent-card.json` can be discovered:

```
aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "travel-agent" \
  --descriptor-type A2A \
  --synchronization-type URL \
  --synchronization-configuration '{"fromUrl": {"url": "https://agent.example.com/.well-known/agent-card.json"}}' \
  --region us-east-1
```

You can also specify credential providers for A2A synchronization, for example you can synchronize from an agent hosted on AgentCore:

```
aws bedrock-agentcore-control create-registry-record \
  --registry-id $REGISTRY_ID \
  --name "a2a_agent_record" \
  --descriptor-type A2A \
  --synchronization-type URL \
  --synchronization-configuration "{
    \"fromUrl\": {
        \"url\": \"$A2A_URL\",
        \"credentialProviderConfigurations\": [{
            \"credentialProviderType\": \"IAM\",
            \"credentialProvider\": {
                \"iamCredentialProvider\": {
                    \"roleArn\": \"$IAM_INVOKER_ROLE\",
                    \"service\": \"bedrock-agentcore\"
                }
            }
        }]
    }
  }"
```

## Trigger synchronization on an existing record


### AWS CLI


```
aws bedrock-agentcore-control update-registry-record \
  --registry-id $REGISTRY_ID \
  --record-id $RECORD_ID \
  --trigger-synchronization \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record(
    registryId='<registryId>',
    recordId='<recordId>',
    triggerSynchronization=True
)
print(f"Status: {response['status']}")
```

**Note**  
If the record is in a non-DRAFT status (e.g., APPROVED), the update creates a new DRAFT revision. The approved revision remains searchable.

 **Troubleshooting** : see [Record synchronization errors](registry-troubleshooting.md#registry-troubleshooting-sync-errors).

# Curating the registry
Curating the registry

Curators are the quality gatekeepers of the registry. They review records that publishers have submitted for approval, evaluate each record against the organization’s standards for security, compliance, and metadata quality, and approve or reject records accordingly. When a resource is decommissioned or superseded, curators deprecate the record to remove it from discovery. This section covers how to review pending records, approve or reject them, deprecate records, and set up notifications for pending approvals.

**Topics**
+ [

# Reviewing registry records
](registry-reviewing-records.md)
+ [

# Deprecating registry records
](registry-deprecating-records.md)
+ [

# Notifications for pending approvals
](registry-notifications-approvals.md)

# Reviewing registry records
Reviewing registry records

## Overview


As a curator, you review records in Pending Approval status against your organization’s standards for security, compliance, and metadata quality.

## View pending records


Filter by PENDING\$1APPROVAL status via console, AWS CLI, or ListRegistryRecords API.

## Approve a record


### Console


1. Open the record detail page for a record in **Pending approval** status.

1. Choose the **Update status** dropdown, then choose **Approve**.

1. In the **Update status** dialog, enter a **Reason** for the status change.

1. Choose **Update**.

### AWS CLI


```
aws bedrock-agentcore-control update-registry-record-status \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --status APPROVED \
  --status-reason "Reviewed and approved" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record_status(
    registryId='<registryId>',
    recordId='<recordId>',
    status='APPROVED',
    statusReason='Reviewed and approved'
)
print(f"Status: {response['status']}")  # APPROVED
print(f"StatusReason: {response['statusReason']}")
```

## Reject a record


### Console


1. Open the record detail page for a record in **Pending approval** status.

1. Choose the **Update status** dropdown, then choose **Reject**.

1. In the **Update status** dialog, enter a **Reason** for the rejection.

1. Choose **Update**.

### AWS CLI


```
aws bedrock-agentcore-control update-registry-record-status \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --status REJECTED \
  --status-reason "Missing tool input schemas" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record_status(
    registryId='<registryId>',
    recordId='<recordId>',
    status='REJECTED',
    statusReason='Missing tool input schemas'
)
print(f"Status: {response['status']}")  # REJECTED
print(f"StatusReason: {response['statusReason']}")
```

**Note**  
Publisher can edit and resubmit, or curator can directly approve a rejected record.

# Deprecating registry records
Deprecating registry records

## Overview


Deprecation of a Registry Record removes the record from being discoverable in the Search Results (via SearchRegistryRecords API) as well as the Registry’s MCP endpoint. Deprecated is a Terminal State and once a record is in this state, it cannot be edited or transitioned to any other state. The Record can still be found via ListRegistryRecords and GetRegistryRecord APIs for auditing purposes, but cannot be un-deprecated.

Deprecate a record for reasons like you have decommissioned the resource, a newer version of the resource is published (with an independent record in the registry), the resource has known issues due to which you do not want other builders to discover the resource, or internal policy requires removal of the resource record.

## Deprecate a record


### Console


1. Open the record detail page.

1. Choose the **Update status** dropdown, then choose **Deprecate**.

1. In the **Update status** dialog, enter a **Reason** for the deprecation.

1. Choose **Update**.

**Note**  
Deprecation is available from any record status.

### AWS CLI


```
aws bedrock-agentcore-control update-registry-record-status \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --status DEPRECATED \
  --status-reason "Replaced by v2" \
  --region us-east-1
```

### AWS SDK


```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record_status(
    registryId='<registryId>',
    recordId='<recordId>',
    status='DEPRECATED',
    statusReason='Replaced by v2'
)
print(f"Status: {response['status']}")  # DEPRECATED
print(f"StatusReason: {response['statusReason']}")
```

# Notifications for pending approvals
Notifications for pending approvals

## Event details

+  **Source:** `aws.bedrock-agentcore` 
+  **Detail type:** `Registry Record State changed to Pending Approval` 
+  **Bus:** Default Amazon EventBridge bus
+  **Resources:** Full ARN of the registry record
+  **Detail:** Contains `registryRecordId` and `registryId` 

## Example event


```
{
 "version":"0",
 "detail-type":"Registry Record State changed to Pending Approval",
 "source":"aws.bedrock-agentcore",
 "account":"123456789012",
 "region":"us-west-2",
 "resources":["arn:aws:bedrock-agentcore:us-west-2:123456789012:registry/REG_ID/record/REC_ID"],
 "detail":{"registryRecordId":"REC_ID","registryId":"REG_ID"}
}
```

## Create an Amazon EventBridge rule


For more information on how to create Amazon EventBridge Rules, see [Creating Amazon EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-visual.html) . AWS Agent Registry events can be found under the source: `aws.bedrock-agentcore` and detail-type: `Registry Record State changed to Pending Approval`.

You can configure the rule to any [Target](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-targets.html) supported by Amazon EventBridge.

# Searching the registry
Searching the registry

Consumers search the registry to discover MCP servers, agents, skills, and other resources that have been approved and published. AWS Agent Registry combines semantic search with keyword matching to deliver relevant results for any type of query. This section covers how to search for registry records and how to use the Registry MCP endpoint.

**Topics**
+ [

# Search for registry records
](registry-search-records.md)
+ [

# Using the Registry MCP endpoint
](registry-mcp-endpoint.md)

# Search for registry records
Search for registry records

## Request Parameters

+  **searchQuery** (required): Can be any natural language query from 1–256 characters
+  **registryIds** (required): Which Registry to conduct the Search in. Supports exactly one registry ARN or ID
+  **maxResults** (optional): How many records are returned in the Search response. Can take any value between 1–20 and defaults to 10
+  **filters** (optional) — Metadata filter expression

## Metadata filters


Operators: `$eq` , `$ne` , `$in` . Logical: `$and` , `$or` . Fields: name, descriptorType, version.

Example: `{"descriptorType": {"$eq": "MCP"}}` 

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

## Console


1. Open the registry detail page.

1. Choose the **Search records** tab.

1. Enter your search query and view results.

**Note**  
Console search is available for IAM-authorized registries only. For JWT-authorized registries, use the search API directly with an HTTP client (such as `curl` ) and a valid JWT bearer token, or use the MCP endpoint for the registry via an MCP client.

## AWS CLI (Registry with IAM based Inbound Authorization)


```
aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1
```

## AWS SDK (Registry with IAM based Inbound Authorization)


```
import boto3

client = boto3.client('bedrock-agentcore')

response = client.search_registry_records(
    registryIds=['<registryARN>'],
    searchQuery='weather',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"{record['name']} - {record['descriptorType']} - {record['status']}")
```

## HTTP client (Registry with OAuth based Inbound Authorization)


First obtain a bearer token:

```
SECRET_HASH=$(echo -n "<username><appClientId>" | openssl dgst -sha256 -hmac "<appClientSecret>" -binary | base64)

aws cognito-idp initiate-auth \
  --client-id "<appClientId>" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME="<username>",PASSWORD='<password>',SECRET_HASH="$SECRET_HASH" \
  --region us-east-1 | jq -r '.AuthenticationResult.AccessToken'
```

Then search with the bearer token:

```
curl -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry-records/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"registryIds": ["<registryARN>"], "searchQuery": "weather", "maxResults": 10}'
```

## Eventual consistency in AWS Agent Registry search


 AWS Agent Registry uses an eventually consistent model for search indexing. When you approve a registry record by calling `UpdateRegistryRecordStatus` or through the console, the record does not appear in `SearchRegistryRecords` or `InvokeRegistryMcp` results immediately. It typically takes a few seconds for the approved record to be indexed and become discoverable, but in some cases it can take up to a few minutes.

During this time, you might observe the following behavior:
+ A `SearchRegistryRecords` query does not return a record that was just approved.
+ The registry MCP endpoint ( `InvokeRegistryMcp` ) does not include a recently approved record in tool results.

Only records in **Approved** status are included in search results. Records in Draft, Pending Approval, Rejected, or Deprecated status are never returned by `SearchRegistryRecords` or `InvokeRegistryMcp` . You can verify a record’s current status by calling `GetRegistryRecord` , which always returns the latest revision regardless of indexing state.

To handle eventual consistency in your application, we recommend the following:
+ After approving a record, confirm it is discoverable by calling `SearchRegistryRecords` with a retry strategy that includes exponential backoff.
+ Do not assume a record is missing from the registry if it does not appear in search results immediately after approval. Call `GetRegistryRecord` to verify the record’s status.
+ If you are integrating approval workflows through Amazon EventBridge and `UpdateRegistryRecordStatus` , add a brief delay before downstream systems query the search API for the newly approved record.

For general guidance on configuring retry behavior in AWS SDKs, see [Retry behavior](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) in the * AWS SDKs and Tools Reference Guide*.

## How record attributes affect search relevance


 AWS Agent Registry uses hybrid search that combines semantic understanding with keyword matching to return relevant results. If a record you expect to find does not appear in search results, understanding which record attributes influence search can help.

### Which record attributes are used for search


The following attributes from your registry record are used to determine search relevance:
+  **Name** — Used for keyword matching. Clear, descriptive names that reflect what the resource does improve discoverability for exact and partial name lookups.
+  **Description** — Used for both keyword and semantic matching. Descriptions written in natural language that explain the resource’s purpose and common use cases are more discoverable than terse technical labels.
+  **Descriptors** — The full content of your protocol definition (MCP server definition, agent card, skill documentation, or custom JSON) is used for semantic matching. This includes tool names, tool descriptions, input parameter names, and capability summaries.
+  **Version and descriptor type** — Available as filterable fields. Consumers can narrow results using metadata filters on `name` , `descriptorType` , and `version`.

### How search queries are processed


When you call `SearchRegistryRecords` , AWS Agent Registry runs two searches in parallel against the same set of indexed records and merges the results:
+  **Semantic search** — Your query is converted into a vector representation and compared against the vector representations of indexed records. This finds conceptually related records even when the exact words in your query don’t appear in the record. For example, a query for "book a flight" can match a record named "travel-reservation-service."
+  **Keyword search** — Your query is matched against the text content of record fields using traditional keyword relevance. This is effective for exact name lookups and specific technical terms. For example, a query for "weather-api-v2" matches records containing that exact text.

If you include metadata filters in your request, the filters are applied to both searches before results are scored and ranked. This means filters reduce the candidate set that both semantic and keyword search operate on, rather than filtering results after ranking.

### How results are ranked


Results from both semantic and keyword search are combined into a single ranked list and returned in order of relevance, with the most relevant record first. Each result’s final position is determined by its relevance across both searches — a record that ranks highly in both semantic and keyword results will appear higher than a record that ranks highly in only one. Within keyword search, the record name has the strongest influence on ranking, followed by the description and descriptor content, which contribute equally. Because both search modes always run and contribute to the final ranking, how you write your query affects which records surface. The following guidance can help you get better results depending on your intent.

### Writing effective search queries


 **When you know the exact name or identifier** , use a short, specific query. Keyword search matches exact text against record names, descriptions, and descriptor content. Short queries like "weather-api-v2" or "pdf-processing" are effective for finding records by name.

 **When you’re exploring by capability or use case** , use a natural language description of what you need. Semantic search understands conceptual intent, so queries like "find a tool that can book flights" or "extract structured data from PDF documents" can match relevant records even if those exact words don’t appear in the record metadata.

 **Avoid mixing filter-like constraints with descriptive intent in the same query.** A query like "find all MCP servers for weather forecasts" sends the entire sentence through both semantic and keyword search. The semantic component interprets the full sentence as a conceptual intent, which can surface records that are conceptually related but don’t match the specific attribute you intended to constrain. Instead, use metadata filters for attribute-based constraints and keep the query focused on the topic. See [When to use metadata filters versus query text](#registry-search-filters-vs-query).

### Writing discoverable records

+ Write descriptions that explain what the resource does and the problems it solves. Semantic search understands intent, so "helps customers track package deliveries" is more discoverable than "delivery-status-endpoint."
+ Provide complete tool definitions for MCP servers. Tool descriptions and input parameter descriptions all contribute to search relevance.
+ Include relevant keywords in your name and description. Keyword search matches exact text, so if consumers are likely to search for specific terms, make sure those terms appear in your record.

### When to use metadata filters versus query text


Use metadata filters when your intent is to constrain results by a known attribute such as record type, name, or version. Do not embed filter-like constraints in the query text itself. For example, if you want to find all MCP servers related to weather, use a metadata filter for the record type and a query for the topic:

```
{
  "searchQuery": "weather forecast",
  "filters": {
    "descriptorType": { "$eq": "MCP" }
  }
}
```

Avoid putting the constraint into the query text like "find all MCP servers for weather forecasts". Because longer queries lean toward semantic matching, the words "MCP servers" are interpreted as part of the conceptual intent rather than as an exact filter. This can cause the semantic component to return records that are conceptually related to the full sentence but don’t match the specific attribute you intended to filter on — for example, returning agent records about weather alongside MCP server records. The same applies to any attribute-based constraint. If you want records with a specific name, version, or type, use the corresponding metadata filter rather than including those terms in the query.

You can filter on the following fields:
+  `name` — Match records by exact name.
+  `descriptorType` — Match records by resource type (for example, `MCP` , `A2A` , `SKILL` , `CUSTOM` ).
+  `version` — Match records by version string.

Filters support `$eq` (equals), `$ne` (not equals), and `$in` (matches any value in a list) operators, and can be combined using `$and` and `$or` logic.

For example, to search for weather-related MCP servers only:

```
{
  "searchQuery": "weather forecast",
  "filters": {
    "descriptorType": { "$eq": "MCP" }
  }
}
```

To exclude a specific resource type:

```
{
  "searchQuery": "<your query>",
  "filters": {
    "descriptorType": { "$ne": "CUSTOM" }
  }
}
```

To match any of several versions:

```
{
  "filters": {
    "version": { "$in": ["1.0", "1.1", "2.0"] }
  }
}
```

### Search returns only approved records


Only records in **Approved** status appear in search results and through the MCP endpoint. Records in Draft, Pending Approval, Rejected, or Deprecated status are not returned. If a recently approved record does not appear in results, see [Eventual consistency in AWS Agent Registry search](#registry-search-eventual-consistency).

# Using the Registry MCP endpoint
Using the Registry MCP endpoint

## Overview


Each registry exposes an MCP-compatible endpoint following [2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25) . The endpoint supports tool listing and tool invocation for searching registry records.

```
https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp
```

The MCP contains one tool named "search\$1registry\$1records".

```
Tool name: search_registry_records

Description:
Searches for registry records using natural language queries. Returns metadata for matching records.

Parameters:
- searchQuery (required): string - Natural language search query
- maxResults: integer - Maximum number of results to return (1-20, default 10)
- filter: object - Optional metadata filter using structured JSON operators. Supports field-level operators ($eq, $ne,
  $in) and logical operators ($and, $or) on filterable fields (name, descriptorType, version). Example:
  {"descriptorType": {"$eq": "MCP"}}
```

You can connect to registry from an existing MCP client, such as Kiro, Claude, etc.

## Connect to OAuth-based registry MCP endpoint from an existing MCP client


### Permissions


The MCP endpoint will use the same **CustomJWTAuthorizerConfiguration** to authorize the incoming requests.

The `.well-known/oauth-protected-resource` path is: `https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp`.

The client can discover the metadata from `WWW-Authenticate` header as well:

```
www-authenticate: Bearer resource_metadata="https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp"
```

Once you obtained the access token, you can validate it:

```
curl -s -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry_records","arguments":{"searchQuery":"weather"}}}'
```

Depending on your authorization server and organization’s security requirements, you may choose one of the following approaches to configure your MCP client:

1. Bearer token: use a separate process to fetch bearer token and configure it in MCP client header

1. Pre-registered client: create a client in your authorization server, and allowlist the client on registry’s configuration.

1. Dynamic client registration: if your authorization server supports dynamic client registration (DCR), you can allowlist the audience in registry’s configuration.

### OAuth-based MCP client setup


#### Use bearer token


In most IDEs, you can configure authorization header bearer token in an mcp configuration. For example, [Kiro supports](https://kiro.dev/blog/introducing-remote-mcp/#securing-mcp-connections) environment variables using the `${ENV_VAR}` syntax. You can use following example:

```
{
  "mcpServers": {
    "my-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
      "headers": {
        "Authorization": "Bearer ${ACCESS_TOKEN}"
      }
    }
  }
}
```

#### Pre-registered client


You can create a new client based on authorization code grant in your authorization server, and use the client to access registry. For example, [create a client in Cognito](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-idp-cognito.html) user pool.

Once you have the client ID, make sure you allowlist it in registry:

```
aws bedrock-agentcore-control update-registry \
  --registry-id <registryId> \
  --authorizer-configuration '{
    "optionalValue": {
      "customJWTAuthorizer": {
        "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration",
        "allowedClients": ["<client-id>"]
      }
    }
  }'
```

Then you can configure your MCP client if it supports specifying clientId. An example in Claude code:

```
{
  "mcpServers": {
    "pre-registered-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
      "oauth": {
        "clientId": "<client-id>",
        "callbackPort": "<port-number>"
      }
    }
  }
}
```

**Note**  
Some authorization servers like Auth0 and Cognito don’t let you configure a range of ports as allowed redirect URIs, so you need to explicitly set one in the preregistered client’s allowed redirect/callback URL, as well as in the mcp.json.

#### Dynamic client registration


Most MCP client applications support dynamic client registration. In this case, you should NOT specify `allowedClients` value in registry. Instead, you can choose to set `allowedAudience` . The value can be the same as your MCP registry. You should configure your authorization server to issue JWT with `aud` field with the same value as in `allowedAudience`.

```
aws bedrock-agentcore-control update-registry \
  --registry-id <registryId> \
  --authorizer-configuration '{
    "optionalValue": {
      "customJWTAuthorizer": {
        "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration",
        "allowedAudience": ["https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp"]
      }
    }
  }'
```

Then you can configure your MCP client simply using an url:

```
{
  "mcpServers": {
    "dcr-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp"
    }
  }
}
```

Common errors when you setup dynamic client registration:
+ You must ensure the authorization server supports dynamic client registration.
+ The authorization server must issue JWT with `aud` field, which is allowed in your registry’s CustomJWTAuthorizerConfiguration.
+ Currently registry does not return scope challenge in www-authenticate header. Some MCP clients support explicitly defining `oauthScopes` in configuration, such as [Kiro](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#oauth-configuration).

## Connect to IAM-based registry MCP endpoint from an existing MCP client


### Permissions


For MCP initialization and tool listing:

```
{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeRegistryMcp",
    "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*"
}
```

For searching via MCP tool invocation, you also need:

```
{
    "Effect": "Allow",
    "Action":
    [
        "bedrock-agentcore:InvokeRegistryMcp",
        "bedrock-agentcore:SearchRegistryRecords"
    ],
    "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*"
}
```

You can verify permission with command:

```
curl -s -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp" \
  -H "Content-Type: application/json" \
  -H "X-Amz-Security-Token: ${AWS_SESSION_TOKEN}" \
  --aws-sigv4 "aws:amz:<region>:bedrock-agentcore" \
  --user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry_records","arguments":{"searchQuery":"weather"}}}'
```

### IAM-based MCP client setup


You can use [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) to connect to an IAM-based registry. For example, in Kiro mcp.json:

```
{
  "mcpServers": {
    "iam-based-registry": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
        "--service",
        "bedrock-agentcore",
        "--region",
        "<region>",
        "--profile",
        "my-profile"
      ]
    }
  }
}
```

## Develop your own MCP client


For more code references of how to invoke the Registry MCP endpoint, including from popular IDEs like Kiro or Claude Code, please refer to sample code references in the public code repository.

# Notifications (Amazon EventBridge)
Notifications (Amazon EventBridge)

## Supported events


Events are sent to the default Amazon EventBridge bus. Source: `aws.bedrock-agentcore`.


| Event | Detail type | Trigger | 
| --- | --- | --- | 
|  Record submitted for approval  |   `Registry Record State changed to Pending Approval`   |  SubmitRegistryRecordForApproval called  | 
|  Registry moves from Creating to Ready State  |   `Registry State transitions from Creating to Ready`   |  After Create Registry, once a Registry completes provisioning  | 

See [Notifications for pending approvals](registry-notifications-approvals.md) for full event schema and setup instructions.

# Log Registry API calls with AWS CloudTrail
Log Registry API calls with AWS CloudTrail

 AWS Agent Registry control plane API calls are logged in AWS CloudTrail, providing a complete audit trail of who did what and when. Control plane operations are logged as management events by default.

**Topics**
+ [

# AWS CloudTrail integration
](registry-cloudtrail-integration.md)

# AWS CloudTrail integration
AWS CloudTrail integration

## Event types


 **Management events (logged by default):** CreateRegistry, GetRegistry, UpdateRegistry, DeleteRegistry, ListRegistries, CreateRegistryRecord, GetRegistryRecord, UpdateRegistryRecord, DeleteRegistryRecord, ListRegistryRecords, SubmitRegistryRecordForApproval, UpdateRegistryRecordStatus

## Sample CloudTrail log for CreateRegistryRecord API


```
{
    "eventVersion": "1.09",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "<REDACTED>",
        "arn": "arn:aws:sts::<REDACTED>",
        "accountId": "<REDACTED>",
        "accessKeyId": "<REDACTED>",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "<REDACTED>",
                "arn": "<REDACTED>",
                "accountId": "<REDACTED>",
                "userName": "Admin"
            },
            "attributes": {
                "creationDate": "2026-04-08T00:59:33Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2026-04-08T01:33:24Z",
    "eventSource": "bedrock-agentcore.amazonaws.com",
    "eventName": "CreateRegistryRecord",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "<REDACTED>",
    "userAgent": "<REDACTED>",
    "requestParameters": {
        "descriptors": {
            "mcp": {
                "server": {
                    "schemaVersion": "2025-12-11",
                    "inlineContent": "{\n  \"name\": \"io.example/my-server\",\n  \"description\": \"Brief description of server functionality\",\n  \"version\": \"1.0.0\"\n} "
                }
            }
        },
        "recordVersion": "1.0.0",
        "clientToken": "<REDACTED>",
        "name": "record_gk0xk",
        "registryId": "jzjXulIwVksK",
        "descriptorType": "MCP"
    },
    "responseElements": {
        "Access-Control-Expose-Headers": "x-amzn-RequestId,x-amzn-ErrorType,x-amzn-Trace-id,x-amzn-Apigw-id,x-amzn-ErrorMessage,Date",
        "recordArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/jzjXulIwVksK/record/QamdREmPPkNr",
        "status": "CREATING"
    },
    "requestID": "12345678-1234-1234-1234-123456789012",
    "eventID": "12345678-1234-5678-9abc-123456789012",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "sessionCredentialFromConsole": "true"
}
```

# IAM Permissions
IAM Permissions

## Registry actions


For an identity to be able to create, manage, or use Registries, you need to attach an identity-based policy to the IAM identity to allow it to perform [Amazon Bedrock AgentCore-related actions](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrockagentcore.html) . For comprehensive permissions, you can use the [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html) managed policy.

For greater security and control, you can create your own custom policy by reducing the permissions in the full access policy.

## Registry control plane actions



| Action | Description | Access level | 
| --- | --- | --- | 
|   `bedrock-agentcore:CreateRegistry`   |  Grants permission to create a registry  |  Write  | 
|   `bedrock-agentcore:GetRegistry`   |  Grants permission to get a registry  |  Read  | 
|   `bedrock-agentcore:UpdateRegistry`   |  Grants permission to update a registry  |  Write  | 
|   `bedrock-agentcore:DeleteRegistry`   |  Grants permission to delete a registry  |  Write  | 
|   `bedrock-agentcore:ListRegistries`   |  Grants permission to list registries  |  List  | 

## Registry record control plane actions



| Action | Description | Access level | 
| --- | --- | --- | 
|   `bedrock-agentcore:CreateRegistryRecord`   |  Grants permission to create a registry record  |  Write  | 
|   `bedrock-agentcore:GetRegistryRecord`   |  Grants permission to get a registry record  |  Read  | 
|   `bedrock-agentcore:UpdateRegistryRecord`   |  Grants permission to update a registry record  |  Write  | 
|   `bedrock-agentcore:DeleteRegistryRecord`   |  Grants permission to delete a registry record  |  Write  | 
|   `bedrock-agentcore:ListRegistryRecords`   |  Grants permission to list registry records  |  List  | 
|   `bedrock-agentcore:SubmitRegistryRecordForApproval`   |  Grants permission to submit a registry record for approval  |  Write  | 
|   `bedrock-agentcore:UpdateRegistryRecordStatus`   |  Grants permission to approve, reject, or deprecate a registry record  |  Write  | 

## Registry data plane actions



| Action | Description | Access level | 
| --- | --- | --- | 
|   `bedrock-agentcore:SearchRegistryRecords`   |  Grants permission to search registry records  |  Read  | 
|   `bedrock-agentcore:InvokeRegistryMcp`   |  Grants permission to invoke the registry MCP endpoint  |  Read  | 

**Note**  
For Invoking the MCP Server, you will need both SearchRegistryRecords and InvokeRegistryMcp IAM Permissions.

## Registry resource types


The following resource types are defined for AWS Agent Registry:


| Resource type | ARN format | 
| --- | --- | 
|  Registry  |   `arn:aws:bedrock-agentcore:{region}:{account}:registry/{registryId}`   | 
|  Registry record  |   `arn:aws:bedrock-agentcore:{region}:{account}:registry/{registryId}/record/{recordId}`   | 

# Troubleshooting
Troubleshooting

## Schema validation errors


When creating different types of records, you may see validation exception for the descriptors. See [Supported record types](registry-supported-record-types.md) section for valid schemas.

Common errors:
+ "Schema version '0.3.0' is not supported for descriptor type 'a2a'." — The schemaVersion field value should be `0.3` instead of `0.3.0` . This aligns with the [official A2A protocol version description](https://a2a-protocol.org/latest/specification/#446-agentinterface) : "Use the latest supported minor version per major version".
+ "Schema validation failed: content is not in compliance with schema version '0.3' for descriptor type 'a2a'." — You can find the schema on [Supported record types](registry-supported-record-types.md) . Note that the content will be validated against \$1/definitions/AgentCard in the json schema.

## Record synchronization errors


When you create or update record using synchronization feature, the record may transition to CREATE\$1FAILED or UPDATE\$1FAILED status, with a `statusReason` explaining what happened.

At high level, errors can be categorized as: permission errors, connection errors, validation errors, and server side errors.

### Permission errors


Synchronization configuration is wrong or expired:
+ "Unable to connect to MCP server because caller credentials have expired." — the caller of the create or update API has expired credentials. You can retry with UpdateRegistryRecord API again.
+ "Received exception from GetWorkloadAccessToken API: <detailed message>" — registry calls [GetWorkloadAccessToken](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessToken.html) API on-behalf-of the caller. Refer to the detailed message to learn about the error. Refer to [Synchronize records from external sources](registry-sync-records.md) if you see access denied exception.
+ "Unable to parse credential provider ARN: <arn>" — malformed credential provider ARN. This must be a valid [credential provider](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html) ARN created from AgentCore Identity.
+ "Received exception from GetResourceOauth2Token API: <detailed message>" — registry calls [GetResourceOauth2Token](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html) API on-behalf-of the caller. Refer to the detailed message to learn about the error. Refer to [Synchronize records from external sources](registry-sync-records.md) if you see access denied exception.
+ "Unable to assume the provided IAM role for MCP server authorization." — registry calls AssumeRole API on-behalf-of the caller. Refer to [Synchronize records from external sources](registry-sync-records.md) for the expected IAM permissions, e.g. caller must have `iam:PassRole` permission.

### Connection errors


Can’t reach the server:
+ "Failed to fetch agent card from URL: %s" — A2A IOException
+ "MCP server returned HTTP <code>" — non-200/202 HTTP response from the MCP server. Please check if the URL is correct and the MCP server can be connected.
+ "The provided URL resolves to a non-public IP address" — Registry only supports connecting to public IP address servers.
+ "Failed to connect to MCP server" — IOException/connection failure
+ "Invalid MCP server URL" — malformed URL
+ "Failed to initialize MCP connection" — initialize request exception
+ "Failed to send initialized notification" — notification exception
+ "Failed to list tools from MCP server" — tools/list exception
+ "MCP server tools/list pagination timed out" — registry only supports at most 30 seconds when paginating tools from MCP server. Contact AWS support if your MCP server needs more time for synchronization.

### Validation errors


Server responded but content is not supported:
+ "Failed to parse agent card JSON" — A2A content empty or malformed JSON
+ "Agent card exceeds maximum size limit" — A2A response too large
+ "Failed to parse MCP server response JSON" — MCP content empty or malformed
+ "MCP server returned invalid response: missing result" — MCP JSON-RPC missing result
+ "MCP server response exceeds maximum allowed size" — MCP response too large
+ "Descriptor type %s does not support URL synchronization" — unsupported descriptor type

### Server side errors

+ "Unknown error" — This is a server side error. Please retry later or contact AWS support for help.