Cette page n’est pas encore traduite.

Live updates, events and webhooks

This page is for developers whose agents, services or integrations need to know when an instruction changes. It covers the two ways the MCP server tells you: a subscription to an instruction's address, and typed events delivered by stream, poll or webhook. It also covers the plan limit on live updates, and what a client does when it is refused.

One live place, many reads.

Reading and live updates

Reading an instruction is never limited. Any agent, on any plan, may read an instruction whenever it wants, over MCP or its page, within the rate limits.

A live update is the server telling you that something changed, so you don't have to ask. The server offers two kinds:

  • A resource subscription (subscriptions/listen) says that an address's answer changed, such as instruction://ins_…@latest after a release. You then read the address again. This is what followers use.
  • An event (events/stream, events/poll or a webhook) says what happened, such as version.published or comment.created, with ids and kinds. This is what integrations and runners use.

Neither carries an instruction's text. You read what changed with your own permission. Both kinds count toward the live-updates limit, except where this page says they don't.

Subscribe to an instruction

Open one subscriptions/listen stream with the addresses you follow. The gateway answers with a server-sent event stream that stays open. Its first message acknowledges the subscription. Then each notifications/resources/updated names an address whose answer changed.

Listen for changes to an instruction's latest
curl -sN https://instruction.md/mcp \
  -H 'authorization: Bearer <access token>' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: subscriptions/listen' \
  -d '{"jsonrpc":"2.0","id":1,"method":"subscriptions/listen","params":{
        "notifications":{"resourceSubscriptions":["instruction://ins_01JD8Q5V0YB3X2K7M9N4P6R8ST@latest"]},
        "_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientInfo":{"name":"my-follower","version":"1.0.0"},
        "io.modelcontextprotocol/clientCapabilities":{}}}}'
What the stream sends
data: {"jsonrpc":"2.0","method":"notifications/subscriptions/acknowledged","params":{}}

data: {"jsonrpc":"2.0","method":"notifications/resources/updated","params":{"uri":"instruction://ins_01JD8Q5V0YB3X2K7M9N4P6R8ST@latest"}}

When you get notifications/resources/updated, read that address again. The read carries the new version's id, its digest and its signature.

Which addresses tell you

The gateway watches these addresses:

AddressWhat it isCounts toward the limit
me://favoritesYour favoritesNo
me://inboxYour inboxNo
instruction://{id}@{selector}An instruction at a ref or versionYes
instruction://{id}An instructionYes
deployment://{org}/{platform}A platform's deploymentsNo

An instruction's notices name its id form, so subscribe by id: instruction://ins_… or instruction://ins_…@<ref>. A subscription to the owner/name form, such as instruction://acme/support-agent@stable, is accepted but never told anything. Get the id from instructions_get, or from the md.instruction/canonical of any read.

When each address is told:

  • A ref moves to another version: instruction://<id>@<ref>, and also instruction://<id> when that ref is the default one (latest, unless a maintainer chose another).
  • A ref is deleted: instruction://<id>@<ref>.
  • A version is revoked: its pinned addresses, @ver_…, @v<N> and @<N>.
  • The instruction is deleted, restored, archived, moved to another organization, or its visibility changes: every address it has.

A change to the gates of a ref, without a new version, tells no one. The draft's changes never reach these addresses: they are events.

Keep the stream alive

The stream has no resume. When it drops, open it again, then read each address once: something may have changed while you were away. Wait longer between tries each time, from 1 second up to 30 seconds, as instruction.md's own clients do. An edge or proxy in front of your client must pass the stream through unbuffered, or updates arrive late or never.

Your own inbox (me://inbox), your favorites and a platform's deployments (deployment://<org>/<platform>) can be subscribed to the same way. They don't count toward the limit.

Events

The server publishes these event types. events/list returns the same list to any signed-in caller.

EventWhat it is forArgumentsKeptCounts toward the limit
md.instruction.activityEverything that happens to the instructions and organizations you can see. The one most followers and integrations want.instructionId, orgId, types7 days, at most 100,000 eventsYes
md.instruction.presenceWhere people working on a draft have their carets. The editor's own; it needs instructionId.instructionId (required)2 minutes, at most 20,000 eventsNo
md.instruction.releasesAn app's feed of the releases a person lets it follow (Sign in with instruction.md).None7 days, at most 100,000 eventsYes
md.deployment.activityA runner's feed: agents a deployment made, approved, released or retired, and rule changes.orgId, platform, ruleId, instructionId, types7 days, at most 100,000 eventsNo

The arguments filter what you receive:

  • instructionId: only this instruction's events. It must be the ins_… id, not owner/name.
  • orgId: only this organization's events (org_…).
  • types: only these types, from the lists below.
  • platform and ruleId (deployments only): only this platform's, or this deployment rule's (dpr_…).

With no arguments, md.instruction.activity sends everything you may receive, across every organization you belong to.

The types of each event

md.instruction.activity: Something happened to an instruction or organization you can see: versions and refs, the draft, suggestions, comments, access, consumers. Ids and kinds only, never content; read what changed with your own permission.

instruction.created, instruction.updated, instruction.deleted, instruction.restored, instruction.purged, instruction.archived, instruction.visibility_changed, instruction.transferred, draft.changed, checkpoint.created, version.published, version.revoked, ref.changed, ref.deleted, suggestion.created, suggestion.settled, comment.created, comment.resolved, proposal.opened, proposal.updated, proposal.merged, proposal.closed, access.changed, access.requested, access.resolved, binding.created, binding.reported, binding.updated, consumer.adopted, binding.paused, binding.resumed, binding.deleted, folder.changed, org.created, org.updated, org.renamed, org.deleted, workspace.created, workspace.updated, workspace.deleted, member.added, member.updated, member.removed, invitation.created, invitation.accepted, invitation.revoked, user.updated, user.deleted, agent.created, agent.rotated, integration.added, integration.updated, integration.removed, agent.revoked, key.changed, link.created, link.revoked, schedule.created, schedule.cancelled, schedule.fired, export.ready, job.finished

md.instruction.presence: Where the people working on an instruction's draft have their carets, as each window says it (instructions_presence_set): its Yjs awareness state, or that it left. Only to the draft's readers, for one instruction at a time (instructionId). Kept two minutes.

presence.changed, presence.left

md.instruction.releases: For an app a person connected (Sign in with instruction.md): a release, a new instruction or a removal in what the person's grant lets it follow (instructions:all, or chosen instructions it may follow). Ids and kinds only; read the released version with instruction://{id}@{versionId}. instructions_releases_list answers the same to poll.

release, added, removed

md.deployment.activity: Something happened to a deployment you can see: an agent made for an instruction (created; approval_needed when it waits), approved, a release it takes (released) or that waits for approval (release_pending), retired, one a rule refused past its maxAgents, a rule made, changed or deleted. Each names the deployment, its rule, the instruction, the platform and the version; read deployment://{org}/{platform} or deployments_list for the rest. For a runner: filter by orgId and platform.

deployment.created, deployment.approval_needed, deployment.approved, deployment.released, deployment.release_pending, deployment.retired, deployment.refused, deployment.rule_created, deployment.rule_updated, deployment.rule_deleted

What an event carries

Every occurrence has an eventId, its name, a timestamp, a cursor, and data. data.row is the event's row, with these fields:

md.instruction.activity

  • epoch: The outbox's epoch, raised after a restore; with tx and seq it orders the events.
  • tx: The transaction that wrote it.
  • seq: Its place in that transaction.
  • id: The event's own id (evt_…).
  • type: What happened, one of the types below.
  • org_id: The organization (org_…).
  • workspace_id: The workspace (ws_…).
  • instruction_id: The instruction (ins_…).
  • version_id: The version it is about (ver_…), when it is about one.
  • visibility: public for the public changes of a public instruction (anyone subscribed to it gets those), else private.
  • subjects: The sign-in subjects it goes to. The gateway compares the subscriber's own.
  • actor: Who did it: its kind, id and name.
  • subject: What it is about, by kind: a ref and its version, a suggestion's id, a member. Ids and kinds only.
  • summary: One line saying what happened, for a list.
  • at: When it happened.

md.instruction.presence

  • epoch: The outbox's epoch, raised after a restore; with tx and seq it orders the events.
  • tx: The transaction that wrote it.
  • seq: Its place in that transaction.
  • instruction_id: The instruction (ins_…).
  • principal_id: Whose caret it is.
  • session: Which window of theirs.
  • type: What happened, one of the types below.
  • awareness: The window's Yjs awareness state (its caret and selection); null once it left.
  • name: The person's name.
  • subjects: The sign-in subjects it goes to. The gateway compares the subscriber's own.
  • at: When it happened.

md.instruction.releases

  • epoch: The outbox's epoch, raised after a restore; with tx and seq it orders the events.
  • tx: The transaction that wrote it.
  • seq: Its place in that transaction.
  • id: The event's own id (evt_…).
  • kind: release, added or removed.
  • type: The change behind it, such as version.published.
  • instruction_id: The instruction (ins_…).
  • version_id: The version it is about (ver_…), when it is about one.
  • client_id: The app's client id.
  • subject: The person's sign-in subject.
  • at: When it happened.

md.deployment.activity

  • epoch: The outbox's epoch, raised after a restore; with tx and seq it orders the events.
  • tx: The transaction that wrote it.
  • seq: Its place in that transaction.
  • id: The event's own id (evt_…).
  • type: What happened, one of the types below.
  • org_id: The organization (org_…).
  • instruction_id: The instruction (ins_…).
  • version_id: The version it is about (ver_…), when it is about one.
  • platform: The platform the deployment runs on (the runner's --platform).
  • rule_id: The deployment rule (dpr_…).
  • deployment_id: The deployment.
  • subjects: The sign-in subjects it goes to. The gateway compares the subscriber's own.
  • actor: Who did it: its kind, id and name.
  • subject: The deployment's facts: its platform, rule, deployment and version.
  • summary: One line saying what happened, for a list.
  • at: When it happened.

An event never carries an instruction's text, a comment's words or a suggestion's change. Read what it names, with your own permission.

Who receives an event

An event of md.instruction.activity goes to the people who may read the instruction's working side: its workspace's people and those it is shared with. A release, a ref move or another change to its versions also goes to the organization's members (not guests) when the instruction is internal. An organization's own events go to its owners and admins. A public instruction's public changes (its releases, ref moves, and changes to its name, visibility or owner) go to anyone who subscribes to them.

A token of an app a person connected never receives md.instruction.activity or md.deployment.activity. Agents receive what their credential may read.

Delivery

Each event can be delivered three ways. Choose by where your code runs:

  • Stream (events/stream): a connection your code keeps open. For a long-running process.
  • Poll (events/poll): your code asks now and then, with a cursor it keeps. For a job, a cron or code behind a firewall.
  • Webhook (events/subscribe): the gateway POSTs each event to your HTTPS endpoint. For a service with a public address.

Every events/* request names its event twice: in params.name and in the Mcp-Name header. A request without the header, or with one that differs, is refused with -32020.

Each event is kept for the time its row in the table above says. A cursor older than that still works: the answer says truncated: true and goes on from the oldest event kept.

Stream

Stream one instruction's releases and ref moves
curl -sN https://instruction.md/mcp \
  -H 'authorization: Bearer <access token>' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: events/stream' \
  -H 'mcp-name: md.instruction.activity' \
  -d '{"jsonrpc":"2.0","id":1,"method":"events/stream","params":{
        "name":"md.instruction.activity",
        "arguments":{"instructionId":"ins_01JD8Q5V0YB3X2K7M9N4P6R8ST","types":["version.published","ref.changed"]},
        "cursor":null,
        "_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientInfo":{"name":"my-follower","version":"1.0.0"},
        "io.modelcontextprotocol/clientCapabilities":{}}}}'
What the stream sends
data: {"jsonrpc":"2.0","method":"notifications/events/active","params":{"cursor":"ev1.<cursor>","truncated":false}}

data: {"jsonrpc":"2.0","method":"notifications/events/event","params":{"eventId":"<eventId>","name":"md.instruction.activity","timestamp":"2026-11-22T09:14:03Z","cursor":"ev1.<cursor>","data":{"row":{"epoch":0,"tx":918274,"seq":1,"id":"evt_01JD8R3N5Q7S9U1W3Y5A7C9E1G","type":"version.published","org_id":"org_01JD8Q4ZK3W5Y7A9C1E3G5J7M9","workspace_id":"ws_01JD8Q4ZM2X4Z6B8D0F2H4K6N8","instruction_id":"ins_01JD8Q5V0YB3X2K7M9N4P6R8ST","version_id":"ver_01JD8R2M4P6T8V0X2Z4B6D8F0H","visibility":"private","subjects":["<subject>"],"actor":{"kind":"user","id":"usr_01JD8Q3W1Y3A5C7E9G1J3L5N7Q","name":"Ada Park"},"subject":{"versionId":"ver_01JD8R2M4P6T8V0X2Z4B6D8F0H","number":3},"summary":"Released v3","at":"2026-11-22T09:14:03Z"}}}}

data: {"jsonrpc":"2.0","method":"notifications/events/heartbeat","params":{"cursor":"ev1.<cursor>"}}

The stream starts with notifications/events/active, then sends one notifications/events/event per occurrence, and a notifications/events/heartbeat when nothing happens. Each carries a cursor. Keep the last one: after a drop, open the stream again with it as cursor, and you get everything since. A null cursor starts from now. Treat a stream that has sent nothing for two heartbeats as dead.

notifications/events/terminated ends a stream for good, such as when you lose access or a renewal is refused. Its error says why.

Poll

Poll an organization's activity
curl -s https://instruction.md/mcp \
  -H 'authorization: Bearer <access token>' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: events/poll' \
  -H 'mcp-name: md.instruction.activity' \
  -d '{"jsonrpc":"2.0","id":1,"method":"events/poll","params":{
        "name":"md.instruction.activity",
        "arguments":{"orgId":"org_01JD8Q4ZK3W5Y7A9C1E3G5J7M9"},
        "cursor":"ev1.<the cursor of the last answer>",
        "maxEvents":100,
        "_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientInfo":{"name":"my-follower","version":"1.0.0"},
        "io.modelcontextprotocol/clientCapabilities":{}}}}'
The answer
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "events": [
      {
        "eventId": "<eventId>",
        "name": "md.instruction.activity",
        "timestamp": "2026-11-22T09:14:03Z",
        "cursor": "ev1.<cursor>",
        "data": {
          "row": {
            "epoch": 0,
            "tx": 918274,
            "seq": 1,
            "id": "evt_01JD8R3N5Q7S9U1W3Y5A7C9E1G",
            "type": "version.published",
            "org_id": "org_01JD8Q4ZK3W5Y7A9C1E3G5J7M9",
            "workspace_id": "ws_01JD8Q4ZM2X4Z6B8D0F2H4K6N8",
            "instruction_id": "ins_01JD8Q5V0YB3X2K7M9N4P6R8ST",
            "version_id": "ver_01JD8R2M4P6T8V0X2Z4B6D8F0H",
            "visibility": "private",
            "subjects": [
              "<subject>"
            ],
            "actor": {
              "kind": "user",
              "id": "usr_01JD8Q3W1Y3A5C7E9G1J3L5N7Q",
              "name": "Ada Park"
            },
            "subject": {
              "versionId": "ver_01JD8R2M4P6T8V0X2Z4B6D8F0H",
              "number": 3
            },
            "summary": "Released v3",
            "at": "2026-11-22T09:14:03Z"
          }
        }
      }
    ],
    "cursor": "ev1.<cursor>",
    "hasMore": false,
    "truncated": false,
    "nextPollMs": 5000
  }
}

Send the answer's cursor with your next poll. With hasMore: true, poll again at once; otherwise wait nextPollMs. A null cursor starts from now and returns nothing. A cursor that can't be resumed answers truncated: true and a fresh cursor, never an error. maxEvents is 100 unless you ask for fewer or more, up to 1,000.

Webhook

Subscribe an HTTPS endpoint to releases
curl -s https://instruction.md/mcp \
  -H 'authorization: Bearer <access token>' \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: events/subscribe' \
  -H 'mcp-name: md.instruction.activity' \
  -d '{"jsonrpc":"2.0","id":1,"method":"events/subscribe","params":{
        "name":"md.instruction.activity",
        "arguments":{"orgId":"org_01JD8Q4ZK3W5Y7A9C1E3G5J7M9","types":["version.published"]},
        "delivery":{"mode":"webhook","url":"https://hooks.example.com/instruction-md","secret":"whsec_<24 to 64 random bytes, base64>"},
        "ttlMs":3600000,
        "_meta":{
        "io.modelcontextprotocol/protocolVersion":"2026-07-28",
        "io.modelcontextprotocol/clientInfo":{"name":"my-follower","version":"1.0.0"},
        "io.modelcontextprotocol/clientCapabilities":{}}}}'

The gateway delivers webhooks the Standard Webhooks way:

  1. Verification. Before the first delivery, the gateway POSTs {"type": "verification", "challenge": "…"} to your URL. Answer 2xx with {"challenge": "…"}, the same value. Until you do, the subscription isn't made.
  2. Each delivery is one POST with the occurrence as its JSON body and the headers webhook-id (the event's id, the same on every retry), webhook-timestamp and webhook-signature. The signature is v1, followed by the base64 HMAC-SHA256 of <id>.<timestamp>.<body> under your secret. While a secret is being replaced, the header carries two signatures.
  3. Retries. Answer 2xx to acknowledge. 410 or 413 gives that event up at once. Anything else is retried with a growing pause, a few times over about 15 minutes. A repeat has the same webhook-id: drop the ones you have seen.
  4. Lifetime. A subscription lasts ttlMs: one hour unless you say, between 5 minutes and 24 hours, and never past your token's expiry. The answer's refreshBefore says when it ends. Subscribe again with the same name, arguments and URL before then to renew it. That also replaces the secret, and resumes a subscription that was suspended after too many failures.
  5. Stop with events/unsubscribe and the same name, arguments and URL.

The URL must be https, on a public address. The gateway refuses private, loopback and internal addresses, and never follows a redirect. The secret is yours: whsec_ and 24 to 64 random bytes in base64. Keep it out of code.

A receiver that checks the signature (Node.js)
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const secret = Buffer.from(process.env.WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");
const seen = new Set(); // webhook-id values already handled: a retry repeats the same one

createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    const id = req.headers["webhook-id"], ts = req.headers["webhook-timestamp"];
    const expected = createHmac("sha256", secret).update(`${id}.${ts}.${body}`).digest();
    const valid = String(req.headers["webhook-signature"] ?? "").split(" ").some((s) => {
      const given = Buffer.from(s.replace(/^v1,/, ""), "base64");
      return given.length === expected.length && timingSafeEqual(given, expected);
    });
    if (!valid || Math.abs(Date.now() / 1000 - Number(ts)) > 300) { res.writeHead(401).end(); return; }
    const message = JSON.parse(body);
    // the gateway's first POST asks you to prove you want the deliveries
    if (message.type === "verification") { res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ challenge: message.challenge })); return; }
    if (!seen.has(id)) { seen.add(id); handle(message); } // an event: { eventId, name, timestamp, data: { row }, cursor }
    res.writeHead(204).end();
  });
}).listen(8080);

function handle(event) {
  if (event.data?.row?.type === "version.published") console.log("released", event.data.row.instruction_id, event.data.row.version_id);
}

Persist the last cursor your receiver saw. After an outage, subscribe again with it and the gateway delivers what you missed, within the time events are kept.

A webhook subscription to a limited event holds one of the plan's places for as long as it lives, like a stream.

The live-updates limit

Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited

On a plan with this limit, that many consumers at a time may hold live updates for an organization's instructions. Reading is never limited. A consumer that is refused still reads its instructions whenever it needs to, and takes a place once one is free.

What counts

A consumer is one sign-in through one client: the person or agent, its token's OAuth client, and the MCP client's name. One consumer's streams count once, so an agent that listens and streams events holds one place.

What the limit covers:

  • The event md.instruction.activity, by stream, poll lease or webhook.
  • The event md.instruction.releases, by stream, poll lease or webhook.
  • A subscription to an instruction:// address, except instruction://delivery-keys.json and the publisher keys at instruction://pub/….

What it doesn't cover: the carets (md.instruction.presence), deployments' events and addresses, your own me:// and org:// views, the editor, instruction.md's own pages, and every organization whose plan has no limit.

How a place is held

The gateway asks the server before anything live opens: a stream, a poll lease, a webhook subscription or a resource subscription. It asks again every 60 seconds while it lives. A place is held for 120 seconds past its last renewal, so a consumer that vanished frees its place within 2 minutes. A poller holds its place for 120 seconds past its last poll: a poll lease is never released early.

Which organization: the instruction's, when the stream names one (by instructionId or address); the one named by orgId; else every organization you belong to that has the limit. A stream over all of them is refused when any one is taken, and the refusal names that organization, so you can ask for one.

The organization's own consumers, its members and its agents, are refused only by each other. A stranger following a public instruction holds a place only until one of the organization's own opens: the stranger's next renewal is then refused.

When it is refused

A refused consumer gets a JSON-RPC error, code -32025. Its message is the server's words, and its data is the limit_reached error whole:

A refused events/stream, poll or listen
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32025,
    "message": "this workspace's plan gives live updates to one agent or AI app at a time, and another is listening now. Reading is not limited: read the instruction whenever you need it. For live updates, try again in 42 seconds or once the other has stopped, or upgrade the workspace (orgs_billing_checkout)",
    "data": {
      "code": "limit_reached",
      "message": "this workspace's plan gives live updates to one agent or AI app at a time, and another is listening now. Reading is not limited: read the instruction whenever you need it. For live updates, try again in 42 seconds or once the other has stopped, or upgrade the workspace (orgs_billing_checkout)",
      "details": {
        "limit": "realtimeConsumers",
        "max": 1,
        "used": 1,
        "orgId": "org_01JD8Q4ZK3W5Y7A9C1E3G5J7M9",
        "plan": "community",
        "upgrade": "orgs_billing_checkout",
        "retryAfterSeconds": 42,
        "reads": "unlimited"
      }
    }
  }
}

What to do:

  • Keep reading. data.details.reads is "unlimited": read the instruction on your own schedule, such as every 60 seconds as instruction.md's followers do.
  • Ask again after data.details.retryAfterSeconds, the time until the oldest place may be free. instruction.md's clients wait that long, at least 5 seconds and at most 2 minutes.
  • Or upgrade: data.details.upgrade names the tool an organization's admin or billing person calls.

A stream that is already open and whose renewal is refused is ended with the same error. An events stream gets notifications/events/terminated first.

instruction watch and the SDK followers handle this for you. instruction watch prints live updates are taken: … Still reading on schedule. once, and goes on reading.

Who holds the place

instructions_consumers_list shows each follower of an instruction. When the organization's plan limits live updates, it adds how many places there are and how many are held:

instructions_consumers_list, its liveUpdates
{
  "liveUpdates": {
    "max": 1,
    "plan": "community",
    "held": 1
  }
}

In the editor, the same numbers are beside an instruction's followers.

A person who didn't allow live updates

A person who connects an AI app can choose not to let it follow changes live. That app's live updates are refused with scope_required, "the person connected this app without live updates: they can allow them in instruction.md, Settings, Connected apps", and details.scope instructions:follow. It can still read. The person allows more under Your account ▸ Connected apps.

The app feed

An app a person connected with Sign in with instruction.md follows the releases that person lets it follow. That is every instruction they can read under the scope instructions:all, or the instructions they chose under instructions:selected with instructions:follow. The app has two ways to hear of them, and both answer the same items:

  • The event md.instruction.releases, by stream, poll or webhook. It takes no arguments: each app receives only the items for its own client and the person whose token it holds. It counts toward the live-updates limit.
  • The tool instructions_releases_list, which the app calls on its own schedule. It is a read, so it is never limited.

Each item is one of three kinds: release (a new version of a followed instruction), added (an instruction the app now follows) or removed (one it no longer follows, such as one deleted or taken out of the grant). event names the change behind it, such as version.published. A removal names only the instruction: no title, version or owner. Read the item's uri for the text: instruction://<id>@<versionId> for a release, instruction://<id> otherwise.

Poll with instructions_releases_list

Call it first without a cursor. The answer is a snapshot: the latest released version of each instruction the grant follows, with snapshot: true and a nextCursor.

The first call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_releases_list",
    "arguments": {}
  }
}
The snapshot (structuredContent)
{
  "items": [
    {
      "kind": "release",
      "event": "version.published",
      "instructionId": "ins_01JD8Q5V0YB3X2K7M9N4P6R8ST",
      "owner": "acme",
      "name": "support-agent",
      "title": "Support agent",
      "versionId": "ver_01JD8R2M4P6T8V0X2Z4B6D8F0H",
      "number": 3,
      "uri": "instruction://ins_01JD8Q5V0YB3X2K7M9N4P6R8ST@ver_01JD8R2M4P6T8V0X2Z4B6D8F0H",
      "at": "2026-11-22T09:14:03Z"
    }
  ],
  "snapshot": true,
  "nextCursor": "0.918274.1"
}

Then call it with the last nextCursor you got. The answer is every release, addition and removal since, in the order they happened, with snapshot: false. limit is 100 unless you ask for fewer or more, up to 500. When nothing happened, items is empty and nextCursor is the one you sent. Keep the cursor between runs.

The next call
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "instructions_releases_list",
    "arguments": {
      "cursor": "0.918274.1",
      "limit": 100
    }
  }
}
What changed since (structuredContent)
{
  "items": [
    {
      "kind": "release",
      "event": "version.published",
      "instructionId": "ins_01JD8Q5V0YB3X2K7M9N4P6R8ST",
      "owner": "acme",
      "name": "support-agent",
      "title": "Support agent",
      "versionId": "ver_01JD8S7B9D1F3H5K7M9P1R3T5V",
      "number": 4,
      "uri": "instruction://ins_01JD8Q5V0YB3X2K7M9N4P6R8ST@ver_01JD8S7B9D1F3H5K7M9P1R3T5V",
      "at": "2026-11-23T08:02:41Z"
    },
    {
      "kind": "removed",
      "event": "instruction.deleted",
      "instructionId": "ins_01JD8Q6W2A4C6E8G0J2L4N6Q8S",
      "versionId": null,
      "number": null,
      "uri": "instruction://ins_01JD8Q6W2A4C6E8G0J2L4N6Q8S",
      "at": "2026-11-23T10:30:00Z"
    }
  ],
  "snapshot": false,
  "nextCursor": "0.921730.2"
}

Only an app's token gets the feed. Any other caller is refused validation with details.field cursor. An app token without the scopes above is refused forbidden with details.reason app_scope. A cursor this tool didn't answer is refused validation.

If it doesn't work

What you seeWhyWhat to do
JSON-RPC -32025, limit_reachedAnother consumer holds the plan's live updates.Keep reading, and ask again after retryAfterSeconds. See When it is refused.
JSON-RPC -32020The request has no Mcp-Name header, or one that differs from params.name.Send the event's name in Mcp-Name.
The subscription is acknowledged, but nothing ever arrivesThe address is the owner/name form, which is never told.Subscribe to instruction://ins_…@<ref>. See Which addresses tell you.
Events stream but no updates arrive, or they arrive in burstsA proxy in front of your client buffers the stream.Turn buffering off for https://instruction.md/mcp.
scope_required with instructions:followThe person connected the app without live updates.Ask them to allow it under Your account ▸ Connected apps, or read on a schedule.
A webhook subscribe fails, or nothing is deliveredThe URL is not public HTTPS, or the endpoint didn't answer the verification challenge.Answer the challenge with its value, from a public HTTPS address.
Still stuckAsk on Support with the time, the event or address, and the error.

Every error code is on Errors.

Questions

How do I receive release events by webhook?

Call events/subscribe with the event md.instruction.activity, the argument types: ["version.published"], and delivery: {mode: "webhook", url, secret}. Answer the gateway's verification challenge, check each delivery's signature, and subscribe again before refreshBefore. See Webhook.

Does a second agent still work when the live updates are taken?

Yes. Reading is never limited, so it reads on its own schedule and asks for live updates again after retryAfterSeconds. See When it is refused.

Should I subscribe to the address or to events?

To keep one instruction current, subscribe to its address and read it again when told. To react to what happens across instructions, such as releases, comments or proposals, use events. See Reading and live updates.

How soon is a place freed when an agent stops?

At once when it closes its stream. When it vanishes without closing, or a poller stops polling, within 2 minutes of the last time it was heard. See How a place is held.

Last checked against the product:

Was this page helpful? Report a problem