لم تُترجم هذه الصفحة بعد.

instruction-mcp command reference

instruction-mcp is the MCP server of the @instruction.md/mcp package. It offers the same tools, resources and prompts as https://instruction.md/mcp, and opens and seals the text of sealed instructions on your side, so instruction.md stores only ciphertext. This page lists its two modes, every command and flag, its HTTP endpoints, its environment and its exit codes.

It runs in one of two modes:

  • On stdio, for one person or one agent: an AI app starts it as a command, and it holds that caller's own key.
  • As a company proxy (--http), for an organization: an HTTP MCP endpoint at your own address that people's AI apps sign in to with instruction.md, holding the organization's key-service key.

Install

Shell
npm i -g @instruction.md/mcp
instruction-mcp --version
Output
@instruction.md/mcp 0.1.1

npx -y @instruction.md/mcp … runs it without installing. The package needs Node.js 20.19 or later. It signs in with the instruction command's sign-in (instruction login, from npm i -g instruction.md), or with a token you give it.

Usage

This is instruction-mcp --help, read from the command's source when this site is built:

instruction-mcp --help
instruction-mcp — instruction.md's MCP server for sealed instructions (@instruction.md/mcp 0.1.1)

  instruction-mcp [--key-file F] [--url U] [--token T]
        serve on stdio: the same tools as https://instruction.md/mcp, sealed instructions opened here and sealed
        here before they are written. Signed in as `instruction login` (or --token / INSTRUCTION_MD_TOKEN). The key:
        --key-file (INSTRUCTION_MD_SEAL_KEY_FILE), else your own key unlocked with INSTRUCTION_MD_SEAL_PASSPHRASE or
        INSTRUCTION_MD_SEAL_RECOVERY.
  instruction-mcp key init [--file F]
        make your key: an agent's goes in a key file (default ./instruction-md.key, 0600); a person's is unlocked by
        INSTRUCTION_MD_SEAL_PASSPHRASE (at least 12 characters). Either way a recovery key is shown once: keep it.
        Then someone who holds a sealed workspace's key gives it to you (the editor's Approve, or seal_wraps_add).
  instruction-mcp key status [--key-file F]
        your key's fingerprint, and each sealed workspace: whether you hold its key.
  instruction-mcp --http PORT --public-url https://mcp.acme.com (--key-file ks.key | --key-command CMD) [--allow-domain acme.com …] [--url U] [--issuer I]
        the company proxy: an MCP endpoint at <public-url>/mcp that people's AI apps sign in to as they do to
        instruction.md (its OAuth metadata names instruction.md's sign-in). Each request goes to instruction.md with
        that person's token; this proxy opens what they may read with the organization's key-service key.
        --key-command: the key held in your KMS or secret store, printed by a command at start, e.g.
        "aws kms decrypt --ciphertext-blob fileb://ks.key.enc --query Plaintext --output text | base64 -d" or
        "vault kv get -field=key secret/instruction-mcp" (INSTRUCTION_MD_SEAL_KEY_COMMAND).
  instruction-mcp key init --key-service --org SLUG [--file F] [--label L]
        an organization's key-service key (an admin of the organization): a key file for the proxy, its public key
        registered; then give sealed workspaces' keys to it (the editor, or seal_wraps_add).

In an AI app: { "command": "npx", "args": ["-y", "@instruction.md/mcp"] }
CommandWhat it does
instruction-mcp [--key-file F] [--key-command C] [--url U] [--token T]Serves on stdio, signed in as you or as an agent
instruction-mcp key init [--file F]Makes your key: a person's, unlocked by a passphrase, or an agent's, in a key file
instruction-mcp key status [--key-file F]Says whether you have a key and whether it unlocks here
instruction-mcp --http PORT --public-url U (--key-file F | --key-command C) [--allow-domain D …] [--url U] [--issuer I]Runs the company proxy
instruction-mcp key init --key-service --org SLUG [--file F] [--label L]Makes the organization's key-service key
instruction-mcp --help, -h, helpPrints the usage above, exit 0
instruction-mcp --version, -vPrints the package name and version, exit 0

Serve on stdio

With no command, instruction-mcp is an MCP server on stdin and stdout. Every tool call, resource read and prompt goes to instruction.md as the signed-in caller. Before an answer reaches the app, each sealed text in it that the key can open is replaced by its plain text. Before a write reaches instruction.md, the text is sealed. Validation, diffs and edits by operations on a sealed instruction run here, on the opened text, because the server can't read it.

FlagVariableWhat it does
--key-file FINSTRUCTION_MD_SEAL_KEY_FILEThe key file to open and seal with: an agent's, written by key init
--key-command CINSTRUCTION_MD_SEAL_KEY_COMMANDA command that prints the key file's JSON, run once at start through the shell, with 30 seconds to answer
(none)INSTRUCTION_MD_SEAL_PASSPHRASE, INSTRUCTION_MD_SEAL_RECOVERYUnlock the signed-in person's own key, registered on instruction.md
--url UINSTRUCTION_MD_URLThe instruction.md MCP server. Default: the server of your last instruction login, else https://instruction.md/mcp
--token TINSTRUCTION_MD_TOKENA bearer token used as it is, instead of the stored sign-in (an agent's access token)

The key is taken in this order: the key command, then the key file, then your own registered key, unlocked with INSTRUCTION_MD_SEAL_PASSPHRASE or INSTRUCTION_MD_SEAL_RECOVERY. If a key file or command is given and it can't be read, the server stops with exit code 1. A passphrase or recovery key that doesn't unlock your key counts as no key. With no key at all, it still serves: sealed instructions pass through still sealed, and it says so once on stderr.

Workspace keys it unwraps are kept in memory for five minutes, then fetched again. On SIGINT or SIGTERM it forgets them and exits 0.

The server calls itself instruction.md (sealed, via @instruction.md/mcp), so an app can tell it apart from instruction.md's own server. Tools that only instruction.md's servers can run (the assistant, pages, read links) refuse sealed instructions and say why.

An AI app that runs a command takes it like this:

MCP server
{
  "mcpServers": {
    "instruction-md": {
      "command": "npx",
      "args": ["-y", "@instruction.md/mcp", "--key-file", "/home/you/.config/instruction-md/agent.key"]
    }
  }
}

In Claude Code:

Shell
claude mcp add instruction-md -- npx -y @instruction.md/mcp --key-file ~/.config/instruction-md/agent.key

Make a key

key init makes your key and registers its public half on instruction.md. Who you are signed in as decides what kind of key it makes:

  • A person: a key unlocked by INSTRUCTION_MD_SEAL_PASSPHRASE, at least 12 characters. Nothing is written to disk. You can also set up your key in the editor instead, at Your account ▸ Security ▸ Encryption key.
  • An agent (signed in with an agent credential's token): a key file, mode 0600, at --file (default ./instruction-md.key). It never overwrites a file that exists.

Either way it prints a recovery key once. Keep it somewhere safe.

Shell (a person)
instruction login
export INSTRUCTION_MD_SEAL_PASSPHRASE='<at least 12 characters>'
instruction-mcp key init
Output
your key: <fingerprint>
your recovery key (shown once, keep it somewhere safe):
  <recovery key>
Next: someone who holds a sealed workspace's key approves you (the editor shows you waiting).
Shell (an agent)
export INSTRUCTION_MD_TOKEN="$TOKEN"   # the agent's access token
instruction-mcp key init --file agent.key
Output
your key: <fingerprint>
  in agent.key (keep it secret: it opens what this agent may read)
your recovery key (shown once, keep it somewhere safe):
  <recovery key>
Next: someone who holds a sealed workspace's key approves you (the editor shows you waiting).

Your key opens nothing yet. Someone who holds a sealed workspace's key approves you, after comparing the fingerprint you show them. The editor shows you as waiting.

Check a key

Shell
instruction-mcp key status --key-file agent.key
Output
your key: <fingerprint>
unlocked here

key status prints your key's fingerprint and whether it unlocks here. When it doesn't, it says not unlocked here (--key-file, or INSTRUCTION_MD_SEAL_PASSPHRASE). With no key registered, it prints no key yet: instruction-mcp key init and exits 1.

Run the company proxy

--http PORT serves an MCP endpoint at <public-url>/mcp. People's AI apps add that address as a remote MCP server and sign in with instruction.md, as they do with https://instruction.md/mcp. Each request goes on to instruction.md with that person's token, so instruction.md still decides who may read what. The proxy holds the organization's key-service key and opens what the person may read. People need no key of their own.

FlagVariableWhat it doesDefault
--http PORTThe port to listen on, on every interface (0.0.0.0)None: the stdio mode
--public-url UINSTRUCTION_MD_PUBLIC_URLThe address people reach it at, behind your TLSRequired
--key-file FINSTRUCTION_MD_SEAL_KEY_FILEThe key-service key fileOne of the two is required
--key-command CINSTRUCTION_MD_SEAL_KEY_COMMANDA command that prints the key file's JSON, for a key in your KMS or secret store; it wins over --key-file
--allow-domain D (repeatable)INSTRUCTION_MD_ALLOW_DOMAINS (comma-separated; added to the flags)Serve only people whose verified email is at one of these domainsEveryone instruction.md lets in
--url UINSTRUCTION_MD_URLThe instruction.md MCP server every request goes tohttps://instruction.md/mcp
--issuer IINSTRUCTION_MD_ISSUERThe authorization server its metadata names/auth/realms/instruction-md at the --url origin
Shell
instruction-mcp --http 8780 --public-url https://mcp.acme.com \
  --key-file /keys/ks.key --allow-domain acme.com
Output (stderr)
instruction-mcp: serving https://mcp.acme.com/mcp on :8780 as key service <fingerprint>

With the key in a secret store:

Shell
instruction-mcp --http 8780 --public-url https://mcp.acme.com \
  --key-command "vault kv get -field=key secret/instruction-mcp"

The key must be a key-service key. A person's or an agent's key file is refused at start. In an AI app, people add the proxy's address:

Shell
claude mcp add instruction-md --transport http https://mcp.acme.com/mcp

How it behaves

  • It keeps no MCP session: each POST is answered on its own, as JSON. Any number of replicas can run behind one address.
  • For each token, it keeps a connection to instruction.md and the person's verified email for four minutes, then makes them again. Nothing is shared between two people's tokens.
  • Workspace keys it unwraps stay in memory for five minutes.
  • A request body larger than 4 MiB is refused.
  • It writes nothing to disk, so its root file system can be read-only.

Its HTTP endpoints

RequestAnswer
POST /mcp with Authorization: Bearer …The MCP answer, as JSON
POST /mcp with no bearer token401 {"error":"unauthorized","error_description":"sign in to instruction.md"}, with WWW-Authenticate: Bearer resource_metadata="<public-url>/.well-known/oauth-protected-resource/mcp", which starts the app's sign-in
POST /mcp with a token instruction.md refuses401 {"error":"invalid_token"}, the same header with error="invalid_token"
POST /mcp from a person outside the allowed domains403 {"error":"forbidden","error_description":"this organization's proxy doesn't serve your account"}
Another method on /mcp405 {"error":"method_not_allowed"}, with Allow: POST
GET /.well-known/oauth-protected-resource/mcp (or without /mcp)The protected-resource metadata: the resource, instruction.md's authorization server, bearer in the header
GET /health200 {"ok":true}
Any other path404 {"error":"not_found"}
A body that isn't JSON, or is too large400 {"error":"bad_request", …}

Every answer carries Cache-Control: no-store.

Shell
curl -s https://mcp.acme.com/health
Output
{"ok":true}
Shell
curl -s https://mcp.acme.com/.well-known/oauth-protected-resource/mcp
Output
{"resource":"https://mcp.acme.com/mcp","authorization_servers":["https://instruction.md/auth/realms/instruction-md"],"bearer_methods_supported":["header"],"resource_name":"instruction.md (sealed, via your organization's proxy)"}

Make the organization's key-service key

An owner or admin of the organization makes it once, signed in as themselves with instruction login. An organization keeps at most 20 active key services.

Shell
instruction login
instruction-mcp key init --key-service --org acme --file ks.key --label mcp.acme.com
Output
the key service's key: <fingerprint>
  in ks.key (keep it secret: give it to the proxy as --key-file, e.g. a Kubernetes secret)
Next: give each sealed workspace's key to it (the editor's Encryption settings, or seal_wraps_add).
FlagWhat it doesDefault
--key-serviceMake a key service's key, not your own
--org SLUGThe organization it serves. Required
--file FWhere the key file goes, mode 0600; never overwritten./instruction-md.key
--label LIts name in the organization's encryption settingsinstruction-mcp

Then someone who holds a sealed workspace's key gives it to the key service with the seal_wraps_add tool, the wrap made on their own device (seal_key_services_list names the key service's fingerprint). The editor doesn't list key services among the keys waiting for a workspace, although the command's last line names its encryption settings. A script that does it is on Sealed instructions. Keep the key file in your secret store (a Kubernetes secret, Vault), never in an image.

The container image

The proxy's image installs the npm package of the version you name. The published image, ghcr.io/instruction-md/mcp, isn't public yet, so build your own from this Dockerfile (saved as mcp.Dockerfile):

mcp.Dockerfile
ARG NODE_IMAGE=node:22.21.1-alpine3.22
FROM ${NODE_IMAGE}
ARG VERSION
RUN test -n "$VERSION" && npm install --global --omit=dev "@instruction.md/mcp@${VERSION}" && npm cache clean --force && rm -rf /root/.npm
ENV NODE_ENV=production NODE_OPTIONS=--enable-source-maps
USER node
EXPOSE 8780
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://127.0.0.1:8780/health >/dev/null || exit 1
ENTRYPOINT ["instruction-mcp"]
CMD ["--http", "8780"]
Shell
docker build -f mcp.Dockerfile --build-arg VERSION=0.1.1 -t instruction-mcp:0.1.1 .
  • Node.js 22 on Alpine, running as the user node (uid 1000): the key file you mount must be readable by it.
  • The entry point is instruction-mcp, and the command is --http 8780. Port 8780 is exposed.
  • A health check runs wget against http://127.0.0.1:8780/health every 30 seconds. If you change the port, change the health check too.
  • Configure it with the variables in the Environment table: INSTRUCTION_MD_PUBLIC_URL, INSTRUCTION_MD_SEAL_KEY_FILE or INSTRUCTION_MD_SEAL_KEY_COMMAND, INSTRUCTION_MD_ALLOW_DOMAINS.
  • TLS is yours: put it behind your ingress or load balancer.
Docker
sudo chown 1000:1000 /secure/ks.key   # the container runs as the user node (uid 1000)

docker run -d -p 8780:8780 --read-only \
  -v /secure/ks.key:/keys/ks.key:ro \
  -e INSTRUCTION_MD_PUBLIC_URL=https://mcp.acme.com \
  -e INSTRUCTION_MD_SEAL_KEY_FILE=/keys/ks.key \
  -e INSTRUCTION_MD_ALLOW_DOMAINS=acme.com \
  instruction-mcp:0.1.1

A Kubernetes example and a key held in AWS KMS are on Sealed instructions.

Environment

The variables instruction-mcp reads, generated from its source when this site is built. Every variable of the command-line tools is on Environment variables and files.

VariableWhat it doesDefault
INSTRUCTION_MD_URLThe instruction.md MCP server. Registry commands and instruction login take it after --url. The hooks, turn, acp and the instruction.md/agent helper take it after --url and the follow file's url. instruction-mcp --http sends every request there.Registry commands: the server of your last instruction login, else https://instruction.md/mcp. instruction login, the hooks and instruction-mcp --http: https://instruction.md/mcp
INSTRUCTION_MD_ISSUERinstruction login: the authorization server to sign in at, the same as --issuer. One that isn't the server's own asks first, or needs --trust-issuer. instruction-mcp --http: the issuer its protected-resource metadata names, the same as --issuer.instruction login: the one the server names. instruction-mcp: /auth/realms/instruction-md at the server's origin
INSTRUCTION_MD_CLIENT_NAMEThe client name every request sends in its client information. The server counts reads by app with it. Each command sets its own when it is unset.instruction-md-cli; a hook: instruction-md-cli hook (<app>); instruction agents turn: instruction-md-cli <app>; the runner: instruction-md-cli fleet@<hostname>; instruction-mcp: instruction-mcp, or instruction-mcp (company proxy)
INSTRUCTION_MD_SEAL_KEY_FILEA key file (imd-seal/1, as instruction-mcp key init writes it) that opens sealed instructions. instruction-mcp: the same as --key-file. instruction and instruction agents: what opens a sealed instruction they follow or a sealed conversation.None
INSTRUCTION_MD_SEAL_KEY_COMMANDA command that prints the key file's JSON, for a key kept in a KMS or secret store. It runs once, through the shell, with 30 seconds to answer, and wins over a key file. instruction-mcp --key-command sets it.None
INSTRUCTION_MD_SEAL_PASSPHRASEA person's passphrase: it unlocks their own key, registered on instruction.md, when no key file or command is given. instruction-mcp key init needs it to make a person's key (at least 12 characters).None
INSTRUCTION_MD_SEAL_RECOVERYA person's recovery key, shown once when the key was made: it unlocks their own key when no key file, command or passphrase does.None
INSTRUCTION_MD_PUBLIC_URLinstruction-mcp --http: the address people reach the company proxy at; its MCP endpoint is <public-url>/mcp. The same as --public-url.None: --http needs it
INSTRUCTION_MD_ALLOW_DOMAINSinstruction-mcp --http: email domains, separated by commas, whose people the proxy serves; added to each --allow-domain. A person's verified email must be at one of them.Every person instruction.md lets in

It signs in through the instruction.md package, so it also reads what that reads: the stored sign-in in credentials.json in the config folder (XDG_CONFIG_HOME), INSTRUCTION_MD_TOKEN (the same as --token) and INSTRUCTION_MD_LABEL (the client title, default instruction mcp@<hostname>). Those rows are on Environment variables and files. It sends INSTRUCTION_MD_CLIENT_NAME as its client name when set (else instruction-mcp, or instruction-mcp (company proxy)).

Exit codes

CodeWhen
0Done; --help, --version; the stdio server stopped by a signal
1An error (its message on stderr); key status with no key yet
2A usage error: an unknown key command, --http without --public-url or a key, a key that isn't a key service's, --key-service without --org, a person's key init without a passphrase
3Not signed in

If it doesn't work

What you seeWhyWhat to do
instruction-mcp needs your sign-in: `instruction login` (npm i -g instruction.md), or --tokenNo stored sign-in and no tokenRun instruction login, or set INSTRUCTION_MD_TOKEN for an agent
instruction-mcp: no key — sealed instructions pass through still sealedNo key file, command, passphrase or recovery key unlocked a keyGive --key-file, or set INSTRUCTION_MD_SEAL_PASSPHRASE; check with key status
this key doesn't hold workspace … 's key yet: someone who does gives it (seal_wraps_add)Your key isn't approved for that workspaceAsk someone in the workspace to approve you in the editor
--http PORT needs --public-url and the key service's key: --key-file, or --key-command (your KMS or secret store prints it)A flag is missingGive both, or set their variables
… isn't a key service's key (instruction-mcp key init --key-service)The proxy was given a person's or an agent's keyMake a key-service key with key init --key-service --org SLUG
set INSTRUCTION_MD_SEAL_PASSPHRASE (at least 12 characters) to make your key here, or set it up in the editor: Settings, SecurityA person ran key init without a passphraseSet it, or make the key in the editor
… exists: not overwrittenkey init found a file at --fileChoose another --file; never delete a key file that still opens something
Still stuckAsk us, with the command and its stderr

Last checked against the product:

Was this page helpful? Report a problem