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.

Shell
curl -H 'Accept: text/markdown' https://instruction.md/instruction-md/code-review

Claude Code

Shell
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

JSON
{
  "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 :

OptionL’application peut
Lire uniquementLire vos instructions et leurs versions. Elle ne modifie rien.
Lire et modifier les brouillonsEn plus, créer des instructions, modifier des brouillons, suggérer des modifications et commenter. Rien n’est publié.
Lire, modifier et publierEn 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 faireEn 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:admin que 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 nommant org:admin.
  • Le studio et la CLI instruction ont toujours cette portée. Si votre hôte ne l’a pas, gérez l’organisation depuis ceux-ci : Paramètres dans le studio, ou instruction agents, instruction keys et instruction audit dans 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 :

YAML
# 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).

Shell
npm install instruction.md
pip install instruction-md   # the Python SDK
TypeScript
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

ChoixCe qu’il signifie
@stableUne référence que vous déplacez délibérément. Recommandée pour tout ce qui est en production.
@latestSe 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.