Comment Connecter Claude Code à AgentCore Registry ?

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

Tout le monde build, personne ne partage

La plupart des équipes ont intégré des agents IA dans leur workflow quotidien — Claude Code, GitHub Copilot, Cursor, agents internes. Les outils sont là, ils fonctionnent, et la productivité est réelle. Mais un problème s'installe dans les organisations qui grandissent : l'agent sprawl.

L'équipe IT développe un MCP server pour interroger la base de données interne. L'équipe platform crée un agent qui automatise les déploiements. L'équipe QA formalise un skill de test-driven development. Chacune de ces ressources est excellente — mais personne en dehors de l'équipe qui l'a créée ne sait qu'elle existe. On réinvente la roue dans chaque silo, on duplique les efforts, on ne peut pas gouverner ce qui est utilisé ni par qui, et quand un consultant externe ou un développeur sans compte AWS a besoin d'accéder à ces outils, il n'y a tout simplement pas de chemin.

Si ce scénario vous rappelle quelque chose, c'est normal. On a déjà vécu exactement la même histoire avec les données.

Data as a Product, Agent as a Product

Il y a quelques années, le mouvement Data Mesh a formalisé un concept qui a transformé la manière dont les organisations traitent leurs données : Data as a Product. L'idée était simple — chaque dataset produit par une équipe devait être traité comme un produit à part entière, avec un propriétaire, une documentation, des garanties de qualité, et un mécanisme de découverte. Avant le Data Mesh, les données vivaient dans des silos, chaque équipe avait sa propre copie de la réalité, et personne ne savait réellement ce qui existait ni si c'était fiable.

Nous en sommes exactement au même point avec les agents IA et leurs outils. Les MCP servers, les skills, les agents — ce sont les datasets de l'ère agentique. Et tout comme les data products avaient besoin d'un catalogue centralisé (un data catalog), les ressources agentiques ont besoin d'un registry.

En machine learning, les Model Cards ont été introduites pour documenter de manière standardisée ce qu'un modèle fait, ses limites, ses biais, et ses conditions d'utilisation. AgentCore Registry applique ce même principe avec ce qu'on pourrait appeler des Agent Cards et des Skill Cards — des métadonnées structurées qui décrivent précisément ce que fait un agent ou un skill, comment l'utiliser, et dans quelles conditions. Un record dans le registry, c'est fondamentalement un Model Card pour l'ère des agents : un contrat de confiance entre le producteur et le consommateur.

C'est précisément ce qu'AWS Bedrock AgentCore Registry résout — en adressant à la fois la découvrabilité, la gouvernance, et l'accès pour des utilisateurs hors de l'écosystème AWS.

Un registry que vos agents peuvent interroger directement

AgentCore Registry est un catalogue centralisé et managé qui permet de publier, organiser, gouverner et découvrir quatre types de ressources : des MCP servers (avec validation du schéma MCP), des agents A2A (avec validation du schéma Agent-to-Agent), des skills (des capacités réutilisables documentées en markdown), et des ressources custom (avec un schéma JSON libre).

Ce qui rend le service particulièrement intéressant pour une adoption en entreprise, c'est qu'il expose chaque registry comme un endpoint MCP natif. Autrement dit, n'importe quel client MCP — Claude Code, Kiro, ou votre agent custom — peut se connecter directement au registry et rechercher les ressources disponibles, sans configuration complexe. L'endpoint expose un outil search_registry_records qui accepte des requêtes en langage naturel avec un système de recherche hybride combinant sémantique et keyword matching.

Côté autorisation, le registry supporte deux modes : AWS IAM (pour les équipes déjà dans l'écosystème AWS) et JWT via un identity provider corporate — Amazon Cognito, Okta, Microsoft Azure AD, ou tout fournisseur OAuth 2.0 compatible. C'est cette deuxième option qui nous intéresse dans ce guide, parce qu'elle permet à des développeurs sans compte AWS d'accéder au registry avec leurs identifiants d'entreprise.

Le workflow de gouvernance suit un modèle Publisher/Curator/Consumer : un Publisher soumet un record, un Curator le review et l'approuve (ou le rejette), et seuls les records approuvés deviennent visibles. Pour les environnements de développement, un mode auto-approval permet de court-circuiter la revue manuelle.

Guide : mettre en place le Registry avec Cognito et Claude Code

Ce qui suit est un guide complet, testé et fonctionnel, pour créer un AgentCore Registry, y publier un skill, et le consommer depuis Claude Code avec une authentification OAuth via Cognito. Chaque commande a été exécutée et vérifiée.

Prérequis

Nous avons besoin d'AWS CLI v2.34 ou supérieur (les commandes registry ne sont pas disponibles dans les versions antérieures), d'un profil AWS avec les permissions IAM pour Cognito et AgentCore, et de Claude Code installé.

On commence par exporter le profil AWS à utiliser — toutes les commandes du guide s'appuient dessus :

export AWS_PROFILE=<votre-profil>
export AWS_REGION=us-east-1  # si la région n'est pas déjà configurée dans votre profil

Pour vérifier que votre CLI est à jour et que les commandes registry sont disponibles :

aws --version
# aws-cli/2.34.28 ou supérieur

aws bedrock-agentcore-control create-registry help
# Doit afficher l'aide de la commande, pas une erreur

Si create-registry n'est pas reconnu, mettez à jour votre CLI. La procédure dépend de votre OS — la documentation officielle couvre tous les cas. Sur macOS par exemple :

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

Étape 1 — Configurer l'identity provider

Dans la plupart des organisations, un SSO est déjà en place — Okta, Azure AD, ou un Cognito User Pool existant. Le registry AgentCore accepte n'importe quel identity provider compatible OAuth 2.0 / OIDC. Il suffit que le provider expose un endpoint /.well-known/openid-configuration pour que le registry puisse valider les JWT. Si vous avez déjà un IdP, vous pouvez passer directement à l'étape 2 avec le discoveryUrl et le clientId de votre provider existant.

Pour les détails sur les providers supportés, la documentation AgentCore Identity couvre les configurations Okta, Azure AD et Cognito.

Dans ce guide, on crée un Cognito User Pool from scratch pour avoir un setup autonome et reproductible.

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"

Ensuite, on crée le domaine Cognito managé. C'est l'URL où les utilisateurs seront redirigés pour s'authentifier :

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

Le domaine sera accessible à https://mon-registry.auth.us-east-1.amazoncognito.com.

Étape 2 — Créer l'App Client OAuth

C'est l'étape qui demande le plus d'attention. On crée un client OAuth public (sans secret) compatible avec le flow authorization code que Claude Code utilisera. Deux points critiques à ne pas manquer.

Le flag --no-generate-secret est indispensable : Claude Code agit comme un client public (il ne peut pas stocker un secret de manière sécurisée), donc le client Cognito ne doit pas avoir de secret.

Les scopes doivent inclure tous les scopes OIDC standards que Cognito supporte : openid, email, profile et phone. C'est lié à un bug connu de Claude Code qui ne transmet pas le paramètre scope dans la requête OAuth. Cognito rejette alors avec invalid_scope si le client n'a pas tous les scopes pré-autorisés.

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"

Le port 4999 dans le callback URL n'est pas arbitraire : Cognito ne permet pas de spécifier un range de ports dans les redirect URIs, donc on fixe un port précis qui sera aussi configuré côté Claude Code.

Étape 3 — Créer le Registry AgentCore

On crée maintenant le registry avec un authorizer JWT pointant vers l'endpoint OIDC discovery de Cognito. Le discoveryUrl permet au registry de récupérer automatiquement les clés publiques pour valider les tokens JWT.

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"

Le registry passe en statut CREATING pendant quelques minutes. On peut surveiller son état :

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

On attend que le statut passe à READY avant de continuer.

Étape 4 — Publier un skill

Un skill dans le registry est une prompt réutilisable décrivant une compétence, une façon de se comporter spécifique, en markdown — c'est le format le plus simple pour tester.

Imaginons un fichier SKILL.md hyper simple contenant notre skill de test-driven development :

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

On le publie dans le registry avec le descriptor type AGENT_SKILLS :

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"

Le champ inlineContent accepte le contenu markdown du skill en une seule chaîne avec des \n pour les sauts de ligne. Pour des skills plus longs, on peut bien évidemment passer par --cli-input-json.

Le record est créé en statut DRAFT. Même avec auto-approval activé, il faut explicitement le soumettre pour approbation — le "auto" signifie qu'il sera approuvé automatiquement sans revue manuelle, pas qu'il saute l'étape de soumission :

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

Le statut passe directement à APPROVED. Le skill est maintenant découvrable.

Étape 5 — Créer un utilisateur de test

On peut maintenant créer un utilisateur de test :

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

Étape 6 — Configurer Claude Code

On crée maintenant un fichier .mcp.json à la racine du projet en réutilisant les variables capturées précédemment. Le registry sera alors disponible uniquement dans ce projet. Si on veut que le registry soit accessible dans tous les projets (ce qui est souvent le cas — le catalogue de skills est transverse), on place la même configuration dans ~/.claude.json au niveau utilisateur :

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

Le champ oauth avec clientId et callbackPort indique à Claude Code d'utiliser le flow OAuth authorization code grant. Au lancement, Claude Code détecte que l'authentification est nécessaire, ouvre le navigateur sur la page de login Cognito, et récupère le token JWT après l'authentification.

Étape 7 — Tester la connexion

On relance Claude Code dans le projet (ou on utilise la commande /mcp pour rafraîchir les connexions MCP). Le serveur agentcore-skills-registry apparaît avec le statut "needs authentication". On sélectionne "Authenticate", le navigateur s'ouvre, on se connecte avec nos identifiants Cognito, et la connexion s'établit.

Une fois connecté, l'outil search_registry_records est disponible, et voilà. On peut rechercher les skills publiés en langage naturel :

> Quels skills sont disponibles dans le registry ?

Claude Code appelle search_registry_records avec la requête et retourne le skill TDD avec tout son contenu markdown, sa description, sa version et son statut.

On peut aussi utiliser le skill directement dans un contexte de travail — ici, Claude Code retrouve le skill TDD depuis le registry et l'applique :

Les pièges à éviter

Ce setup a l'air simple une fois qu'on connaît les bonnes valeurs, mais quelques erreurs peuvent coûter du temps.

CLI AWS < 2.34 — les commandes create-registry n'existent tout simplement pas, et l'erreur (Found invalid choice) ne mentionne pas qu'il faut mettre à jour. On pourrait croire que le service n'est pas disponible dans sa région.

Client secret Cognito — --generate-secret (le défaut dans certains workflows) fait échouer le flow silencieusement. Claude Code est un client public : --no-generate-secret est obligatoire.

Scopes OIDC — openid seul ne suffit pas. Il faut pré-autoriser email, profile et phone à cause du bug Claude Code qui ne transmet pas le paramètre scope.

JSON de update-registry — Contrairement à create-registry, update-registry exige un wrapper optionalValue autour de customJWTAuthorizer. Facile à manquer si on modifie la config après coup.

Statut DRAFT — autoApproval=true court-circuite la revue manuelle, pas la soumission. Il faut toujours appeler submit-registry-record-for-approval.

Le Registry dans l'écosystème AgentCore

Le Registry ne vit pas seul — il s'intègre dans la suite complète Bedrock AgentCore : Runtime (déploiement serverless), Gateway (APIs et services tiers exposés en MCP), Identity (authentification et credentials), Memory (persistance contextuelle), Policy (guardrails Cedar), et Observability (tracing OpenTelemetry).

Le Registry est la couche de découverte transverse qui les connecte.

Un agent déployé sur Runtime peut interroger le Registry pour trouver les outils disponibles via Gateway. Identity sécurise l'accès au Registry et fournit les credentials pour synchroniser les métadonnées des MCP servers distants. Policy gouverne qui a accès à quoi. Le tout est tracé par Observability.

C'est cette intégration qui fait passer AgentCore du statut de collection de services à celui de plateforme enterprise. Et le fait que le Registry soit un endpoint MCP standard ouvre la porte à des agents qui découvrent dynamiquement les outils disponibles dans l'organisation et les invoquent — sans configuration préalable.

Et après ?

Ce guide couvre le cas le plus simple — un skill publié dans un registry avec authentification Cognito. Mais le registry supporte bien d'autres scénarios.

On peut publier des MCP servers avec synchronisation automatique : le registry récupère périodiquement les métadonnées depuis l'endpoint MCP distant et met à jour le record, ce qui garantit que le catalogue reste à jour sans intervention manuelle. On peut aussi configurer des workflows d'approbation via EventBridge pour intégrer le registry dans les processus de review existants de l'organisation — un record soumis peut déclencher un ticket Jira, une notification Slack, ou un pipeline Step Functions.

Pour d'autres identity providers (Okta, Azure AD), le setup est quasiment identique — on remplace le discoveryUrl comme mentionné en étape 1. Le Dynamic Client Registration (DCR) simplifie encore davantage la configuration : plus besoin de spécifier un clientId dans le .mcp.json, le client s'enregistre automatiquement. La documentation du MCP endpoint détaille les configurations pour chaque provider.

Tout comme le data catalog est devenu un prérequis pour les organisations data-driven (pour celles qui le sont vraiment), le registry d'agents est en train de devenir le socle des organisations agent-driven. La différence, c'est que cette fois les consommateurs ne sont pas seulement des humains — ce sont aussi des agents.