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
npm i -g @instruction.md/mcp
instruction-mcp --version @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 — 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"] } | Command | What 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, help | Prints the usage above, exit 0 |
instruction-mcp --version, -v | Prints 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.
| Flag | Variable | What it does |
|---|---|---|
--key-file F | INSTRUCTION_MD_SEAL_KEY_FILE | The key file to open and seal with: an agent's, written by key init |
--key-command C | INSTRUCTION_MD_SEAL_KEY_COMMAND | A 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_RECOVERY | Unlock the signed-in person's own key, registered on instruction.md |
--url U | INSTRUCTION_MD_URL | The instruction.md MCP server. Default: the server of your last instruction login, else https://instruction.md/mcp |
--token T | INSTRUCTION_MD_TOKEN | A 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:
{
"mcpServers": {
"instruction-md": {
"command": "npx",
"args": ["-y", "@instruction.md/mcp", "--key-file", "/home/you/.config/instruction-md/agent.key"]
}
}
} In Claude Code:
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.
instruction login
export INSTRUCTION_MD_SEAL_PASSPHRASE='<at least 12 characters>'
instruction-mcp key init 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). export INSTRUCTION_MD_TOKEN="$TOKEN" # the agent's access token
instruction-mcp key init --file agent.key 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
instruction-mcp key status --key-file agent.key 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.
| Flag | Variable | What it does | Default |
|---|---|---|---|
--http PORT | The port to listen on, on every interface (0.0.0.0) | None: the stdio mode | |
--public-url U | INSTRUCTION_MD_PUBLIC_URL | The address people reach it at, behind your TLS | Required |
--key-file F | INSTRUCTION_MD_SEAL_KEY_FILE | The key-service key file | One of the two is required |
--key-command C | INSTRUCTION_MD_SEAL_KEY_COMMAND | A 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 domains | Everyone instruction.md lets in |
--url U | INSTRUCTION_MD_URL | The instruction.md MCP server every request goes to | https://instruction.md/mcp |
--issuer I | INSTRUCTION_MD_ISSUER | The authorization server its metadata names | /auth/realms/instruction-md at the --url origin |
instruction-mcp --http 8780 --public-url https://mcp.acme.com \
--key-file /keys/ks.key --allow-domain acme.com instruction-mcp: serving https://mcp.acme.com/mcp on :8780 as key service <fingerprint> With the key in a secret store:
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:
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
| Request | Answer |
|---|---|
POST /mcp with Authorization: Bearer … | The MCP answer, as JSON |
POST /mcp with no bearer token | 401 {"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 refuses | 401 {"error":"invalid_token"}, the same header with error="invalid_token" |
POST /mcp from a person outside the allowed domains | 403 {"error":"forbidden","error_description":"this organization's proxy doesn't serve your account"} |
Another method on /mcp | 405 {"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 /health | 200 {"ok":true} |
| Any other path | 404 {"error":"not_found"} |
| A body that isn't JSON, or is too large | 400 {"error":"bad_request", …} |
Every answer carries Cache-Control: no-store.
curl -s https://mcp.acme.com/health {"ok":true} curl -s https://mcp.acme.com/.well-known/oauth-protected-resource/mcp {"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.
instruction login
instruction-mcp key init --key-service --org acme --file ks.key --label mcp.acme.com 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). | Flag | What it does | Default |
|---|---|---|
--key-service | Make a key service's key, not your own | |
--org SLUG | The organization it serves. Required | |
--file F | Where the key file goes, mode 0600; never overwritten | ./instruction-md.key |
--label L | Its name in the organization's encryption settings | instruction-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):
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"] 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
wgetagainsthttp://127.0.0.1:8780/healthevery 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_FILEorINSTRUCTION_MD_SEAL_KEY_COMMAND,INSTRUCTION_MD_ALLOW_DOMAINS. - TLS is yours: put it behind your ingress or load balancer.
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.
| Variable | What it does | Default |
|---|---|---|
INSTRUCTION_MD_URL | The 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_ISSUER | instruction 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_NAME | The 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_FILE | A 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_COMMAND | A 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_PASSPHRASE | A 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_RECOVERY | A 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_URL | instruction-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_DOMAINS | instruction-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
| Code | When |
|---|---|
| 0 | Done; --help, --version; the stdio server stopped by a signal |
| 1 | An error (its message on stderr); key status with no key yet |
| 2 | A 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 |
| 3 | Not signed in |
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
instruction-mcp needs your sign-in: `instruction login` (npm i -g instruction.md), or --token | No stored sign-in and no token | Run instruction login, or set INSTRUCTION_MD_TOKEN for an agent |
instruction-mcp: no key — sealed instructions pass through still sealed | No key file, command, passphrase or recovery key unlocked a key | Give --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 workspace | Ask 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 missing | Give 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 key | Make 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, Security | A person ran key init without a passphrase | Set it, or make the key in the editor |
… exists: not overwritten | key init found a file at --file | Choose another --file; never delete a key file that still opens something |
| Still stuck | Ask us, with the command and its stderr | |