Le service MCP

AWR expose son registre de travail via MCP (Model Context Protocol), le protocole standard qui permet à un hôte d'agent — tel qu'un assistant de codage ou un client IA de bureau — de découvrir et d'appeler des outils. Le service MCP est la manière dont votre agent lit l'état du projet, compile le contexte, enregistre des preuves et fait avancer le travail sans passer lui-même par le CLI. Il y a deux façons de l'exécuter :

• stdio — un processus local que votre client lance directement, un projet à la fois. C'est la configuration classique et elle reste disponible.
• HTTP partagé — un unique point de terminaison Streamable HTTP servant plusieurs projets et plusieurs clients indépendants. Les paquets npm et PyPI incluent tous deux cette capacité.

Cet article se concentre sur le service HTTP partagé, qui est ce que vous exécutez quand plus d'une personne ou d'un agent a besoin des mêmes projets. Pour ce que les agents font avec ces outils une fois connectés, voir Agents. Pour l'équivalent destiné aux humains des mêmes opérations, voir Le CLI AWR.

Comment fonctionne le service partagé

Vous initialisez chaque projet sur le serveur avec awr init, puis vous enregistrez sa racine absolue canonique avec le project_id renvoyé par :

awr --json status

AWR vérifie cette identité au démarrage et à chaque requête. Les fichiers sources et la base .awr de chaque projet restent séparés — le service ne clone pas de dépôts, ne monte pas de systèmes de fichiers clients et ne fusionne pas de registres de projets. Les clients ont besoin d'un accès réseau au service, pas d'un exécutable AWR local, et les fichiers du projet doivent être lisibles sur le serveur : un chemin sur le portable d'un client ne devient pas lisible à distance. Il n'y a pas de « projet courant » partagé — chaque outil de projet prend un argument project explicite, et il n'existe aucun outil pour ouvrir un chemin arbitraire du serveur.

Configurer le service

Créez un fichier TOML détenu par l'opérateur en dehors du dépôt public :

version = 1
allowed_hosts = ["awr.internal.example"]

[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"

[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"

[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]

[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]

Chaque entrée client nomme une variable d'environnement qui contient son identifiant bearer. Fournissez des identifiants distincts, générés aléatoirement, d'au moins 32 caractères. Un droit write inclut l'accès en lecture ; un droit read ne peut pas muter les projets. Gardez les identifiants clients stables lors des rotations d'identifiants — les liaisons de conversation et de requête s'attachent à l'identifiant client, et le changer crée un périmètre distinct. Les changements de configuration ne prennent effet qu'après un redémarrage du service.

Exécuter le service

awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080

Chaque requête HTTP est authentifiée. Le mécanisme intégré est l'authentification bearer statique — pas un serveur d'autorisation OAuth ni un fournisseur d'identité d'entreprise. Pour l'accès distant, terminez HTTPS à une frontière de déploiement authentifiée et restreignez l'accès direct au backend. Contrôles d'accès supplémentaires :

• Les origines sont refusées sauf si elles sont explicitement listées dans allowed_origins ; les clients natifs omettent normalement l'en-tête Origin.
• Le SDK vérifie allowed_hosts, avec pour valeur par défaut les hôtes de bouclage quand aucun n'est configuré.
• Le service valide l'Origin mais n'implémente pas le préflight CORS des navigateurs, donc un frontend navigateur a besoin d'une passerelle appropriée.

Sous Unix, SIGTERM et Ctrl-C cessent proprement d'accepter les requêtes et purgent le travail HTTP actif. Déconnecter un client ou redémarrer le service ne termine jamais une session de travail AWR — les connexions de protocole et les sessions persistantes sont des identités séparées. AWR n'installe pas de démon système — utilisez le superviseur de processus de votre déploiement pour le démarrage et le redémarrage. Pour un usage local à client unique, la commande stdio reste :

awr-mcp --project /absolute/project

Connecter un client

Configurez chaque client MCP pour Streamable HTTP avec la même URL de service utilisant le chemin /mcp, plus son propre identifiant bearer dans un en-tête Authorization: Bearer … délivré via le mécanisme d'identifiants de ce client. Une fois connecté, appelez awr_projects_list pour découvrir les clés de projet pour lesquelles votre identifiant est autorisé. Chaque outil de projet exige ensuite project :

{"project": "billing", "work": "INVOICE-001"}

Les outils

Le service HTTP partagé expose 21 outils au total (20 via stdio, qui omet l'outil de listage des projets). Ils se répartissent en trois groupes.

Outils de travail et de contexte

Ils reflètent les actions CLI du quotidien :

Outils de session et de continuation

Les sessions lient une conversation à une unité de travail. Fournissez un identifiant conversation stable depuis votre hôte — pas un identifiant de connexion HTTP. La même chaîne de conversation sous un autre projet ou un autre client est une liaison séparée.

Une attente en suspens bloque les transitions de travail et la reprise jusqu'à ce que l'hôte enregistre une réponse. La réponse lève ce blocage mais ne change pas le statut du travail ni ne planifie le prochain tour de l'hôte — votre hôte inspecte la session, compile un contexte frais et décide de continuer ou de créer un successeur.

Écritures, révisions et résultats incertains

Chaque écriture HTTP partagée exige deux choses :

• un request_id stable généré par le client (jusqu'à 256 octets),
• la expected_revision que vous avez observée en dernier.

{
  "project": "billing",
  "request_id": "host-turn-42-start",
  "expected_revision": 120,
  "work": "INVOICE-001",
  "conversation": "invoice-review",
  "agent": "billing-assistant",
  "provider": "example-provider",
  "model": "example-model",
  "claim": true
}

Répéter exactement le même identifiant de requête et les mêmes arguments renvoie le résultat enregistré sans réexécuter l'action, donc une nouvelle tentative après un délai d'attente est sûre. Des arguments modifiés exigent un nouvel identifiant. Conservez la project_revision renvoyée pour votre prochaine écriture, et ne calculez jamais la révision suivante en ajoutant un : le journal des requêtes et l'opération de domaine consomment tous deux des révisions.

Après un délai d'attente ou une déconnexion, appelez awr_operation_get avec le même projet et le même identifiant de requête. Une requête inachevée rapporte write_outcome: unknown ; une écriture interrompue peut déjà avoir été validée, donc ne déduisez jamais un échec d'un flux de réponse HTTP fermé. awr_operation_recover ne peut enregistrer un résultat validé que lorsqu'un événement terminal non ambigu est lié à la requête — il ne réinvoque jamais l'outil d'origine. Les lectures peuvent s'exécuter en concurrence ; les écritures sont sérialisées par projet, et des projets différents ont des verrous indépendants. Une écriture obsolète renvoie un conflit — lisez l'état courant et reconsidérez avant de réessayer.

Lectures de flux de travaux (en développement)

La source de développement ajoute un registre version = 2 qui accorde aux clients un accès en lecture seule à des flux de travaux immuables explicitement listés, pour les projets utilisant le registre YAML de flux de travaux. Ce sont des permissions détenues par l'opérateur : les droits read/write au niveau projet à eux seuls n'autorisent aucun flux de travaux isolé.

[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1

Les clients autorisés utilisent l'outil awr_workstream, propre au service partagé, en commençant par action: "capabilities" et action: "list" pour découvrir ce qu'ils peuvent lire. Soyez conscient des limites actuelles : cette extension n'accorde que des lectures — pas de mutations, de lectures de fichiers de contenu ni d'opérations Team PostgreSQL — et les projets qui l'activent rejettent les outils partagés historiques, y compris toutes les écritures, jusqu'à ce qu'une implémentation autorisée soit disponible. L'activation et la réindexation sont des actions locales de l'opérateur à ce stade.

Pour aller plus loin

• Agents — comment un agent utilise sessions, réservations et points de contrôle par-dessus ces outils.
• Le CLI AWR — les mêmes opérations de domaine depuis la ligne de commande, pour les opérateurs et le débogage.
• Dépannage — conflits de révision, sources obsolètes et reprise.