Book a call
,

AWS Agent Registry GA: Under the Hood + Setup Guide

Jorge Vazquez
Illustration: AWS Agent Registry GA architecture and setup

AWS Agent Registry just went generally available, and if you’ve spent the last year watching agents, tools, and random MCP servers multiply across your org like rabbits, this is the part where AWS finally gives you a leash. It’s a private, governed catalog for agents, tools, skills, MCP servers, and custom resources — and GA bolts on the stuff preview was missing: approval workflows, semantic search, and CloudTrail audit trails. This is not the “why governance matters” article. This is the “how the thing actually works, and how you register something real” article.

What AWS Agent Registry Actually Models

Under the hood, every entry in the registry is a resource record — a structured, versioned object with a type, a schema, ownership metadata, and a lifecycle status. Resource types at GA include AGENT, TOOL, SKILL, MCP_SERVER, and CUSTOM. That last bucket exists because half your org’s “agent stuff” won’t fit neatly into the first four, and AWS knows it.

Each record carries a fixed envelope (ID, ARN, owner, tags, status) plus a type-specific metadata blob. For an MCP server, that blob includes the transport (stdio, HTTP, or Streamable HTTP), the endpoint or connection command, the tool/resource capabilities it exposes, and an auth model. Here’s roughly what a record looks like once it’s active:

{
  "recordId": "mcp-server-internal-jira-mcp-a1b2c3",
  "resourceType": "MCP_SERVER",
  "arn": "arn:aws:agentregistry:us-east-1:123456789012:record/mcp-server-internal-jira-mcp-a1b2c3",
  "name": "internal-jira-mcp",
  "status": "ACTIVE",
  "ownerTeam": "platform-eng",
  "createdBy": "arn:aws:iam::123456789012:user/jvazquez",
  "version": "1.2.0",
  "metadata": {
    "transport": "streamable-http",
    "endpointUrl": "https://mcp.internal.example.com/jira",
    "authType": "IAM_SIGV4",
    "capabilities": {
      "tools": ["create_ticket", "search_tickets", "update_status"],
      "resources": ["jira://projects/{key}"]
    }
  },
  "tags": { "env": "prod", "criticality": "high" }
}

That schema is what makes the registry more than a fancy spreadsheet: it’s machine-readable enough that Amazon Bedrock AgentCore runtimes, or any orchestrator you’ve hand-rolled, can query the catalog at runtime and bind to a tool without a human copy-pasting an endpoint URL into a YAML file at 4 PM on a Friday.

Approval Workflow Mechanics in AWS Agent Registry

Preview let you create records manually. GA adds real governance: a record can require one or more approval stages before it flips from PENDING_REVIEW to ACTIVE. Workflows are defined declaratively and attached per resource type, so your security team can require a review on every MCP_SERVER record without touching how SKILL records get approved.

A workflow definition looks like this:

{
  "workflowName": "mcp-server-approval",
  "resourceType": "MCP_SERVER",
  "stages": [
    {
      "stageName": "security-review",
      "approverGroup": "arn:aws:iam::123456789012:group/SecurityReviewers",
      "requiredApprovals": 1
    },
    {
      "stageName": "platform-review",
      "approverGroup": "arn:aws:iam::123456789012:group/PlatformOwners",
      "requiredApprovals": 1
    }
  ],
  "onApproval": { "setStatus": "ACTIVE", "publishToCatalog": true },
  "onRejection": {
    "setStatus": "REJECTED",
    "notify": ["arn:aws:sns:us-east-1:123456789012:agent-registry-notifications"]
  }
}

Stages run in order — nobody on the platform team sees a record until security clears it. Each approval or rejection is itself an API call (ApproveRecord / RejectRecord), scoped by IAM to members of the approver group, which means you enforce “who can bless an MCP server” the same way you enforce everything else in AWS: policy, not tribal knowledge living in someone’s head.

Semantic and Keyword Search Indexing

Here’s the part that actually makes the catalog usable instead of just auditable. AWS Agent Registry indexes every record two ways: a traditional keyword index (name, tags, description) and a semantic embedding built from the record’s description and capability metadata. Search a phrase like “something that can file a support ticket” and semantic search will surface your Jira MCP server even though the word “ticket” never appears in its tags.

aws agent-registry search-records \
  --query "agent that can summarize customer support tickets" \
  --search-type SEMANTIC \
  --resource-types MCP_SERVER,SKILL \
  --max-results 10

Keyword search still exists for when you know exactly what you want:

aws agent-registry search-records \
  --query "name:internal-jira-mcp" \
  --search-type KEYWORD

This is the difference between a registry and a graveyard. A pile of unsearchable JSON blobs in S3 is not discovery — it’s just storage with extra steps. Semantic indexing is what turns “governed catalog” from a compliance checkbox into something engineers actually open before building yet another duplicate tool.

Illustration: AWS Agent Registry GA architecture and setup

The CloudTrail Audit Trail Schema

Every mutating call against the registry — create, approve, reject, deprecate, delete — lands in AWS CloudTrail under the agentregistry.amazonaws.com event source. That’s not a bolt-on feature; it’s the whole point of putting this in AWS instead of a wiki page. A typical approval event looks like this:

{
  "eventVersion": "1.09",
  "eventTime": "2026-09-14T18:22:07Z",
  "eventSource": "agentregistry.amazonaws.com",
  "eventName": "ApproveRecord",
  "awsRegion": "us-east-1",
  "userIdentity": {
    "type": "IAMUser",
    "principalId": "AIDAEXAMPLE123",
    "arn": "arn:aws:iam::123456789012:user/security-reviewer",
    "accountId": "123456789012"
  },
  "requestParameters": {
    "recordId": "mcp-server-internal-jira-mcp-a1b2c3",
    "stageName": "security-review",
    "decision": "APPROVED"
  },
  "responseElements": { "newStatus": "PENDING_PLATFORM_REVIEW" },
  "resources": [
    {
      "accountId": "123456789012",
      "type": "AWS::AgentRegistry::Record",
      "ARN": "arn:aws:agentregistry:us-east-1:123456789012:record/mcp-server-internal-jira-mcp-a1b2c3"
    }
  ]
}

Because it’s standard CloudTrail, you get everything that implies for free: routing to an S3 trail, querying with Athena, alerting through EventBridge on specific event names, and feeding it into whatever SIEM your security team already trusts. If an auditor asks “who approved the agent that has write access to our CRM,” the answer isn’t “let me check Slack” — it’s a CloudTrail Lake query.

Walkthrough: Registering an Existing MCP Server

Say you’ve already got an internal MCP server running for Jira, and you want it discoverable and governed instead of living in three different .env files. First, create the record:

aws agent-registry create-record \
  --resource-type MCP_SERVER \
  --name "internal-jira-mcp" \
  --description "Internal Jira ticket MCP server for engineering agents" \
  --owner-team "platform-eng" \
  --tags Key=env,Value=prod Key=criticality,Value=high \
  --metadata file://mcp-metadata.json

Where mcp-metadata.json holds the transport, endpoint, auth model, and capability list shown earlier. Submitting the record automatically kicks off any workflow bound to MCP_SERVER resources:

aws agent-registry get-record --record-id mcp-server-internal-jira-mcp-a1b2c3
# status: PENDING_REVIEW -> stageName: security-review

Once security and platform approvers sign off, the record flips to ACTIVE and gets indexed for both keyword and semantic search. Any AgentCore-hosted agent — or anything else with the right IAM permissions — can now resolve it:

aws agent-registry get-record \
  --record-id mcp-server-internal-jira-mcp-a1b2c3 \
  --query 'metadata.endpointUrl'

Lock this down with IAM the same way you’d lock down anything else — scope agent-registry:GetRecord and agent-registry:SearchRecords to the roles that actually need catalog read access, and keep CreateRecord/ApproveRecord restricted to the teams responsible for those actions. Check the IAM user guide if you need a refresher on scoping resource-level permissions by ARN pattern.

Why This Matters More Than It Sounds

None of this is glamorous. It’s a catalog with a review process and an audit log — the least sexy sentence you can write about “AI infrastructure.” But that’s exactly the point: agents and MCP servers have been sprawling across orgs with zero central inventory, and “zero central inventory” is how you end up explaining to an auditor why nobody knows which agent has write access to production data. AWS Agent Registry doesn’t make your agents smarter. It makes them accountable, which, once you’ve lived through an incident review, you’ll take every time.

Check the AWS Weekly Roundup and the GA announcement for the full feature list, and keep an eye on the AWS ML blog’s deep dive on managing agents, tools, and skills at scale for more on how this pairs with AgentCore in bigger deployments.

At Enkompass (enkompass.net), this is our home turf. We design AWS architectures that survive contact with production — and the 3 AM page that comes with it. If you’d rather have seasoned cloud people handle it instead of learning the hard way at 2 AM, let’s talk. We’ve wired up approval workflows and IAM-scoped registry access for teams who’d otherwise be tracking their MCP servers in a shared Google Doc. Reach out through our contact page or call us directly at +1-828-436-5667 — we’ll help you turn this from a someday-project into a done-deal.

Ready when you are

Let’s map your route to AWS

A free 60-minute architecture review with a senior engineer. No slides, no SDR, just a plan.

Book a cloud review
See the work