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

instruction.md
:::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"}
:::
  • account names which account the agent uses there; this machine says what it means (step 3).
  • allow lists tools the agent may call without asking; deny tools 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; with sha256, 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

Shell
# 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

Shell
# 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

Shell
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.

Shell
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

Shell
$ 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:

Shell
# 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.