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.

Shell
curl -H 'Accept: text/markdown' https://instruction.md/instruction-md/code-review

Claude Code

Shell
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

JSON
{
  "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ónLa aplicación puede
Solo leerLeer tus instrucciones y sus versiones. No cambia nada.
Leer y escribir borradoresAdemás, crear instrucciones, cambiar borradores, sugerir cambios y comentar. No se publica nada.
Leer, escribir y publicarAdemás, publicar nuevas versiones, después de preguntarte. Es la opción que la página ofrece primero.
Todo lo que tú puedes hacerAdemá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:admin solo 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 indicando org:admin.
  • El estudio y la CLI instruction siempre tienen el ámbito. Si tu host no lo tiene, gestiona la organización desde allí: Configuración en el estudio, o instruction agents, instruction keys e instruction audit en 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:

YAML
# 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).

Shell
npm install instruction.md
pip install instruction-md   # the Python SDK
TypeScript
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ónQué significa
@stableUna referencia que mueves a propósito. Recomendada para todo lo que esté en producción.
@latestSe 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.