Why and How to Connect Claude Code to AgentCore Registry ?

The real problem is no more building AI agents — it's now making them discoverable, governed, and reusable across your organization.

If you're using Claude Code in your team, you've probably built custom skills, connected MCP servers, maybe even written agents that automate parts of your workflow. And it works. But what happens when your organization has ten teams doing the same thing?

The Why

Everyone builds, nobody shares

One team builds an MCP server to query the internal database. Another creates a deployment agent. Your QA team formalizes a test-driven development skill. Each of these resources is excellent — but nobody outside the team that created it knows it exists. We reinvent the wheel in every silo, we duplicate efforts, we can't govern what's being used or by whom, and when a developer without an AWS account needs access to these tools, there's simply no path.

This is agent sprawl — and if you've worked with Claude Code across multiple teams, you've seen it happening. The same specialization problem that deep agents solve at the intra-agent level now resurfaces at the organizational level.

If this scenario sounds familiar, that's normal. We've already lived through the exact same story with data.

Data as a Product, Agent as a Product

A few years ago, the Data Mesh movement formalized a concept that transformed the way organizations handle their data: Data as a Product. The idea was simple — every dataset produced by a team should be treated as a product in its own right, with an owner, documentation, quality guarantees, and a discovery mechanism. Before Data Mesh, data lived in silos, every team had its own copy of reality, and nobody really knew what existed or whether it was reliable.

We are at exactly the same point with AI agents and their tools. MCP servers, skills, agents — these are the datasets of the agentic era. And just as data products needed a centralized catalog (a data catalog), agentic resources need a registry.

In machine learning, Model Cards were introduced to document in a standardized way what a model does, its limitations, its biases, and its usage conditions. AgentCore Registry applies this same principle with what we could call Agent Cards and Skill Cards — structured metadata that precisely describes what an agent or skill does, how to use it, and under what conditions. A record in the registry is fundamentally a Model Card for the age of agents: a trust contract between producer and consumer.

This is precisely what AWS Bedrock AgentCore Registry solves — addressing discoverability, governance, and access for users outside the AWS ecosystem all at once.

A registry Claude Code can query directly

AgentCore Registry is a centralized, managed catalog that lets you publish, organize, govern, and discover four types of resources: MCP servers (with MCP schema validation), A2A agents (with Agent-to-Agent schema validation), skills (reusable capabilities documented in markdown), and custom resources (with a free-form JSON schema).

What makes the service particularly interesting for enterprise adoption is that it exposes each registry as a native MCP endpoint. In other words, any MCP client — Claude Code, Kiro, or your custom agent — can connect directly to the registry and search for available resources, without complex configuration. The endpoint exposes a search_registry_records tool that accepts natural language queries with a hybrid search system combining semantic and keyword matching.

On the authorization side, the registry supports two modes: AWS IAM (for teams already in the AWS ecosystem) and JWT via a corporate identity provider — Amazon Cognito, Okta, Microsoft Azure AD, or any OAuth 2.0-compatible provider. It's this second option that interests us in this guide, because it allows developers without an AWS account to access the registry with their corporate credentials.

The governance workflow follows a Publisher/Curator/Consumer model: a Publisher submits a record, a Curator reviews and approves (or rejects) it, and only approved records become visible. For development environments, an auto-approval mode allows bypassing the manual review.

The How

Now that we know why we need a registry, let's connect Claude Code to one. What follows is a complete, tested and functional guide — from creating the registry to searching skills directly from Claude Code. Every command has been executed and verified.

Prerequisites

We need AWS CLI v2.34 or higher (the registry commands are not available in earlier versions), an AWS profile with IAM permissions for Cognito and AgentCore, and Claude Code installed.

We start by exporting the AWS profile to use — all commands in this guide rely on it:

export AWS_PROFILE=<your-profile>
export AWS_REGION=us-east-1  # if the region isn't already configured in your profile

To verify that your CLI is up to date and the registry commands are available:

aws --version
# aws-cli/2.34.28 or higher

aws bedrock-agentcore-control create-registry help
# Should display the command help, not an error

If create-registry isn't recognized, update your CLI. The procedure depends on your OS — the official documentation covers all cases. On macOS for example:

curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Step 1 — Configure the identity provider

In most organizations, an SSO is already in place — Okta, Azure AD, or an existing Cognito User Pool. The AgentCore registry accepts any OAuth 2.0 / OIDC-compatible identity provider. It just needs the provider to expose a /.well-known/openid-configuration endpoint so the registry can validate JWTs. If you already have an IdP, you can skip directly to step 2 with the discoveryUrl and clientId of your existing provider.

For details on supported providers, the AgentCore Identity documentation covers Okta, Azure AD, and Cognito configurations.

In this guide, we create a Cognito User Pool from scratch for a self-contained and reproducible setup.

USER_POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name "agentcore-registry-pool" \
  --auto-verified-attributes email \
  --username-attributes email \
  --deletion-protection ACTIVE \
  --admin-create-user-config AllowAdminCreateUserOnly=true \
  --query 'UserPool.Id' \
  --output text)

echo "User Pool ID: $USER_POOL_ID"

Next, we create the managed Cognito domain. This is the URL where users will be redirected to authenticate:

aws cognito-idp create-user-pool-domain \
  --domain "my-registry" \
  --user-pool-id "$USER_POOL_ID"

The domain will be accessible at https://my-registry.auth.us-east-1.amazoncognito.com.

Step 2 — Create the OAuth App Client

This is the step that requires the most attention. We create a public OAuth client (without a secret) compatible with the authorization code flow that Claude Code will use. Two critical points not to miss.

The --no-generate-secret flag is essential: Claude Code acts as a public client (it can't securely store a secret), so the Cognito client must not have a secret.

The scopes must include all standard OIDC scopes that Cognito supports: openid, email, profile, and phone. This is related to a known Claude Code bug that doesn't transmit the scope parameter in the OAuth request. Cognito then rejects with invalid_scope if the client doesn't have all scopes pre-authorized.

CLIENT_ID=$(aws cognito-idp create-user-pool-client \
  --user-pool-id "$USER_POOL_ID" \
  --client-name "claude-code-registry-client" \
  --no-generate-secret \
  --explicit-auth-flows ALLOW_USER_SRP_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --allowed-o-auth-flows code \
  --allowed-o-auth-scopes openid email profile phone \
  --allowed-o-auth-flows-user-pool-client \
  --callback-urls '["http://localhost:4999/callback"]' \
  --supported-identity-providers COGNITO \
  --query 'UserPoolClient.ClientId' \
  --output text)

echo "Client ID: $CLIENT_ID"

The port 4999 in the callback URL isn't arbitrary: Cognito doesn't allow specifying a port range in redirect URIs, so we fix a specific port that will also be configured on the Claude Code side.

Step 3 — Create the AgentCore Registry

We now create the registry with a JWT authorizer pointing to Cognito's OIDC discovery endpoint. The discoveryUrl allows the registry to automatically retrieve the public keys to validate JWT tokens.

REGISTRY_ARN=$(aws bedrock-agentcore-control create-registry \
  --name "skills-registry" \
  --description "Centralized registry for agent skills" \
  --authorizer-type CUSTOM_JWT \
  --authorizer-configuration '{
    "customJWTAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/'"$USER_POOL_ID"'/.well-known/openid-configuration",
      "allowedClients": ["'"$CLIENT_ID"'"]
    }
  }' \
  --approval-configuration autoApproval=true \
  --query 'registryArn' \
  --output text)

REGISTRY_ID=$(echo "$REGISTRY_ARN" | awk -F/ '{print $NF}')
echo "Registry ID: $REGISTRY_ID"

The registry transitions to CREATING status for a few minutes. We can monitor its state:

aws bedrock-agentcore-control get-registry \
  --registry-id "$REGISTRY_ID" \
  --query 'status' \
  --output text

We wait until the status changes to READY before continuing.

Step 4 — Publish a skill

A skill in the registry is a reusable prompt describing a specific competency, a specific way of behaving, in markdown — it's the simplest format to test with.

Let's imagine a very simple SKILL.md file containing our test-driven development skill:

---
name: test-driven-development
description: Drives development with tests. Use when implementing logic, fixing bugs, or changing behavior.
---

# Test-Driven Development

Write a failing test before writing the code that makes it pass...

We publish it to the registry with the AGENT_SKILLS descriptor type:

RECORD_ARN=$(aws bedrock-agentcore-control create-registry-record \
  --registry-id "$REGISTRY_ID" \
  --name "test-driven-development" \
  --description "Drives development with tests. Use when implementing new logic, fixing bugs, or changing behavior." \
  --descriptor-type AGENT_SKILLS \
  --descriptors '{"agentSkills": {"skillMd": {"inlineContent": "# Test-Driven Development\n\nWrite a failing test before writing the code that makes it pass..."}}}' \
  --record-version "1.0.0" \
  --query 'recordArn' \
  --output text)

RECORD_ID=$(echo "$RECORD_ARN" | awk -F/ '{print $NF}')
echo "Record ID: $RECORD_ID"

The inlineContent field accepts the skill's markdown content as a single string with \n for line breaks. For longer skills, you can of course use --cli-input-json.

The record is created in DRAFT status. Even with auto-approval enabled, you have to explicitly submit it for approval — the "auto" means it will be approved automatically without manual review, not that it skips the submission step:

aws bedrock-agentcore-control submit-registry-record-for-approval \
  --registry-id "$REGISTRY_ID" \
  --record-id "$RECORD_ID"

The status goes directly to APPROVED. The skill is now discoverable.

Step 5 — Create a test user

We can now create a test user:

aws cognito-idp admin-create-user \
  --user-pool-id "$USER_POOL_ID" \
  --username test@example.com \
  --user-attributes Name=email,Value=test@example.com Name=email_verified,Value=true \
  --temporary-password "TempPass123!"

Step 6 — Configure Claude Code

We now create a .mcp.json file at the project root, reusing the variables captured earlier. The registry will then be available only in this project. If you want the registry to be accessible across all projects (which is often the case — the skills catalog is cross-cutting), place the same configuration in ~/.claude.json at the user level:

cat > .mcp.json <<EOF
{
  "mcpServers": {
    "agentcore-skills-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.us-east-1.amazonaws.com/registry/$REGISTRY_ID/mcp",
      "oauth": {
        "clientId": "$CLIENT_ID",
        "callbackPort": 4999
      }
    }
  }
}
EOF

The oauth field with clientId and callbackPort tells Claude Code to use the OAuth authorization code grant flow. On launch, Claude Code detects that authentication is needed, opens the browser to the Cognito login page, and retrieves the JWT token after authentication.

Step 7 — Test the connection

We restart Claude Code in the project (or use the /mcp command to refresh MCP connections). The agentcore-skills-registry server appears with a "needs authentication" status. We select "Authenticate", the browser opens, we log in with our Cognito credentials, and the connection is established.

Once connected, the search_registry_records tool is available, and there we go. We can search for published skills in natural language:

> What skills are available in the registry?

Claude Code calls search_registry_records with the query and returns the TDD skill with all its markdown content, description, version, and status.

We can also use the skill directly in a work context — here, Claude Code retrieves the TDD skill from the registry and applies it:

Pitfalls to watch out for

This setup looks simple once you know the right values, but a few mistakes can cost you time.

AWS CLI < 2.34 — the create-registry commands simply don't exist, and the error message (Found invalid choice) doesn't mention that you need to update. You might think the service isn't available in your region.

Cognito client secret — --generate-secret (the default in some workflows) silently breaks the OAuth flow. Claude Code is a public client: --no-generate-secret is mandatory.

OIDC scopes — openid alone isn't enough. You need to pre-authorize email, profile, and phone because of the Claude Code bug that doesn't transmit the scope parameter.

update-registry JSON — Unlike create-registry, update-registry requires an optionalValue wrapper around customJWTAuthorizer. Easy to miss if you modify the config after the fact.

DRAFT status — autoApproval=true bypasses manual review, not submission. You always need to call submit-registry-record-for-approval.

The Registry in the AgentCore ecosystem

The Registry doesn't live alone — it integrates into the full Bedrock AgentCore suite: Runtime (serverless deployment), Gateway (APIs and third-party services exposed as MCP), Identity (authentication and credentials), Memory (contextual persistence), Policy (Cedar guardrails), and Observability (OpenTelemetry tracing).

The Registry is the cross-cutting discovery layer that connects them all.

An agent deployed on Runtime can query the Registry to find tools available via Gateway. Identity secures access to the Registry and provides credentials to synchronize metadata from remote MCP servers. Policy governs who has access to what. Everything is traced by Observability.

This integration is what elevates AgentCore from a collection of services to an enterprise platform. And the fact that the Registry is a standard MCP endpoint opens the door to agents that dynamically discover available tools in the organization and invoke them — without any prior configuration.

What's next?

This guide covers the simplest case — a skill published in a registry with Cognito authentication. But the registry supports many other scenarios.

You can publish MCP servers with automatic synchronization: the registry periodically retrieves metadata from the remote MCP endpoint and updates the record, ensuring the catalog stays up to date without manual intervention. You can also configure approval workflows via EventBridge to integrate the registry into the organization's existing review processes — a submitted record can trigger a Jira ticket, a Slack notification, or a Step Functions pipeline.

For other identity providers (Okta, Azure AD), the setup is virtually identical — you replace the discoveryUrl as mentioned in step 1. Dynamic Client Registration (DCR) simplifies the configuration even further: no need to specify a clientId in the .mcp.json anymore, the client registers itself automatically. The MCP endpoint documentation details the configurations for each provider.

Just as the data catalog became a prerequisite for data-driven organizations (for those that truly are), the agent registry is becoming the foundation of agent-driven organizations. The difference is that this time, the consumers are not just humans — they're also agents.