Connecter un agent
Le registre est un seul point d’accès MCP : https://instruction.md/mcp. Un agent lit une instruction
comme une ressource, et celui qui s’y abonne (agentd, les suiveurs des SDK) est prévenu quand vous publiez et la
recharge sans redémarrer. Claude Code et Codex ne s’abonnent pas aux ressources : ils suivent une instruction grâce
à des hooks, mis en place en une commande (Claude Code,
Codex, en anglais).
Le serveur parle MCP 2026-07-28, le protocole sans état : il n’y a pas d’identifiant de session,
et chaque requête porte sa version du protocole, son client et ses capacités, si bien que n’importe quelle réplique
du serveur peut y répondre. Un abonnement est un flux subscriptions/listen. Nos propres clients le
parlent : le studio, la CLI instruction et les clients de suivi (followers) pour TypeScript, Python et
Go. C’est le seul protocole que instruction.md prend en charge : un hôte se connecte avec la version 2026-07-28.
Mises à jour en direct et lecture
Un agent obtient une instruction de deux façons. Il la lit chaque fois qu’il veut la dernière version. Et il peut recevoir des mises à jour en direct : le serveur le prévient à l’instant où quelque chose change, sans qu’il ait à demander.
La lecture n’est jamais limitée, quelle que soit l’offre : autant d’agents que vous voulez, aussi souvent qu’ils le veulent.
Les mises à jour en direct dépendent de l’offre de l’espace de travail. Avec Community, un seul agent ou une seule application d’IA les reçoit à la fois. À partir de Pro, il n’y a pas de limite. Si un deuxième agent demande les mises à jour en direct dans un espace de travail Community alors qu’un autre les reçoit déjà, il en est informé, avec le délai avant de réessayer. Il fonctionne quand même : il lit la dernière version à son propre rythme (nos clients de suivi vérifient toutes les minutes, sauf si vous réglez un autre intervalle) et prend la place dès que le premier s’arrête. Le studio lui-même ne prend jamais cette place.
Pour celles et ceux qui écrivent un client : les mises à jour en direct, ce sont subscriptions/listen
sur une adresse instruction:// et les événements MCP Events md.instruction.activity et
md.instruction.releases (flux, interrogation périodique ou webhook). Le refus est l’erreur JSON-RPC
-32013, avec notre erreur dans son champ data : code: "limit_reached", un
message, et details avec limit: "realtimeConsumers", max, plan,
retryAfterSeconds et upgrade. Un flux qui perd sa place (l’agent de l’espace de travail
la reprend à un agent extérieur) se termine par notifications/events/terminated, qui porte la même
erreur. Un agent compte pour un, quel que soit le nombre de flux qu’il ouvre. Une place se libère quand ses flux
se ferment, ou deux minutes après le dernier signe de vie de l’agent.
L’adresse d’une instruction
Chaque instruction publique a une adresse web, https://instruction.md/{owner}/{name}, la même
pour les personnes et pour les agents. Un navigateur reçoit sa page : l’instruction, son URI
instruction:// et la configuration pour la suivre. Un agent qui envoie
Accept: text/markdown, ou aucun en-tête Accept, comme le font curl et la plupart des
outils de récupération, reçoit le texte publié lui-même, à l’identique, avec sa version dans les en-têtes.
L’adresse est la même dans les deux cas : il n’existe pas de forme en .md. @stable ou
@v3 après le nom lit une référence (ref) ou une version précise, et
https://instruction.md/{owner} liste les instructions publiques d’un propriétaire. Pour suivre
une instruction au fil de ses changements, connectez l’agent par MCP, comme décrit ci-dessous. Le fichier
/llms.txt du site liste la documentation et les modèles à l’intention des agents.
curl -H 'Accept: text/markdown' https://instruction.md/instruction-md/code-review Claude Code
claude mcp add instruction-md --transport http https://instruction.md/mcp
# then in a session: read instruction://acme/support-agent@stable Pour faire d’une instruction celle du projet, tenue à jour pendant une session, voyez Claude Code (en anglais).
Codex
Codex parle une version de MCP antérieure à celle de ce serveur : il se connecte donc par le serveur MCP de la ligne de commande. Voyez Codex (en anglais) pour cela, et pour suivre une instruction pendant une session.
Cursor et les autres clients MCP
{
"mcpServers": {
"instruction-md": {
"command": "npx",
"args": ["-y", "instruction.md", "mcp", "--follow", "instruction://acme/support-agent@stable", "--url", "https://instruction.md/mcp"]
}
}
}
Chaque lecture exige un appelant connecté. Claude et ChatGPT vous font vous connecter eux-mêmes. Cursor, VS Code et
les autres clients qui parlent une version de MCP plus ancienne qu’instruction.md passent par le serveur stdio de la
CLI ci-dessus (VS Code : la même entrée sous servers dans .vscode/mcp.json, avec
"type": "stdio"), auquel vous vous connectez une fois avec instruction login. Les agents
utilisent leurs propres identifiants.
Choisir ce qu’une application d’IA peut faire
Quand vous connectez une application d’IA comme Claude, ChatGPT ou un éditeur de code, instruction.md demande d’abord Que peut faire l’application ? (avec le nom de l’application). Vous choisissez l’une des quatre options, chacune incluant la précédente :
| Option | L’application peut |
|---|---|
| Lire uniquement | Lire vos instructions et leurs versions. Elle ne modifie rien. |
| Lire et modifier les brouillons | En plus, créer des instructions, modifier des brouillons, suggérer des modifications et commenter. Rien n’est publié. |
| Lire, modifier et publier | En plus, publier de nouvelles versions, après vous avoir demandé. C’est l’option que la page propose en premier. |
| Tout ce que vous pouvez faire | En plus, partager, supprimer, modifier votre compte et administrer une organisation que vous administrez. |
Un interrupteur à part, Suivre les modifications en direct, indique si l’application peut suivre des instructions et savoir quand elles changent. Pour une application qui doit seulement lire et suivre, choisissez Lire uniquement et laissez l’interrupteur activé.
L’application ne voit que les outils que votre choix autorise, et le serveur refuse tout ce qu’elle tente d’autre, quel que soit votre propre rôle. Pour modifier ce choix ou déconnecter une application, ouvrez Paramètres ▸ Applications connectées et choisissez Modifier ce qu’elles peuvent faire. Une modification prend effet en quelques minutes. Une application connectée avant l’arrivée de ce choix se le voit demander à sa prochaine connexion ; d’ici là, elle agit pleinement en votre nom.
Les outils d’organisation dans un hôte
Administrer une organisation demande une portée (scope) OAuth supplémentaire, org:admin, et l’option
Tout ce que vous pouvez faire au moment de connecter l’application. Sans elle, un hôte liste les outils
pour écrire, relire, publier, partager et suivre des instructions, mais pas les 28 qui font fonctionner une
organisation : ses membres et ses invitations, ses espaces de travail, sa politique, ses clés de signature, ses
agents, sa facturation et son journal d’audit. Un hôte sans cette portée a une liste d’outils plus courte.
- Le serveur ne nomme pas cette portée là où un hôte apprend comment se connecter (les métadonnées de la ressource protégée et le challenge de sa réponse 401) : l’hôte se connecte donc pour les outils de tous les jours et liste ceux-là.
-
Un hôte n’obtient
org:adminque s’il la demande par son nom au moment où vous vous connectez, là où il vous laisse choisir les portées qu’il demande. La page de connexion affiche alors « Administer your organizations on instruction.md » parmi ce que vous acceptez, et l’hôte liste les outils d’organisation. -
Un hôte qui nomme ses portées lors de sa première connexion n’a que celles-là : s’il a omis
org:admin, il ne peut plus la demander lors d’une connexion ultérieure (elle est refusée comme portée non valide). Supprimez le connecteur et ajoutez-le de nouveau, cette fois en nommantorg:admin. -
Le studio et la CLI
instructionont toujours cette portée. Si votre hôte ne l’a pas, gérez l’organisation depuis ceux-ci : Paramètres dans le studio, ouinstruction agents,instruction keysetinstruction auditdans la CLI. - Les agents ne l’obtiennent jamais : les identifiants d’un agent ne permettent pas d’administrer une organisation.
La portée permet seulement à un client de voir et d’appeler ces outils. Chaque outil vérifie toujours votre rôle : seuls les propriétaires et les administrateurs d’une organisation la modifient, et seuls ses membres chargés de la facturation modifient sa facturation.
agentd
agentd, à partir de la version 1.18, parle MCP 2026-07-28 et MCP Events. Donnez à
l’agent ses propres identifiants (Paramètres ▸ Agents dans le studio, ou instruction agents create ; une
organisation avec l’offre Pro ou supérieure), puis suivez l’instruction par son identifiant, à une référence :
# agentd 1.18 or later, as a daemon: the instruction is the policy every conversation follows
agent:
name: support-desk
instruction:
mcp:
server: instruction-md
# the instruction's id at a ref: publishing moves the ref, and the server pushes the re-read
resource: "instruction://ins_01M…@stable"
events: [md.instruction.activity]
unavailable: keep
trust:
- uri: "instruction://ins_01M…@stable"
publisher: "https://instruction.md/pub/acme"
intelligence:
endpoints: https://api.anthropic.com
dialect: anthropic
model: claude-sonnet-5
token: "{{secret:ANTHROPIC_API_KEY}}"
mcp:
servers:
- name: instruction-md
endpoint: https://instruction.md/mcp
auth:
kind: oauth2
grant: client_credentials
client_id: "<your agent's client id>"
client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"
# agents sign in on their own realm
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
store:
kind: file
file: { path: ./support-desk-state }
a2a:
listen: http://127.0.0.1:8420
lifecycle:
run_until: drained
Publier déplace la référence, le serveur pousse la relecture vers l’abonnement d’agentd, et le tour suivant lit la
nouvelle version : agentd consigne instruction.applied, de l’ancienne version à la nouvelle, en moins
d’une seconde. Une adresse de la forme propriétaire/nom (instruction://acme/support-agent@stable)
fonctionne aussi ; agentd apprend alors qu’une version est publiée par MCP Events, quelques secondes plus tard.
Épingler publisher rend la vérification obligatoire : à chaque lecture, agentd vérifie la signature
de l’auteur avec le jeu de clés de l’éditeur, refuse une version signée avec une clé révoquée et conserve sa
dernière instruction valide plutôt que d’appliquer quoi que ce soit qu’il ne peut pas vérifier. La signature d’une
version nomme l’instruction par son identifiant : épinglez donc l’adresse avec l’identifiant. Le jeton de l’agent
vient du realm des agents, que les métadonnées du serveur MCP ne nomment pas : token_url indique où
il se trouve.
Votre propre code
Le paquet instruction.md sur npm fournit un client de suivi (follower) qui met en œuvre la moitié
« consommateur » de la spécification : conserver la dernière version valide, respecter les mises en attente
imposées par la politique, vérifier les signatures en découvrant les clés, et rapporter ce qu’il a appliqué. Son
client MCP, instruction.md/client, lui apporte le protocole sans état ; son abonnement se rouvre après
une coupure et relit l’instruction. Les SDK Python et Go ont le même client de suivi sur le même protocole
(python -m instruction_md watch, NewHTTPClient).
npm install instruction.md
pip install instruction-md # the Python SDK import { asSdkClient, createClient } from "instruction.md/client";
import { InstructionFollower } from "instruction.md/consumer";
const follower = new InstructionFollower({
// MCP 2026-07-28, stateless (or any MCP client with the SDK's Client shape)
client: asSdkClient(createClient({ url: "https://instruction.md/mcp", token: () => token })),
uri: "instruction://acme/support-agent@stable",
mode: "follow",
policy: { requireSignature: true, publisher: "https://instruction.md/pub/acme" },
report: { consumer: { label: "support-bot (prod)", kind: "agent" } },
onApply: (applied) => setSystemPrompt(applied.text),
onHold: (reason) => log.warn({ reason }, "kept the last good instruction"),
});
await follower.start(); Suivre sans risque une cible qui bouge
| Choix | Ce qu’il signifie |
|---|---|
@stable | Une référence que vous déplacez délibérément. Recommandée pour tout ce qui est en production. |
@latest | Se déplace à chaque publication. Pratique pour le développement. |
@ver_… | Épinglée sur une version immuable. Ne change jamais. |
Quoi que vous suiviez, un consommateur qui ne peut pas lire ou ne peut pas vérifier garde la version qu’il avait déjà. Ne pas pouvoir joindre le registre revient à « pas de mises à jour », jamais à « pas d’instructions ».
Dire au registre ce que vous avez appliqué
Un consommateur peut déclarer une liaison et signaler la version qu’il a appliquée. C’est ce qui alimente la vue Consumers : quels agents suivent une instruction, ce que chacun exécute et combien de temps prend l’adoption. C’est facultatif, et cela n’envoie jamais votre contenu où que ce soit.