Servers, skills and sign-ins
An instruction can say what its agent works with: the MCP servers it uses (and which of their tools it
may or may not call) and the skills it can load. The instruction command writes them
into Claude Code's or Codex's own settings, and keeps them in step as new versions come out.
Sign-ins stay on your machine. An instruction names an account, such as work; the machine says
what that account means: a key from a variable, a key from your organization's secret store, or a sign-in to the
server. instruction.md never holds your keys or tokens.
1. In the instruction
:::mcp{id=desk title="Help desk" src="https://desk.example.com/mcp" account=work allow="tickets.list" deny="tickets.delete"}
The help desk's tickets.
:::
:::skill{id=triage title="Triage" description="Sort new tickets by how urgent they are."}
1. Read the ticket.
2. Say how urgent it is, and why.
:::
:::skill{id=design src="https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md"}
::: accountnames which account the agent uses there; this machine says what it means (step 3).allowlists tools the agent may call without asking;denytools it must never call. Tools your organization blocked are denied too.- A skill is written in the instruction, or fetched from GitHub by its
src(at most 256 KB; withsha256, only that exact file). - If your organization limits instructions to its approved integrations, a server or skill it hasn't approved is not written.
2. Write them into the agent's settings
# in a project that follows an instruction (instruction connect --host claude-code … --with-hooks --write)
instruction apply # Claude Code: .mcp.json, .claude/settings.json, .claude/skills/
instruction apply --host codex # Codex: .codex/config.toml, .agents/skills/
instruction apply --host both --approve
instruction apply --remove # take back everything apply wrote
It changes only what it wrote itself (it keeps a list in .instruction/applied.json, which you commit),
and leaves a server or skill of the same name that someone else added alone. A project set up with
instruction connect … --with-hooks --write applies at once, and again in the background whenever a session
starts on a version that changes them. Claude Code and Codex read servers when a session starts, so new ones are there
from the next session.
Claude Code asks once before it uses a project's servers; --approve approves them for you. Codex reads a
project's settings once you trust its folder.
3. Say what each account means on this machine
# a key from a variable
instruction accounts set desk@work --env DESK_API_KEY
# a key from your organization's secret store (any command that prints it)
instruction accounts set desk@work --command "op read op://Work/Desk/token"
instruction accounts set desk@work --command "vault kv get -field=token secret/agents/desk"
# a sign-in to the server itself
instruction signin desk --account work --url https://desk.example.com/mcp
instruction accounts # what each one uses (never a value)
These live in ~/.config/instruction-md/accounts.json, readable only by you. When the agent connects to
a server, its app asks instruction credential for the header; the command prints it only to the app, never
to your terminal. A server with no account and nothing set here signs in the app's own way, as before.
Codex runs that command with only HOME and PATH. A key from a variable is handed to Codex in
its own setting instead, so it still works; a command that needs other variables (such as VAULT_ADDR)
should set them itself, for example VAULT_ADDR=https://vault.example.com vault kv get ….
Signing in to a server
instruction signin desk --account work --url https://desk.example.com/mcp
# a browser on this computer: it opens, you sign in, done
# no browser here (--no-browser, or over SSH): open the link on any device,
# then paste the address of the page you end on (it starts with http://127.0.0.1)
instruction signin desk --account work --url https://desk.example.com/mcp --device
# where the server offers it: a code to enter on any device
The sign-in finishes on your machine: nothing passes through instruction.md, so a link someone sends you can't sign
their machine in as you. Tokens are kept in ~/.config/instruction-md/mcp-tokens.json and renewed
before they run out.
Your company's sign-in (Enterprise)
Where a server trusts your company's identity provider, the agent gets its access with no browser at all: the provider vouches for it, and you revoke it there.
instruction accounts set crm@corp \
--xaa-idp https://login.corp.example/oauth2/v1/token \
--xaa-client-id agents-runner --xaa-client-secret-env CORP_IDP_SECRET \
--xaa-subject-command "corp-sso print-id-token" \
--xaa-server-client-id instruction-md-agents 4. Check before the agent starts
$ instruction doctor --host claude-code
✓ signed in; this project follows acme/desk (v7)
✓ Claude Code 2.1.329, signed in
✓ desk@work: desk.example.com takes this machine's credential
! wiki: wiki.example.com needs a sign-in — the agent's app will ask you
fix: instruction signin wiki --url https://wiki.example.com/mcp
Nothing stops the agent. instruction doctor checks your instruction.md sign-in, the agent's own (Claude Code's or Codex's, and
when it runs out), and each server's account, and gives the one command that fixes anything missing. It exits with 1
when something would stop the agent.
On a machine that runs agents for you
instruction fleet does all of this for each agent before it starts it:
it writes the agent's servers and skills into its folder, hands them to Claude Code directly (nothing waits for an
approval), and runs the same checks. An agent that would wait for a sign-in nobody is there to give is not started:
the Deployments page shows Needs sign-in with the command to run on that machine, and you get a
notification. Once it's fixed, the agent starts by itself. An agent whose app stops because its own sign-in ran out
is reported the same way, not as a failure.
The agent's app signs in with its own long-lived sign-in, kept in your secret store; renewing it there is all a re-sign-in takes:
# on a machine with no browser: a long-lived sign-in, kept in your secret store
claude setup-token
instruction accounts host claude-code --env CLAUDE_CODE_OAUTH_TOKEN --from-command "vault kv get -field=token secret/agents/claude"
instruction accounts host codex --env CODEX_API_KEY --from-command "vault kv get -field=key secret/agents/openai" A release that changes an agent's servers or skills restarts it, even when it takes new versions live.