Connect an agent

The registry is one MCP endpoint: https://mcp.instruction.md/mcp. An agent reads an instruction as a resource and subscribes to it. When you publish, the agent is notified and reloads without restarting.

Claude Code

claude mcp add instruction-md --transport http https://mcp.instruction.md/mcp
# then in a session: read instruction://acme/support-agent@stable

Cursor and other MCP clients

{
  "mcpServers": {
    "instruction-md": {
      "url": "https://mcp.instruction.md/mcp",
      "headers": { "Authorization": "Bearer <token from: instruction login>" }
    }
  }
}

Public instructions are readable without a token. Sign in when you want your own private instructions, or when the policy of the organization requires it.

agentd

agent:
  instruction: "instruction://acme/support-agent@stable"
mcp:
  servers:
    - name: instruction-md
      url: https://mcp.instruction.md/mcp
      auth:
        kind: oauth2
        grant: client_credentials
        client_id: <your agent client>
        client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"
instruction_sources:
  - uri: "instruction://acme/support-agent@stable"
    mode: follow
    publisher: "https://instruction.md/pub/acme"

Pinning publisher makes verification mandatory: agentd checks the author signature against the publisher's key set on every read, refuses a version signed with a revoked key, and holds its last good instruction rather than applying anything it cannot verify.

Your own code

@instruction-md/spec ships a follower that implements the consumer half of the specification: keep-last-good, policy holds, signature verification with key discovery, and reporting what it applied.

import { InstructionFollower } from "@instruction-md/spec/consumer";

const follower = new InstructionFollower({
  client,                                   // an MCP client
  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();

Following a moving target safely

Whatever you follow, a consumer that cannot read or cannot verify keeps the version it already had. Being unable to reach the registry degrades to "no updates", never to "no instructions".

Telling the registry what you applied

A consumer can declare a binding and report the version it applied. That is what fills in the Consumers view: which agents follow an instruction, what each is running, and how long adoption takes. It is optional, and it never sends your content anywhere.