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.
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 asinstruction://ins_…@latestafter a release. You then read the address again. This is what followers use. - An event (
events/stream,events/pollor a webhook) says what happened, such asversion.publishedorcomment.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.
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":{}}}}' 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:
| Address | What it is | Counts toward the limit |
|---|---|---|
me://favorites | Your favorites | No |
me://inbox | Your inbox | No |
instruction://{id}@{selector} | An instruction at a ref or version | Yes |
instruction://{id} | An instruction | Yes |
deployment://{org}/{platform} | A platform's deployments | No |
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 alsoinstruction://<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.
| Event | What it is for | Arguments | Kept | Counts toward the limit |
|---|---|---|---|---|
md.instruction.activity | Everything that happens to the instructions and organizations you can see. The one most followers and integrations want. | instructionId, orgId, types | 7 days, at most 100,000 events | Yes |
md.instruction.presence | Where people working on a draft have their carets. The editor's own; it needs instructionId. | instructionId (required) | 2 minutes, at most 20,000 events | No |
md.instruction.releases | An app's feed of the releases a person lets it follow (Sign in with instruction.md). | None | 7 days, at most 100,000 events | Yes |
md.deployment.activity | A runner's feed: agents a deployment made, approved, released or retired, and rule changes. | orgId, platform, ruleId, instructionId, types | 7 days, at most 100,000 events | No |
The arguments filter what you receive:
instructionId: only this instruction's events. It must be theins_…id, not owner/name.orgId: only this organization's events (org_…).types: only these types, from the lists below.platformandruleId(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
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":{}}}}' 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
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":{}}}}' {
"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
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:
- Verification. Before the first delivery, the gateway POSTs
{"type": "verification", "challenge": "…"}to your URL. Answer2xxwith{"challenge": "…"}, the same value. Until you do, the subscription isn't made. - 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-timestampandwebhook-signature. The signature isv1,followed by the base64 HMAC-SHA256 of<id>.<timestamp>.<body>under your secret. While a secret is being replaced, the header carries two signatures. - Retries. Answer
2xxto acknowledge.410or413gives that event up at once. Anything else is retried with a growing pause, a few times over about 15 minutes. A repeat has the samewebhook-id: drop the ones you have seen. - 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'srefreshBeforesays 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. - Stop with
events/unsubscribeand 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.
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, exceptinstruction://delivery-keys.jsonand the publisher keys atinstruction://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:
{
"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.readsis"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.upgradenames 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:
{
"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.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "instructions_releases_list",
"arguments": {}
}
} {
"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.
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "instructions_releases_list",
"arguments": {
"cursor": "0.918274.1",
"limit": 100
}
}
} {
"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 see | Why | What to do |
|---|---|---|
JSON-RPC -32025, limit_reached | Another consumer holds the plan's live updates. | Keep reading, and ask again after retryAfterSeconds. See When it is refused. |
JSON-RPC -32020 | The 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 arrives | The 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 bursts | A proxy in front of your client buffers the stream. | Turn buffering off for https://instruction.md/mcp. |
scope_required with instructions:follow | The 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 delivered | The 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 stuck | Ask 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.