# 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
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
## 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 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 \
--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='',
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 "" \
--region us-east-1
```
### AWS SDK
```
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.list_registry_records(
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 "" \
--record-id "" \
--region us-east-1
```
### AWS SDK
```
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.get_registry_record(
registryId='',
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 "" \
--record-id "" \
--description "Updated description" \
--region us-east-1
```
### AWS SDK
```
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.update_registry_record(
registryId='',
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 "" \
--record-id "" \
--region us-east-1
```
### AWS SDK
```
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.submit_registry_record_for_approval(
registryId='',
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 "" \
--record-id "" \
--region us-east-1
```
### AWS SDK
```
import boto3
client = boto3.client('bedrock-agentcore-control')
response = client.delete_registry_record(
registryId='',
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
## 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='',
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:*::workload-identity-directory/*"
]
},
{
"Effect": "Allow",
"Action":
[
"bedrock-agentcore:GetResourceOauth2Token"
],
"Resource":
[
"arn:aws:bedrock-agentcore:*::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:::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='',
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).