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

resources/read
{
  "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": {}
    }
  }
}
Its headers
mcp-protocol-version: 2026-07-28
mcp-method: resources/read
mcp-name: instruction://acme/support-agent@stable
The answer
{
  "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"
        }
      }
    }
  ]
}
  • uri is 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), or instruction://{id}@ver_… for a pinned version, also when it was asked as @v3 or @3. Subscribe to this form (see Subscriptions).
  • text is 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, and md.instruction/hostMatter says so.
  • mimeType is text/markdown; variant=instruction, or application/vnd.instruction-md.sealed+json for an instruction in a sealed workspace (beta, not yet independently reviewed), whose text is the sealed envelope as released. See Sealed instructions for developers.
  • _meta holds the version's facts. md.instruction/signature, md.instruction/kid and md.instruction/publisherKeys are there when the version is signed; verify the signature against the keys at publisherKeys (Signing and verification). md.instruction/revoked is there when the version was withdrawn. md.instruction/policy carries the organization's policy for the text.
  • md.instruction/cache says how long the answer may be kept: { "immutable": true } for a pinned version without host-integrations lines, otherwise maxAge 30 seconds, with an etag either 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.

AddressWhat it isTypeSubscribe
instruction://index.jsonInstructions in effect for you. The instructions you follow (your bindings) and the version each ref points at now.application/json
instruction://delivery-keys.jsonDelivery keys. The platform's delivery-signing public keys.application/json
instruction://pub/{owner}/keys.jsonPublisher 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/markdownyes
instruction://{id}An instruction. instruction://{id}: its latest version (its default ref) with md.instruction/* metadata.text/markdownyes

me://

You: your profile, preferences, favorites, recent instructions, inbox, exports and access requests. People only.

AddressWhat it isTypeSubscribe
me://profileYour profile. Your name, handle, title, time zone and language.application/json
me://preferencesYour preferences. Your synced preferences: appearance, editor, notifications, privacy.application/json
me://favoritesYour favorites. The instructions you starred.application/jsonyes
me://recentRecently opened. The instructions you opened recently.application/json
me://inboxYour inbox. Your notifications, newest first: mentions, suggestions, comments, access requests, releases of what you follow.application/jsonyes
me://exportsYour 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://requestsYour 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.

AddressWhat it isTypeSubscribe
org://{slug}/workspaces/{ws}/treeA 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.

AddressWhat it isTypeSubscribe
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/jsonyes

catalog://

Public lists: templates, public instructions, plans.

AddressWhat it isTypeSubscribe
catalog://templatesTemplates. The templates you can start an instruction from.application/json
catalog://explorePublic instructions. Public instructions, recently updated first.application/json
catalog://plansPlans. The plans and what each allows.application/json

spec://

The instruction language: its kinds, insert snippets and JSON Schema.

AddressWhat it isTypeSubscribe
spec://kindsThe language's kinds. Every kind of block the instruction language has, its form and what it delivers.application/json
spec://insertsInsert snippets. The snippets the editor offers for each kind.application/json
spec://schemaThe 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.

AddressWhat it isTypeSubscribe
skill://instruction-md/index.jsonSkills. Every skill this server offers (SEP-2640 layout), with its files and their digests.application/json
skill://instruction-md/{skill}/SKILL.mdA 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.

AddressWhat it isTypeSubscribe
ui://instruction.md/browseBrowse 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/reviewReview 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/draftAn 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:

AddressNotified when
me://favoritesYour inbox or favorites change
me://inboxYour 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.

subscriptions/listen
{
  "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.

Shell
curl -si -H 'accept: text/markdown' https://instruction.md/acme/support-agent@stable
Output
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-spec and, when signed, instruction-signature name the version. repr-digest is 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 in content-location. A pinned version is kept a year (immutable) and carries last-modified, unless host-integrations lines were added (then instruction-host-matter: host-integrations, and it is kept 60 seconds).
  • If-None-Match and, for a pinned version, If-Modified-Since answer 304.
  • The link header 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, the instruction:// 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.

Shell
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

Last checked against the product:

Was this page helpful? Report a problem