Resources and addresses
Every address the MCP server reads, what each one answers, and which ones notify you when they change. For developers reading instructions with resources/read, following them with subscriptions, or fetching public ones over plain HTTP.
The tables on this page are generated at build time from the server's registry and the production gateway's configuration.
An instruction's address
An instruction is named in one of two ways, and either can carry a selector after @:
| Address | Reads |
|---|---|
instruction://{owner}/{name} |
The version the instruction's default ref points at (its default ref is latest unless changed) |
instruction://{owner}/{name}@{selector} |
The version the selector names |
instruction://{id} |
The same as the first, by the instruction's id (ins_…) |
instruction://{id}@{selector} |
The same as the second, by id |
A selector is one of:
| Selector | Example | Means |
|---|---|---|
| A ref's name | @latest, @stable, @canary |
Follow that ref: the address reads whatever version it points at now |
v and a number, or the number |
@v3, @3 |
Pin version 3 |
| A version id | @ver_01JX… |
Pin that version |
owner is an organization's slug and name the instruction's name. Both are case-insensitive. A slug or name the instruction had before a rename or a transfer still resolves to it, for good. The id never changes.
Refs other than latest exist only once someone creates them: stable is never made for you. Create it with instructions_refs_set (Tool reference), instruction refs <owner>/<name> set stable <version>, or in the editor. Reading a ref that doesn't exist answers not_found. So does reading the default ref of an instruction that has no version yet, with details.reason: "unpublished".
What a read answers
{
"jsonrpc": "2.0", "id": 3, "method": "resources/read",
"params": {
"uri": "instruction://acme/support-agent@stable",
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
"io.modelcontextprotocol/clientCapabilities": {}
}
}
} mcp-protocol-version: 2026-07-28
mcp-method: resources/read
mcp-name: instruction://acme/support-agent@stable {
"contents": [
{
"uri": "instruction://ins_01JX<…>@stable",
"mimeType": "text/markdown; variant=instruction",
"text": "---\nspec: \"1\"\ntitle: Support Agent\n---\n\n# Support Agent\n\n…",
"_meta": {
"md.instruction/canonical": "instruction://ins_01JX<…>",
"md.instruction/versionId": "ver_01JX<…>",
"md.instruction/number": 4,
"md.instruction/ref": "stable",
"md.instruction/spec": "1",
"md.instruction/digest": "sha256:<…>",
"md.instruction/owner": "acme",
"md.instruction/name": "support-agent",
"md.instruction/title": "Support Agent",
"md.instruction/visibility": "internal",
"md.instruction/kind": "instruction",
"md.instruction/publisher": "https://instruction.md/pub/acme",
"md.instruction/signature": "<compact JWS>",
"md.instruction/kid": "<key id>",
"md.instruction/publisherKeys": "instruction://pub/acme/keys.json",
"md.instruction/cache": { "maxAge": 30, "etag": "sha256:<…>" },
"md.instruction/extension": {
"application": "hydrate", "role": "system", "priority": 0.5,
"version": "ver_01JX<…>", "digest": "sha256:<…>", "digestOf": "authored", "spec": "1"
}
}
}
]
} uriis the address served, always by id and always with what it read:instruction://{id}@{ref}for a ref (the default ref's name when the address named none, such as@latest), orinstruction://{id}@ver_…for a pinned version, also when it was asked as@v3or@3. Subscribe to this form (see Subscriptions).textis the version's text exactly as it was released. When the organization's integrations policy applies, its host-integrations lines are added to the front matter, outside the signed bytes, andmd.instruction/hostMattersays so.mimeTypeistext/markdown; variant=instruction, orapplication/vnd.instruction-md.sealed+jsonfor an instruction in a sealed workspace (beta, not yet independently reviewed), whose text is the sealed envelope as released. See Sealed instructions for developers._metaholds the version's facts.md.instruction/signature,md.instruction/kidandmd.instruction/publisherKeysare there when the version is signed; verify the signature against the keys atpublisherKeys(Signing and verification).md.instruction/revokedis there when the version was withdrawn.md.instruction/policycarries the organization's policy for the text.md.instruction/cachesays how long the answer may be kept:{ "immutable": true }for a pinned version without host-integrations lines, otherwisemaxAge30 seconds, with anetageither way.
Every read is recorded, as a follow (a ref) or a pin (a version), which is how the people who manage an instruction see its consumers.
Views of an instruction
An instruction's other views take its id. instruction://{owner}/{name}/draft is not an address: the second part after the owner is read as a name.
| Address | Answers | Who may read it |
|---|---|---|
instruction://{id}/draft |
The draft's text as a release would take it (suggestions not yet accepted left out), with md.instruction/draftRevision (an edit's expectedRevision), the version it is based on, whether it changed since, pending suggestions and open threads |
Who may read the draft |
instruction://{id}/suggestions |
The suggestions waiting on the draft | Who may read the draft |
instruction://{id}/comments |
Comment threads in the order they are anchored in the text, each with its last 50 messages. Past 150,000 bytes the open threads are kept first and the answer has truncated: true |
Who may read the draft |
instruction://{id}/checkpoints |
The draft's checkpoints | Who may read the draft |
instruction://{id}/versions |
Every version, newest first (up to 200) | Readers |
instruction://{id}/refs |
Every ref and the version it points at | Readers |
instruction://{id}/meta |
Its public facts | Readers |
instruction://{id}/presence |
Who had it open in the editor in the last two minutes | Readers. Empty for a reader who may not read the draft |
instruction://{id}/events |
Its recent events (up to 100) | Readers |
instruction://{id}/activity |
Its activity (up to 100) | Its Admins |
instruction://{id}/consumers |
The agents and apps that follow it (up to 100) | Its Admins |
instruction://{id}/proposals |
Its proposals (up to 50) | Readers |
instruction://{id}/access |
Who has which permission on it (up to 500) | Its Admins |
instruction://{id}/comments/{thread} |
One comment thread | Who may read the draft |
instruction://{id}/checkpoints/{checkpoint} |
One checkpoint, with its text | Who may read the draft |
instruction://{id}/proposals/{proposal} |
One proposal | Readers |
instruction://{id}/connect/{host} |
How a host connects to follow it: claude, chatgpt, agentd, sdk, cli, or any other word for a generic answer |
Readers |
instruction://{id}/diff/{from}..{to} |
A unified diff between two versions, refs or draft (v2..v3, stable..draft) |
Readers, and the draft's readers for draft |
The lists are capped as shown. Use the matching tools (instructions_versions_list, instructions_comments_* and the rest) to page through more.
Keys and the index
| Address | Answers |
|---|---|
instruction://index.json |
The instructions in effect for you: the ones you follow (your bindings), each with the version its ref points at now |
instruction://pub/{owner}/keys.json |
An owner's publisher keys as a JWKS, with active, retired and revoked keys: what a verifier pins. An old slug finds the organization it became |
instruction://delivery-keys.json |
The platform's delivery-signing public keys |
Every resource, by scheme
me:// reads only for a person, never for an agent. org:// views that administer an organization need its admin. Every read takes the same rate limit as a read tool (Rate limits).
instruction://
Instructions: a version, a ref, the draft and the other views, diffs, the index of what you follow, and publisher keys.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
instruction://index.json | Instructions in effect for you. The instructions you follow (your bindings) and the version each ref points at now. | application/json | |
instruction://delivery-keys.json | Delivery keys. The platform's delivery-signing public keys. | application/json | |
instruction://pub/{owner}/keys.json | Publisher keys. instruction://pub/{owner}/keys.json: an owner's signing keys (JWKS with active, retired and revoked states), what verifiers pin. | application/json | |
instruction://{id}/diff/{range} | A diff. instruction://{id}/diff/{range}: the unified diff between two of an instruction's versions, refs or its draft (range = from..to). | application/json | |
instruction://{id}/{view}/{item} | One item of an instruction. instruction://{id}/{view}/{item}: one comment thread, checkpoint or proposal, or the connection snippet for a host. | application/json | |
instruction://{owner}/{name}@{selector} | An instruction at a ref, by name. instruction://{owner}/{name}@{selector}: a version (v3, ver_…) or ref of an instruction named by its owner and name. | text/markdown | |
instruction://{first}/{second} | An instruction's view, or an instruction by name. instruction://{id}/{view} (draft, suggestions, comments, checkpoints, versions, refs, meta, presence, events, activity, consumers, proposals, access) or instruction://{owner}/{name}. | text/markdown | |
instruction://{id}@{selector} | An instruction at a ref or version. instruction://{id}@{selector}: a version (v3, ver_…) or a ref (latest, stable…). | text/markdown | yes |
instruction://{id} | An instruction. instruction://{id}: its latest version (its default ref) with md.instruction/* metadata. | text/markdown | yes |
me://
You: your profile, preferences, favorites, recent instructions, inbox, exports and access requests. People only.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
me://profile | Your profile. Your name, handle, title, time zone and language. | application/json | |
me://preferences | Your preferences. Your synced preferences: appearance, editor, notifications, privacy. | application/json | |
me://favorites | Your favorites. The instructions you starred. | application/json | yes |
me://recent | Recently opened. The instructions you opened recently. | application/json | |
me://inbox | Your inbox. Your notifications, newest first: mentions, suggestions, comments, access requests, releases of what you follow. | application/json | yes |
me://exports | Your exports. Your exports still kept (7 days), newest first, each with the job that made it; and your export jobs of the last day with their state (queued, running, done, failed). | application/json | |
me://requests | Your access requests. The access you asked for, and the answers. | application/json | |
me://exports/{id}/{part} | A part of your export. me://exports/{id}/{part}: one part of an export's file (base64, at most 150,000 bytes); read them in order from 0 and join them. | application/zip | |
me://exports/{id} | Your export. me://exports/{id}: an export of yours (me_export), kept 7 days — its file's name, size and how many parts to read. | application/json |
org://
An organization you belong to, its administration views, and a workspace's tree.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
org://{slug}/workspaces/{ws}/tree | A workspace's tree. org://{slug}/workspaces/{ws}/tree: the projects, folders and instructions of a workspace you can see. | application/json | |
org://{slug}/{view} | An organization's view. org://{slug}/{view}: members, invitations, policy, keys, agents, usage, workspaces, events. | application/json | |
org://{slug} | An organization. org://{slug}: an organization you belong to. | application/json |
deployment://
The agents a deployment rule assigned to one platform.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
deployment://{org}/{platform} | A platform's deployments. deployment://{org}/{platform}: the agents assigned to a platform in an organization, by its id (org_…), as deployments_list answers them: each instruction, its ref and version, parameters, state, what waits for approval. Subscribable: it changes when a deployment does. | application/json | yes |
catalog://
Public lists: templates, public instructions, plans.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
catalog://templates | Templates. The templates you can start an instruction from. | application/json | |
catalog://explore | Public instructions. Public instructions, recently updated first. | application/json | |
catalog://plans | Plans. The plans and what each allows. | application/json |
spec://
The instruction language: its kinds, insert snippets and JSON Schema.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
spec://kinds | The language's kinds. Every kind of block the instruction language has, its form and what it delivers. | application/json | |
spec://inserts | Insert snippets. The snippets the editor offers for each kind. | application/json | |
spec://schema | The schema. The instruction language's JSON Schema. | application/json | |
spec://kinds/{kind} | A kind. spec://kinds/{kind}: one kind of block, explained. | application/json |
skill://
The server's skills and their files.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
skill://instruction-md/index.json | Skills. Every skill this server offers (SEP-2640 layout), with its files and their digests. | application/json | |
skill://instruction-md/{skill}/SKILL.md | A skill. skill://instruction-md/{skill}/SKILL.md: a skill's instructions. | text/markdown | |
skill://instruction-md/{skill}/reference/{file} | A skill's reference. skill://instruction-md/{skill}/reference/{file}: a skill's supporting file. | text/markdown |
ui://
The MCP Apps a host draws beside a tool's answer.
| Address | What it is | Type | Subscribe |
|---|---|---|---|
ui://instruction.md/browse | Browse instructions. An MCP App: your instructions, one's history and its proposals — opened beside instructions_list, instructions_versions_list and instructions_proposals_list. | text/html;profile=mcp-app | |
ui://instruction.md/review | Review a proposal. An MCP App: a proposal against the version it was based on, with Approve, Request changes, Merge and Close — opened beside instructions_proposals_get. | text/html;profile=mcp-app | |
ui://instruction.md/draft | An instruction's draft. An MCP App: an instruction's draft as the site draws it, the suggested changes waiting on it with Accept and Reject, what the validator finds, and requests to send to the conversation — opened beside instructions_get and instructions_create. | text/html;profile=mcp-app |
Templates are matched in the order they are listed in the registry, the more specific first, so instruction://{owner}/{name}@{selector} is tried before instruction://{first}/{second}, which reads either a view (when first is an ins_ id) or an instruction by owner and name.
Subscriptions
The server notifies a subscriber with notifications/resources/updated when the answer at the exact address it subscribed to changes. Only these addresses are watched:
| Address | Notified when |
|---|---|
me://favorites | Your inbox or favorites change |
me://inbox | Your inbox or favorites change |
instruction://{id}@{selector} | @ref: that ref moves or is deleted. A pinned version (@ver_…, @vN, @N): it is withdrawn. Either: the instruction is deleted, restored, archived, transferred or its visibility changes |
instruction://{id} | The default ref moves; the instruction is deleted, restored, archived, transferred or its visibility changes |
deployment://{org}/{platform} | A deployment on that platform changes, or its runner reports |
Subscribe to the id form. A read by owner and name answers the id form in contents[].uri: subscribe to that. A subscription to instruction://acme/support-agent@stable itself is never notified, because notifications name the id form only. A bare instruction://{id} is notified too when its default ref moves, but the read answers @{ref}, which is notified the same way.
Subscribe with a subscriptions/listen request that names the addresses in notifications.resourceSubscriptions, as listen() in the instruction.md package's MCP client does. Its answer is a server-sent event stream that starts with notifications/subscriptions/acknowledged and carries a notifications/resources/updated with the address for each change.
{
"jsonrpc": "2.0", "id": 4, "method": "subscriptions/listen",
"params": {
"notifications": { "resourceSubscriptions": ["instruction://ins_01JX<…>@stable"] },
"_meta": { "…": "as in every request" }
}
} After a notification, read the address again. A gates-only change to a ref (its policy, not its version) sends nothing.
The registry also marks instruction://index.json, org://{slug}/workspaces/{ws}/tree and instruction://{first}/{second} as changing, but the gateway doesn't watch them: hear their changes through the MCP Events stream md.instruction.activity instead.
Live updates are limited on some plans: on such a plan one agent or app at a time holds them, and reads are never limited. The limit, the refusal and the events are on Live updates, events and webhooks.
Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited
Web addresses
A public instruction also has a web address, https://instruction.md/{owner}/{name}, the same for people and agents. It is the only HTTP form: there is no .md address, and ?format= is ignored.
| Address | Answers |
|---|---|
/{owner}/{name} |
The default ref's version |
/{owner}/{name}@{ref} |
That ref's version |
/{owner}/{name}@v{N}, @ver_… |
One version, kept for good |
/{owner}/{name}/versions |
Every release and ref |
/{owner} |
The owner's public instructions |
/ins_{id}[@selector][/view] |
302 to the instruction's address now: a link that survives renames and transfers |
Content negotiation
One URL has two representations, picked by the Accept header alone. A browser's navigation, which prefers text/html, gets the page. Everything else (curl, an agent's fetch, no Accept header, a tie) gets the version's text exactly as released. A reader that accepts text/plain but no markdown type gets the same bytes as text/plain.
curl -si -H 'accept: text/markdown' https://instruction.md/acme/support-agent@stable HTTP/2 200
content-type: text/markdown; charset=utf-8; variant=instruction
instruction-version: v4
instruction-digest: sha256:<…>
instruction-id: instruction://ins_01JX<…>
instruction-spec: 1
instruction-signature: <compact JWS>
etag: "<…>"
cache-control: public, max-age=60
content-location: /acme/support-agent@v4
repr-digest: sha-256=:<…>:
link: <https://instruction.md/acme/support-agent>; rel="canonical", <https://instruction.md/acme/support-agent@v4>; rel="latest-version", <https://instruction.md/acme/support-agent/versions>; rel="version-history", <https://instruction.md/acme/support-agent/edit>; rel="edit-form", <instruction://ins_01JX<…>>; rel="alternate", <https://instruction.md/acme/support-agent@stable>; rel="alternate"; type="text/html"
vary: Accept, Accept-Language
access-control-allow-origin: *
content-security-policy: default-src 'none'; sandbox
content-disposition: inline; filename="support-agent.md"
---
spec: "1"
title: Support Agent
… instruction-version,instruction-digest,instruction-id,instruction-specand, when signed,instruction-signaturename the version.repr-digestis the SHA-256 of the bytes.- A ref's address is kept 60 seconds (
cache-control: public, max-age=60) and says the version it read incontent-location. A pinned version is kept a year (immutable) and carrieslast-modified, unless host-integrations lines were added (theninstruction-host-matter: host-integrations, and it is kept 60 seconds). If-None-Matchand, for a pinned version,If-Modified-Sinceanswer304.- The
linkheader names the canonical address, the latest version (not on a pinned version kept for good, which a later release would make wrong), the list of versions, the editor, theinstruction://id and the other representation.
Only public markdown
Only a public instruction with a released version is served over HTTP. Everything else answers the same 404: private, internal (your organization only), unreleased, in the trash, a ref or version that isn't there, a name that never was. The answer never says which, and never asks for a token. Read those over MCP, signed in.
curl -si https://instruction.md/acme/private-thing
HTTP/2 404
content-type: text/plain; charset=utf-8
cache-control: no-store
Nothing here
There is no public instruction at this address. A private one is read over MCP, signed in: https://instruction.md/docs/connect/ A person who may read an instruction that isn't public sees it at the same address in their browser: the 404 page asks the server for it over MCP, with that person's own sign-in.
Other answers: a withdrawn version answers 410. An address in other letters, with a trailing slash, or with %40 for its @ answers 301 to its canonical form (lower case, no trailing slash, a plain @). One a rename or move left behind answers 301 to the address it has now. Anything but GET and HEAD answers 405.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
not_found reading @stable |
The ref doesn't exist yet | Create it: instructions_refs_set, or instruction refs <owner>/<name> set stable <version> |
not_found with details.reason: "unpublished" |
The instruction has no version | Release one first: instructions_publish |
not_found for instruction://{owner}/{name}/draft |
Views take the id | Read instruction://{owner}/{name}, take the id from md.instruction/canonical, then read instruction://{id}/draft |
| A subscription never fires | It is on the owner/name form, or on an address the gateway doesn't watch | Subscribe to the uri a read answered (instruction://ins_…@stable) |
404 over HTTP for an instruction you can open |
It isn't public | Read it over MCP, signed in (Connect an MCP client) |
| A second agent gets no live updates | The plan's live-updates limit | See Live updates, events and webhooks. Reading still works |