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.

Step 1: Create a registry

Create a registry with IAM authorization and manual approval.

Console

To Create a Registry with IAM based Auth

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.

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.

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.

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 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

To submit a record for approval from the record details page

After you submit a record for approval, the record status changes based on the registry’s approval setting:

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_APPROVAL (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

To approve a record from the record details page

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.

To search for registry records

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

Next steps