AWS Agent Registry Tutorial: Register, Approve, Audit

If you’ve been bolting together spreadsheets and Slack threads to track which agents, MCP servers, and internal tools your teams have quietly spun up, this AWS Agent Registry tutorial is for you. AWS Agent Registry went generally available this month, and it’s exactly what it sounds like: a private, governed catalog where you register agents, tools, skills, and MCP servers, gate them behind approval workflows, and search the whole thing with either plain keywords or semantic queries. GA also bolts on AWS CloudTrail logging for every registry action, so “who approved this agent to touch production” finally has an answer that isn’t “ask around the Slack channel and hope.” Read the GA announcement if you want the official feature list — here we’re registering something real, wiring up an approval workflow, searching for it two different ways, and pulling the audit trail to prove it all happened.

Before you touch a command, get the basics lined up:

• An AWS account with administrative access, or an IAM principal scoped to the permissions below
• AWS CLI v2 installed and configured, either via aws configure or an SSO profile
• An IAM role or user with agentregistry:* and cloudtrail:LookupEvents permissions attached
• A region where AWS Agent Registry is generally available, per the GA announcement
• An existing MCP server or agent endpoint worth registering — we’re using a sample internal finance MCP server

1. Step 1: Register your first agent or MCP server in AWS Agent Registry

   First, attach an IAM policy that lets your role manage registry records. Nothing exotic — standard least-privilege JSON, scoped to what you actually need instead of a lazy wildcard admin grant. See the IAM user guide if policy syntax is rusty.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AgentRegistryFullAccess",
         "Effect": "Allow",
         "Action": [
           "agentregistry:CreateAgentRecord",
           "agentregistry:CreateApprovalWorkflow",
           "agentregistry:UpdateApprovalWorkflow",
           "agentregistry:ApproveAgentRecord",
           "agentregistry:SearchCatalog",
           "agentregistry:GetAgentRecord",
           "agentregistry:ListAgentRecords"
         ],
         "Resource": "*"
       },
       {
         "Sid": "AuditReadAccess",
         "Effect": "Allow",
         "Action": ["cloudtrail:LookupEvents"],
         "Resource": "*"
       }
     ]
   }
   

   Save that as agent-registry-policy.json and attach it:

   aws iam put-role-policy \
     --role-name AgentRegistryAdminRole \
     --policy-name AgentRegistryAccess \
     --policy-document file://agent-registry-policy.json
   

   Now register the MCP server. GA supports both manual field entry and URL-based creation, where the registry crawls the endpoint’s manifest and imports tool definitions automatically. We’ll go manual so every field is explicit and auditable from day one:

   aws agent-registry create-agent-record \
     --name "invoice-reconciliation-mcp" \
     --resource-type MCP_SERVER \
     --description "Internal MCP server exposing invoice lookup, reconciliation, and ERP write-back tools" \
     --endpoint-url "https://mcp.internal.example.com/invoice-recon" \
     --owner-team "finance-platform" \
     --tags Key=environment,Value=production Key=criticality,Value=high \
     --metadata-source URL
   

   The response comes back PENDING_REVIEW, not ACTIVE:

   {
     "agentRecordId": "agt-0x8f42d9b1c7e4a3f",
     "name": "invoice-reconciliation-mcp",
     "status": "PENDING_REVIEW",
     "createdAt": "2026-09-13T15:02:11Z"
   }
   

   That’s the whole point of a governed catalog — nothing goes live and discoverable org-wide until someone with actual authority signs off. No more “someone deployed a tool with write access to the ERP and nobody noticed for three weeks.”

2. Step 2: Configure an approval workflow

   A registry with no gatekeeping is just a wiki with extra steps. Route new records from a given team to the right reviewers, and require every one of them to sign off before the record activates:

   aws agent-registry create-approval-workflow \
     --name "finance-agent-approval" \
     --applies-to-tag Key=owner-team,Value=finance-platform \
     --approvers "arn:aws:iam::123456789012:role/FinancePlatformLead" \
                 "arn:aws:iam::123456789012:role/SecurityReviewer" \
     --approval-mode ALL_REQUIRED \
     --auto-expire-days 90
   

   Notice auto-expire-days. Approvals that live forever are how a “temporary staging agent” ends up running unreviewed in production two years later. Force a re-approval cadence and thank yourself later. Once the workflow exists, a reviewer records the actual decision:

   aws agent-registry approve-agent-record \
     --agent-record-id agt-0x8f42d9b1c7e4a3f \
     --workflow-id wf-3a91cc02 \
     --decision APPROVE \
     --comment "Reviewed scopes, least-privilege confirmed, ERP write-back restricted to sandbox account"
   

   That comment field isn’t decorative. It becomes part of the permanent record, and it’s exactly what shows up later when someone asks why this thing was allowed anywhere near production data.



3. Step 3: Search the catalog with keyword and semantic queries

   This is where AWS Agent Registry earns its keep over a spreadsheet. Keyword search behaves like you’d expect — exact and fuzzy matches against names, descriptions, and tags:

   aws agent-registry search-catalog \
     --query "invoice reconciliation" \
     --search-type KEYWORD \
     --max-results 10
   

   Semantic search is the more interesting party trick. You don’t need to know the tool’s registered name — describe the capability in plain language, and the registry’s embeddings-based index finds the closest match even when the wording never appears in the record:

   aws agent-registry search-catalog \
     --query "something that can match ERP invoices against bank statements automatically" \
     --search-type SEMANTIC \
     --max-results 10
   

   That’s the difference between an engineer three teams over finding your finance MCP server in ten seconds, versus filing a ticket asking whether anyone already built this.

4. Step 4: Pull the CloudTrail audit trail for a registry event

   Every create, approve, search, and update against the registry lands in CloudTrail Event History as a management event. That’s the enterprise piece GA bolted onto preview: a real, immutable paper trail instead of a changelog nobody updates. Pull everything the registry logged for a given window:

   aws cloudtrail lookup-events \
     --lookup-attributes AttributeKey=EventSource,AttributeValue=agentregistry.amazonaws.com \
     --start-time "2026-09-13T00:00:00Z" \
     --end-time "2026-09-14T00:00:00Z" \
     --max-results 20
   

   Or narrow it to a single record — what you’ll actually do during an incident review or compliance audit:

   aws cloudtrail lookup-events \
     --lookup-attributes AttributeKey=ResourceName,AttributeValue=agt-0x8f42d9b1c7e4a3f
   

   Each event includes the calling identity, timestamp, source IP, and full request parameters — meaning your approval comment from Step 2 is sitting right there in the payload. For teams under SOC 2 or similar frameworks, that’s the artifact an auditor actually wants, not a screenshot of a Confluence page. For more on filtering and retention, check the CLI reference for lookup-events, and see AWS’s own writeup on managing agents, tools, and skills at scale with AWS Agent Registry for the broader governance model.

What you built: You now have a registered, tagged MCP server sitting in a governed catalog instead of floating around as a URL in someone’s DMs. It’s gated behind a real approval workflow with named reviewers and an expiration date, discoverable by anyone in the org through keyword or semantic search, and every action against it — creation, approval, lookup — is captured in CloudTrail with enough detail to satisfy an auditor or answer an incident commander’s questions at 2 AM. That’s a governance layer for agentic AI that didn’t exist eighteen months ago, running on infrastructure your team already trusts.

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. We’ve stood up agent governance layers like this one for clients who needed a real audit trail before their security team would sign off on a single production agent. If you’d rather have seasoned cloud people handle it instead of learning the hard way at 2 AM, let’s talk. 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.