Підключити агента
Реєстр — це одна точка доступу MCP: https://instruction.md/mcp. Агент читає інструкцію як ресурс, а
той, що підписується на неї (agentd, послідовники з SDK), отримує сповіщення, коли ви публікуєте нову версію, і
перечитує інструкцію без перезапуску. Claude Code і Codex на ресурси не підписуються: вони дотримуються
інструкції через хуки, які налаштовує одна команда (Claude Code,
Codex, англійською).
Сервер працює за протоколом MCP 2026-07-28, без стану: ідентифікатора сесії немає, а кожен запит
містить версію протоколу, дані клієнта та його можливості, тож відповісти може будь-яка репліка сервера. Підписка —
це потік subscriptions/listen. Наші власні клієнти працюють саме так: студія, CLI
instruction і бібліотеки для TypeScript, Python та Go. Це єдиний протокол, який підтримує
instruction.md: хост підключається з версією 2026-07-28.
Оновлення наживо та читання
Агент отримує інструкцію двома способами. Він читає її щоразу, коли потрібна найновіша версія. І може отримувати оновлення наживо: сервер повідомляє про зміну в ту саму мить, тож агентові не треба питати.
Читання ніколи не обмежується, на жодному тарифі: будь-яка кількість агентів, так часто, як їм потрібно.
Оновлення наживо залежать від тарифу робочого простору. На Community їх одночасно отримує один агент або ШІ-застосунок. Починаючи з Pro — будь-яка кількість. Якщо в робочому просторі Community другий агент просить оновлення наживо, поки їх отримує інший, йому про це повідомляють і кажуть, коли спробувати знову. Він усе одно працює: читає найновішу версію за власним розкладом (наші бібліотеки перевіряють щохвилини, якщо ви не задали інший інтервал) і займає місце, щойно перший агент зупиниться. Сама студія цього місця ніколи не займає.
Для тих, хто пише клієнт: оновлення наживо — це subscriptions/listen на адресі
instruction:// та події MCP Events md.instruction.activity і
md.instruction.releases (потік, опитування або вебхук). Відмова — це помилка JSON-RPC
-32013 з нашою помилкою в полі data: code: "limit_reached", повідомлення та
details з полями limit: "realtimeConsumers", max, plan,
retryAfterSeconds і upgrade. Потік, що втрачає своє місце (його забирає власний агент
робочого простору в агента ззовні), завершується повідомленням notifications/events/terminated з тією
самою помилкою. Агент рахується як один, хоч скільки потоків він відкриє. Місце звільняється, коли його потоки
закриваються, або через дві хвилини після останнього сигналу від агента.
Адреса інструкції
Кожна публічна інструкція має вебадресу, https://instruction.md/{owner}/{name}, однакову для
людей і агентів. Браузер отримує її сторінку: саму інструкцію, її URI instruction:// і налаштування,
щоб стежити за нею. Агент, який надсилає Accept: text/markdown або взагалі не надсилає заголовка
Accept, як це роблять curl і більшість програм, отримує сам опублікований текст, дослівно, з версією
в заголовках. Адреса в обох випадках та сама: форми з .md немає. @stable або
@v3 після назви читає посилання (ref) або одну версію, а
https://instruction.md/{owner} показує публічні інструкції власника. Щоб стежити за інструкцією,
коли вона змінюється, підключіть агента через MCP, як описано нижче. Файл /llms.txt на
сайті перелічує документацію та шаблони для агентів.
curl -H 'Accept: text/markdown' https://instruction.md/instruction-md/code-review Claude Code
claude mcp add instruction-md --transport http https://instruction.md/mcp
# then in a session: read instruction://acme/support-agent@stable Щоб інструкція стала інструкцією проєкту й оновлювалася під час сеансу, дивіться Claude Code (англійською).
Codex
Codex розмовляє ранішою версією MCP, ніж цей сервер, тож під’єднується через власний MCP-сервер командного рядка. Як це налаштувати й як дотримуватися інструкції під час сеансу, дивіться на сторінці Codex (англійською).
Cursor та інші MCP-клієнти
{
"mcpServers": {
"instruction-md": {
"command": "npx",
"args": ["-y", "instruction.md", "mcp", "--follow", "instruction://acme/support-agent@stable", "--url", "https://instruction.md/mcp"]
}
}
}
Кожне читання потребує входу. Claude і ChatGPT самі проводять вас через вхід. Cursor, VS Code та інші клієнти, що
говорять старішою версією MCP, ніж instruction.md, підключаються через stdio-сервер CLI вище (VS Code: той самий запис
у servers файлу .vscode/mcp.json, з "type": "stdio"), у який ви входите один
раз командою instruction login. Агенти використовують власні облікові дані.
Що дозволено застосунку зі штучним інтелектом
Коли ви підключаєте застосунок зі штучним інтелектом, як-от Claude, ChatGPT чи редактор коду, instruction.md спершу питає: What may it do? (що йому дозволено). Ви обираєте один із чотирьох варіантів, і кожен наступний включає попередній:
| Варіант | Застосунок може |
|---|---|
| Read only (лише читання) | Читати ваші інструкції та їхні версії. Він нічого не змінює. |
| Read and write drafts (читання і чернетки) | Ще й створювати інструкції, змінювати чернетки, пропонувати зміни та коментувати. Нічого не публікується. |
| Read, write and publish (читання, чернетки, публікація) | Ще й випускати нові версії, спершу спитавши вас. Саме цей варіант сторінка пропонує першим. |
| Everything you can do (усе, що можете ви) | Ще й надавати доступ, видаляти, змінювати ваш обліковий запис і керувати організацією, якою керуєте ви. |
Окремий перемикач, Follow changes live, визначає, чи може застосунок стежити за інструкціями та дізнаватися про їхні зміни. Якщо застосунок має лише читати і стежити, оберіть Read only і залиште перемикач увімкненим.
Застосунок бачить тільки ті інструменти, які дозволяє ваш вибір, а сервер відхиляє будь-що інше, хай яка у вас роль. Щоб змінити вибір або відключити застосунок, відкрийте Settings ▸ Connected apps і натисніть Change what they may do. Зміна набирає чинності за кілька хвилин. Застосунок, підключений раніше, спитає про це під час наступного входу, а доти діє від вашого імені повністю.
Інструменти організації в хості
Для адміністрування організації потрібна ще одна область доступу OAuth, org:admin, і варіант
Everything you can do під час підключення застосунку. Без неї хост
показує інструменти для написання, рецензування, випуску, поширення інструкцій і стеження за ними, але не ті 28,
що керують організацією: її учасниками та запрошеннями, робочими просторами, політикою, ключами підпису, агентами,
оплатою та журналом аудиту. Хост без цієї області має коротший список інструментів.
- Сервер не називає цю область там, де хост дізнається, як входити (у метаданих захищеного ресурсу та у виклику відповіді 401), тож хост входить для щоденних інструментів і показує їх.
-
Хост отримує
org:adminлише тоді, коли просить її за назвою під час вашого входу, якщо він дає змогу вибрати області, які запитує. Тоді сторінка входу показує «Administer your organizations on instruction.md» серед того, на що ви погоджуєтеся, а хост показує інструменти організації. -
Хост, який називає свої області під час першого підключення, має лише їх: якщо він тоді пропустив
org:admin, то не зможе попросити її під час наступного входу (запит буде відхилено як недійсну область). Видаліть конектор і додайте його знову, цього разу вказавшиorg:admin. -
Студія та CLI
instructionзавжди мають цю область. Якщо ваш хост її не має, керуйте організацією там: у Settings у студії або командамиinstruction agents,instruction keysіinstruction auditу CLI. - Агенти ніколи її не отримують: облікові дані агента не дають змоги адмініструвати організацію.
Область лише дає клієнтові змогу бачити й викликати ці інструменти. Кожен інструмент однаково перевіряє вашу роль: організацію змінюють лише її власники та адміністратори, а оплату — учасники з доступом до оплати.
agentd
agentd версії 1.18 і новіших підтримує MCP 2026-07-28 та MCP Events. Дайте
агентові власні облікові дані (Settings ▸ Agents у студії або instruction agents create; організація
на тарифі Pro чи вищому), а потім стежте за інструкцією за її ідентифікатором і посиланням:
# agentd 1.18 or later, as a daemon: the instruction is the policy every conversation follows
agent:
name: support-desk
instruction:
mcp:
server: instruction-md
# the instruction's id at a ref: publishing moves the ref, and the server pushes the re-read
resource: "instruction://ins_01M…@stable"
events: [md.instruction.activity]
unavailable: keep
trust:
- uri: "instruction://ins_01M…@stable"
publisher: "https://instruction.md/pub/acme"
intelligence:
endpoints: https://api.anthropic.com
dialect: anthropic
model: claude-sonnet-5
token: "{{secret:ANTHROPIC_API_KEY}}"
mcp:
servers:
- name: instruction-md
endpoint: https://instruction.md/mcp
auth:
kind: oauth2
grant: client_credentials
client_id: "<your agent's client id>"
client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"
# agents sign in on their own realm
token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
store:
kind: file
file: { path: ./support-desk-state }
a2a:
listen: http://127.0.0.1:8420
lifecycle:
run_until: drained
Публікація пересуває посилання, сервер надсилає в підписку agentd сигнал перечитати, і наступний хід читає нову
версію: agentd записує в журнал instruction.applied, зі старої версії на нову, протягом секунди.
Адреса виду власник/назва (instruction://acme/support-agent@stable) теж працює; тоді agentd дізнається
про публікацію версії через MCP Events, на кілька секунд пізніше.
Якщо закріпити publisher, перевірка стає обов’язковою: agentd під час кожного читання звіряє підпис
автора з набором ключів видавця, відхиляє версію, підписану відкликаним ключем, і залишає останню справну
інструкцію, а не застосовує те, чого не може перевірити. Підпис версії називає інструкцію за її ідентифікатором,
тож закріплюйте адресу з ідентифікатором. Токен агента видає окремий realm для агентів, якого метадані MCP-сервера
не називають: token_url вказує, де він.
Ваш власний код
Пакет instruction.md в npm містить бібліотеку-послідовника, що реалізує клієнтську половину
специфікації: зберігає останню справну версію, дотримується політик, перевіряє підписи з пошуком ключів і звітує,
що саме застосовано. Його MCP-клієнт, instruction.md/client, дає протокол без стану; підписка
відновлюється після розриву й перечитує інструкцію. SDK для Python і Go мають такого самого послідовника на тому
самому протоколі (python -m instruction_md watch, NewHTTPClient).
npm install instruction.md
pip install instruction-md # the Python SDK import { asSdkClient, createClient } from "instruction.md/client";
import { InstructionFollower } from "instruction.md/consumer";
const follower = new InstructionFollower({
// MCP 2026-07-28, stateless (or any MCP client with the SDK's Client shape)
client: asSdkClient(createClient({ url: "https://instruction.md/mcp", token: () => token })),
uri: "instruction://acme/support-agent@stable",
mode: "follow",
policy: { requireSignature: true, publisher: "https://instruction.md/pub/acme" },
report: { consumer: { label: "support-bot (prod)", kind: "agent" } },
onApply: (applied) => setSystemPrompt(applied.text),
onHold: (reason) => log.warn({ reason }, "kept the last good instruction"),
});
await follower.start(); Як безпечно стежити за інструкцією, що змінюється
| Вибір | Що він означає |
|---|---|
@stable | Посилання, яке ви пересуваєте свідомо. Рекомендовано для всього, що працює в продакшні. |
@latest | Пересувається з кожною публікацією. Зручно для розробки. |
@ver_… | Закріплено за однією незмінною версією. Ніколи не змінюється. |
Хоч би за чим ви стежили, отримувач, який не може прочитати або перевірити інструкцію, залишає ту версію, яку вже мав. Якщо реєстр недоступний, це означає «немає оновлень», але ніколи не «немає інструкцій».
Як повідомити реєстру, що ви застосували
Отримувач може оголосити прив’язку та повідомити, яку версію застосував. Саме це наповнює подання Consumers: які агенти дотримуються інструкції, яку версію має кожен і скільки часу триває перехід на нову. Це необов’язково, і ваш вміст при цьому нікуди не надсилається.