Conectar un agente
El registro es un único punto de acceso MCP: https://instruction.md/mcp. Un agente lee una
instrucción como un recurso, y el que se suscribe a ella (agentd, los seguidores de los SDK) recibe un aviso cuando
publicas y vuelve a cargarla sin reiniciarse. Claude Code y Codex no se suscriben a recursos: siguen una
instrucción mediante hooks, que se configuran con un comando (Claude Code,
Codex, en inglés).
El servidor habla MCP 2026-07-28, el protocolo sin estado: no hay identificador de sesión, y cada
petición lleva su versión del protocolo, su cliente y sus capacidades, de modo que cualquier réplica del servidor
puede responderla. Una suscripción es un flujo subscriptions/listen. Nuestros propios clientes lo
hablan: el estudio, la CLI instruction y los seguidores para TypeScript, Python y Go. Es el único
protocolo que admite instruction.md: un host se conecta con 2026-07-28.
Actualizaciones en vivo y lectura
Un agente obtiene una instrucción de dos maneras. La lee cada vez que quiere la última versión. Y puede recibir actualizaciones en vivo: el servidor le avisa en el momento en que algo cambia, así que no tiene que preguntar.
La lectura nunca está limitada, en ningún plan: cualquier número de agentes, con la frecuencia que quieran.
Las actualizaciones en vivo dependen del plan del espacio de trabajo. En Community, las recibe un solo agente o aplicación de IA a la vez. A partir de Pro, cualquier número. Si un segundo agente pide actualizaciones en vivo en un espacio de trabajo Community mientras otro las tiene, se le informa de ello y de cuándo volver a intentarlo. Sigue funcionando: lee la última versión a su propio ritmo (nuestros seguidores comprueban cada minuto, salvo que fijes otro intervalo) y ocupa el puesto en vivo cuando el primero se detiene. El estudio nunca ocupa ese puesto.
Para quienes escriben un cliente: las actualizaciones en vivo son subscriptions/listen sobre una
dirección instruction:// y los eventos de MCP Events md.instruction.activity y
md.instruction.releases (flujo, sondeo o webhook). El rechazo es el error JSON-RPC
-32013, con nuestro error en su campo data: code: "limit_reached", un
mensaje y details con limit: "realtimeConsumers", max, plan,
retryAfterSeconds y upgrade. Un flujo que pierde su puesto (el agente propio del espacio
de trabajo se lo quita a uno de fuera) termina con notifications/events/terminated, que lleva el
mismo error. Un agente cuenta como uno, abra los flujos que abra. Un puesto queda libre cuando sus flujos se
cierran, o dos minutos después de la última señal del agente.
La dirección de una instrucción
Cada instrucción pública tiene una dirección web, https://instruction.md/{owner}/{name}, la
misma para personas y agentes. Un navegador recibe su página: la instrucción, su URI instruction:// y
la configuración para seguirla. Un agente que envía Accept: text/markdown, o ninguna cabecera
Accept, como hacen curl y la mayoría de los programas, recibe el propio texto publicado, tal cual,
con su versión en las cabeceras. La dirección es la misma en ambos casos: no existe una forma con
.md. @stable o @v3 después del nombre lee una referencia o una versión
concreta, y https://instruction.md/{owner} muestra las instrucciones públicas de un propietario.
Para seguir una instrucción a medida que cambia, conecta el agente por MCP, como se explica más abajo. El archivo
/llms.txt del sitio enumera la documentación y las plantillas para agentes.
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 Para que una instrucción sea la del proyecto y se mantenga al día durante una sesión, consulta Claude Code (en inglés).
Codex
Codex habla una versión de MCP anterior a la de este servidor, así que se conecta a través del servidor MCP de la línea de comandos. Consulta Codex (en inglés) para eso y para seguir una instrucción durante una sesión.
Cursor y otros clientes MCP
{
"mcpServers": {
"instruction-md": {
"command": "npx",
"args": ["-y", "instruction.md", "mcp", "--follow", "instruction://acme/support-agent@stable", "--url", "https://instruction.md/mcp"]
}
}
}
Toda lectura requiere haber iniciado sesión. Claude y ChatGPT te hacen iniciar sesión ellos mismos. Cursor, VS Code y
otros clientes que hablan una versión de MCP anterior a la de instruction.md pasan por el servidor stdio de la CLI de
arriba (VS Code: la misma entrada en servers de .vscode/mcp.json, con
"type": "stdio"), en el que inicias sesión una vez con instruction login. Los agentes usan
una credencial propia.
Elegir qué puede hacer una aplicación de IA
Cuando conectas una aplicación de IA como Claude, ChatGPT o un editor de código, instruction.md pregunta primero ¿Qué puede hacer?. Eliges una de cuatro opciones, y cada una incluye la anterior:
| Opción | La aplicación puede |
|---|---|
| Solo leer | Leer tus instrucciones y sus versiones. No cambia nada. |
| Leer y escribir borradores | Además, crear instrucciones, cambiar borradores, sugerir cambios y comentar. No se publica nada. |
| Leer, escribir y publicar | Además, publicar nuevas versiones, después de preguntarte. Es la opción que la página ofrece primero. |
| Todo lo que tú puedes hacer | Además, compartir, eliminar, cambiar tu cuenta y administrar una organización que tú administras. |
Un interruptor aparte, Seguir los cambios en directo, indica si la aplicación puede seguir instrucciones y enterarse de cuándo cambian. Para una aplicación que solo deba leer y seguir, elige Solo leer y deja el interruptor activado.
A la aplicación solo se le muestran las herramientas que tu elección permite, y el servidor rechaza cualquier otra cosa que intente, sea cual sea tu propio rol. Para cambiar la elección o desconectar una aplicación, abre Configuración ▸ Aplicaciones conectadas y elige Cambiar lo que pueden hacer. Un cambio surte efecto en pocos minutos. A una aplicación que conectaste antes de que existiera esta elección se le pregunta la próxima vez que inicia sesión; hasta entonces actúa en tu nombre sin restricciones.
Herramientas de organización en un host
Administrar una organización requiere un ámbito de OAuth más, org:admin, y la opción
Todo lo que tú puedes hacer al conectar la aplicación. Sin él, un host muestra las herramientas para
escribir, revisar, publicar, compartir y seguir instrucciones, pero no las 28 que gestionan una organización: sus
miembros e invitaciones, espacios de trabajo, política, claves de firma, agentes, facturación y registro de
auditoría. Un host sin ese ámbito tiene una lista de herramientas más corta.
- El servidor no nombra el ámbito allí donde un host averigua cómo iniciar sesión (los metadatos de recurso protegido y el desafío de su respuesta 401), así que un host inicia sesión para las herramientas de uso diario y muestra esas.
-
Un host obtiene
org:adminsolo cuando lo pide por su nombre mientras inicias sesión, si te deja elegir los ámbitos que solicita. La página de inicio de sesión muestra entonces «Administer your organizations on instruction.md» entre lo que aceptas, y el host muestra las herramientas de organización. -
Un host que nombra sus ámbitos al conectarse por primera vez tiene solo esos: si entonces omitió
org:admin, no puede pedirlo en un inicio de sesión posterior (se rechaza como ámbito no válido). Elimina el conector y añádelo de nuevo, esta vez indicandoorg:admin. -
El estudio y la CLI
instructionsiempre tienen el ámbito. Si tu host no lo tiene, gestiona la organización desde allí: Configuración en el estudio, oinstruction agents,instruction keyseinstruction auditen la CLI. - Los agentes nunca lo obtienen: la credencial de un agente no puede administrar una organización.
El ámbito solo permite a un cliente ver y llamar a estas herramientas. Cada herramienta sigue comprobando tu rol: solo los propietarios y administradores de una organización la modifican, y su facturación, solo sus miembros de facturación.
agentd
agentd 1.18 y posteriores hablan MCP 2026-07-28 y MCP Events. Dale al agente una
credencial propia (Configuración ▸ Agentes en el estudio, o instruction agents create; una organización en
el plan Pro o superior) y luego sigue la instrucción por su identificador en una referencia:
# 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
Publicar mueve la referencia, el servidor envía a la suscripción de agentd el aviso de volver a leer, y el
siguiente turno lee la nueva versión: agentd registra instruction.applied, de la versión anterior a
la nueva, en menos de un segundo. Una dirección del tipo propietario/nombre
(instruction://acme/support-agent@stable) también funciona; en ese caso agentd se entera de que se
ha publicado una versión a través de MCP Events, unos segundos más tarde.
Fijar publisher hace obligatoria la verificación: en cada lectura, agentd comprueba la firma del
autor con el conjunto de claves del editor, rechaza una versión firmada con una clave revocada y conserva su
última instrucción válida en lugar de aplicar algo que no puede verificar. La firma de una versión nombra la
instrucción por su identificador, así que fija la dirección con el identificador. El token del agente procede del
realm de los agentes, que los metadatos del servidor MCP no nombran: token_url indica dónde está.
Tu propio código
El paquete instruction.md de npm incluye un seguidor que implementa la mitad consumidora de la
especificación: conserva la última versión válida, respeta las retenciones de política, verifica firmas
descubriendo las claves e informa de lo que ha aplicado. Su cliente MCP, instruction.md/client, le da
el protocolo sin estado; su suscripción se reabre tras un corte y vuelve a leer la instrucción. Los SDK de Python
y Go tienen el mismo seguidor sobre el mismo protocolo (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(); Seguir con seguridad algo que cambia
| Opción | Qué significa |
|---|---|
@stable | Una referencia que mueves a propósito. Recomendada para todo lo que esté en producción. |
@latest | Se mueve con cada publicación. Buena para desarrollo. |
@ver_… | Fijada a una versión inmutable. Nunca cambia. |
Sigas lo que sigas, un consumidor que no puede leer o no puede verificar conserva la versión que ya tenía. No poder llegar al registro se queda en «sin actualizaciones», nunca en «sin instrucciones».
Decirle al registro qué has aplicado
Un consumidor puede declarar un vínculo e informar de la versión que ha aplicado. Eso es lo que llena la vista Consumers: qué agentes siguen una instrucción, qué versión ejecuta cada uno y cuánto tarda la adopción. Es opcional, y nunca envía tu contenido a ninguna parte.