Цю сторінку ще не перекладено.

Servers, skills and accounts

This page is for developers who set up the agents that follow an instruction. You will declare the MCP servers and skills the agent works with, write them into Claude Code's or Codex's own files with one command, and give each machine the credentials those servers need, without putting a key in the instruction.

An account is a name the instruction gives a server's credential, such as work. The instruction says which account to use (account=work); each machine says what that account means there: a variable, a command that prints a key from your secret store, a sign-in to the server, or your identity provider. instruction.md never holds the key, and the instruction never contains it.

The instruction names the account; each machine says what it means.

Before you start

  • @instruction.md/agents on the machine (npm i -g @instruction.md/agents, or instruction agents … from the instruction.md package). See The runner.
  • A sign-in: instruction agents login, the same as instruction login.
  • A project that follows the instruction (.instruction/follow.json, written by instruction agents follow … --write), or the instruction's address on the command line.
  • Claude Code or Codex. apply writes for these two apps. Others take the instruction through their hooks (Other coding agents), and their servers are set up by hand.

Declare servers and skills

The instruction names its servers with :::mcp and its skills with :::skill. The language, every attribute and how the editor completes them are on Tools and integrations. What apply reads of them:

acme/support-agent
:::mcp{id=desk title="Help desk" src="https://desk.example.com/mcp" account=work allow="tickets_list tickets_get" deny="tickets_delete"}
The help desk's tickets: read them, answer them, never delete one.
:::

:::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=frontend-design src="https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md" sha256="sha256:<64 hex digits>"}
:::
:::mcp attribute What apply does with it
id The server's name in the app's files. Required: a server without one is skipped.
src Its address (Streamable HTTP). https://, or http:// on localhost, 127.0.0.1 or [::1]; no user name or password in it.
account The account this machine resolves for its credential (below).
allow Tools the agent may call without asking: Claude Code's permissions.allow, Codex's enabled_tools.
deny Tools the agent must not call: Claude Code's permissions.deny, Codex's disabled_tools. Your organization's blocked tools join it.
title, description, tools, required Carried with the server; not written into the app's files.
:::skill attribute What apply does with it
id The skill's folder: .claude/skills/<id>/ or .agents/skills/<id>/. Required.
description When the model should load it: the description of the written SKILL.md (else trigger, else title, else id; cut at 1,024 characters). A fetched SKILL.md's own description is kept when the instruction gives only a title.
The block's text The skill's text, written as it is.
src Instead of a text: a SKILL.md on GitHub, as a github.com/…/blob/…/SKILL.md page, a github.com/…/tree/… folder (its SKILL.md) or a raw.githubusercontent.com address. Fetched over https, at most 256 KB.
sha256 With src: sha256: and the file's hex digest. A file that doesn't match is not written.

A server or a skill inside a host-run :::agent block is that agent's own, not the root agent's, and apply leaves it out.

A server named only by a registry entry, with no src, is skipped: apply needs an address to connect to. Give it its src.

Write them into the agent's files

In a project that follows the instruction:

Shell
instruction agents follow instruction://acme/support-agent@stable --host claude-code --write

follow --write writes the follow file and the hooks, records the app (claude-code or codex) in the follow file's apply list, and applies at once. After that, apply runs by itself in the background whenever a session starts on a version the servers and skills weren't written for. The app reads them as a session starts, so a change is there from the next session, and the hook says so once. --no-apply on follow leaves this out.

To apply by hand:

Shell
instruction agents apply                          # the hosts follow.json names, else Claude Code
instruction agents apply --host codex
instruction agents apply --host both --approve       # Claude Code uses the servers without asking you
instruction agents apply acme/support-agent --dry-run  # what it would write, written nowhere
instruction agents apply --remove                    # take back everything apply wrote
Output
$ instruction agents apply --host claude-code
acme/support-agent v7 for claude-code: servers desk; skills triage, frontend-design
wrote .mcp.json, .claude/settings.json, .claude/skills/triage/SKILL.md, .claude/skills/frontend-design/SKILL.md
Claude Code asks once before it uses a project's servers (or run `instruction agents apply --approve` to approve them for yourself).
On this machine, say what desk's account "work" means: instruction agents accounts set desk@work --env VAR (or --command, or instruction agents signin desk --account work)

What it writes, for each app:

Claude Code Codex
Servers .mcp.json mcpServers .codex/config.toml [mcp_servers.<id>]
Credentials headersHelper: instruction agents credential …, for a server with an account or an entry on this machine bearer_token_env_var or env_http_headers for a key in a variable, else http_headers_helper, on the same condition
Allowed and denied tools .claude/settings.json permissions (mcp__<server>__<tool>) enabled_tools, disabled_tools
Skills .claude/skills/<id>/SKILL.md .agents/skills/<id>/SKILL.md
Approval --approve: .claude/settings.local.json enabledMcpjsonServers, for you only The folder must be trusted, which Codex asks when you start it there
.mcp.json
{
  "mcpServers": {
    "desk": {
      "type": "http",
      "url": "https://desk.example.com/mcp",
      "headersHelper": "npx -y @instruction.md/agents credential desk --account work --url https://desk.example.com/mcp"
    }
  }
}
.codex/config.toml
# instruction.md apply: desk
[mcp_servers.desk]
url = "https://desk.example.com/mcp"
bearer_token_env_var = "DESK_API_KEY"
enabled_tools = ["tickets_list", "tickets_get"]
disabled_tools = ["tickets_delete"]

apply changes only what it wrote itself. It keeps the list in .instruction/applied.json, which you commit, so a teammate's apply knows which entries are its own. A server, a permission rule or a skill of the same name that someone else wrote is left alone, and the output says so: (left alone, not ours: .mcp.json: desk). A version that drops a server or a skill removes what apply wrote for it. A JSON file left empty is removed.

.instruction/applied.json
{
  "format": "instruction-applied/1",
  "follow": "instruction://acme/support-agent@stable",
  "label": "acme/support-agent",
  "versionId": "ver_01JX5S8T0V2W4Y6Z8A1C3E5G7J",
  "version": 7,
  "digest": "sha256:…",
  "hosts": ["claude-code"],
  "servers": [{ "id": "desk", "url": "https://desk.example.com/mcp", "account": "work" }],
  "skills": [
    { "id": "triage", "source": "inline" },
    { "id": "frontend-design", "source": "https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md" }
  ],
  "owned": {
    ".mcp.json": ["desk"],
    ".claude/settings.json": ["mcp__desk__tickets_delete", "mcp__desk__tickets_list", "mcp__desk__tickets_get"],
    ".claude/skills": ["triage", "frontend-design"]
  },
  "at": "2026-11-22T09:14:03.120Z"
}
Option What it does
[<uri>] The instruction, when the project's follow file doesn't name it.
--host claude-code, codex or both The apps to write for. Default: the follow file's apply list, else the hosts of the last apply, else claude-code. An app left out has what was written for it removed.
--approve Claude Code uses the servers without asking you once.
--dry-run Say what it would write and remove; write nothing.
--remove Take back everything apply wrote, and remove applied.json.
--dir D The project, when it isn't the one found from here.
--cli CMD How the app runs this CLI for a credential. Default: npx -y @instruction.md/agents.
--json The result as JSON: changed, wrote, removed, conflicts, skipped, notes, applied.
--url U, --token T Another server, or a token instead of the stored sign-in.

The hook's background run also passes --if-changed, --quiet and --note. apply exits 0, 1 on an error, 2 on a usage error, and 3 when not signed in.

Say what each account means on this machine

An instruction's server is looked up on this machine as id@account first (desk@work), then as id alone. A server with no account and no entry signs in the app's own way, as before.

The entries live in ~/.config/instruction-md/accounts.json (or $XDG_CONFIG_HOME/instruction-md/), written readable by you only (0600). INSTRUCTION_MD_ACCOUNTS or --file names another file. Commands list what each entry is, never a value.

A key from a variable

Shell
# a key from a variable
instruction agents accounts set desk@work --env DESK_API_KEY

# a key in another header, with no "Bearer " in front
instruction agents accounts set desk@work --env DESK_API_KEY --header X-Api-Key --scheme ""

The credential goes in Authorization: Bearer <value> unless the entry says otherwise. --header names another header, and --scheme another word before the value ("" for the value alone).

A key from your secret store

--command runs any command that prints the key, with your own rights, for at most 20 seconds. Vault, 1Password and a cloud secret manager all work this way.

Shell
# a key from your organization's secret store: any command that prints it
instruction agents accounts set crm@work --command 'vault kv get -field=token secret/crm'
instruction agents accounts set desk@work --command 'op read op://Work/Desk/token'

Codex runs header commands 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 sets them itself, for example VAULT_ADDR=https://vault.example.com vault kv get ….

A sign-in to the server

Shell
# a sign-in to the server itself (OAuth): the entry, then the sign-in
instruction agents accounts set desk@work --oauth
instruction agents signin desk --account work --url https://desk.example.com/mcp

signin signs this machine in to an MCP server with OAuth. It finds the server's sign-in service from the server, registers as instruction.md CLI (by its client metadata document where the server takes one, else by dynamic registration), and keeps the tokens in ~/.config/instruction-md/mcp-tokens.json (0600; INSTRUCTION_MD_MCP_TOKENS names another file). A token is renewed when it is within 60 seconds of its end. The sign-in also makes the account's entry a sign-in.

Shell
instruction agents signin desk --account work --url https://desk.example.com/mcp
#   a browser on this computer opens; you sign in; done
instruction agents signin desk --account work --url https://desk.example.com/mcp --no-browser
#   open the link on any device, then paste back the address you end on (it starts with http://127.0.0.1)
instruction agents signin desk --account work --url https://desk.example.com/mcp --device
#   where the server offers it: a code to enter on any device
Option What it does
--url U The server's address. Default: the address of this account's earlier sign-in, else the server's address in the project's last apply.
--account A The account it is for (desk@work).
--no-browser Print the link instead of opening it. Over SSH, open it on any device and paste back the address you end on.
--device A code to enter on any device, where the server offers it.
--scope S The scopes to ask for. Default: what the server lists.
--client-id ID, --client-secret-env V A client the server's administrator gave you, when it registers none.

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. If nothing comes back within 10 minutes, signin stops with exit 3.

Your identity provider (XAA)

Where a server trusts your company's identity provider, the agent gets its token with no browser: the machine exchanges a person's identity token at the provider for an assertion, then the assertion at the server's own sign-in service for a token. You revoke it at the provider.

Shell
instruction agents 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 \
  --xaa-scope 'crm.read crm.write' --xaa-audience https://auth.crm.example
Option What it is
--xaa-idp URL The identity provider's token address.
--xaa-client-id ID, --xaa-client-secret-env V or --xaa-client-secret-command C This machine's client at the provider.
--xaa-subject-env V or --xaa-subject-command C The identity token of whoever the agent acts for.
--xaa-server-client-id ID, --xaa-server-client-secret-env V or …-command C The client at the server's sign-in service.
--xaa-scope S The scopes to ask the server for.
--xaa-audience ISS The server's sign-in service, when it isn't found from the server.

A lapsed token is minted again from the provider. This is your provider and the server agreeing; instruction.md takes no part in it.

List and remove

Output
$ instruction agents accounts
crm@work                     the command vault…
desk@work                    the variable DESK_API_KEY
wiki                         a sign-in (instruction agents signin)
crm@corp                     the identity provider login.corp.example
host claude-code             CLAUDE_CODE_OAUTH_TOKEN from the command vault…
Shell
instruction agents accounts remove desk@work      # its entry, and its sign-in's tokens
instruction agents accounts remove-host claude-code

accounts --json lists them as JSON. remove of an entry that isn't there exits 4. The whole file, with host entries (below):

~/.config/instruction-md/accounts.json
{
  "servers": {
    "desk@work": { "env": "DESK_API_KEY" },
    "crm@work": { "command": "vault kv get -field=token secret/crm" },
    "wiki": { "oauth": true },
    "legacy": { "env": "LEGACY_KEY", "header": "X-Api-Key", "scheme": "" }
  },
  "hosts": {
    "claude-code": { "env": "CLAUDE_CODE_OAUTH_TOKEN", "from": { "command": "vault kv get -field=token secret/agents/claude" } },
    "codex": { "env": "CODEX_API_KEY", "from": { "env": "OPENAI_API_KEY" } }
  }
}

The header command

When the agent connects to a server, its app runs the command apply wrote, instruction agents credential <server> --account <account> --url <address>. The command prints the headers as JSON to the app, and nothing to a terminal: on a terminal it refuses unless you add --show. Piped, it prints what the app reads:

Shell
$ instruction agents credential desk --account work --url https://desk.example.com/mcp | cat
{"Authorization":"Bearer <the key>"}

It exits 4 when this machine has no entry for the server, and 3 when the entry can't give a credential (the variable isn't set, the command failed, the sign-in lapsed), with the fix on stderr. Its name and address also come from Claude Code's CLAUDE_CODE_MCP_SERVER_NAME and CLAUDE_CODE_MCP_SERVER_URL. An accounts file elsewhere than the usual place is named in the command with --accounts.

The agent's app's own sign-in

An agent nobody watches still needs its app signed in. accounts host gives the app its sign-in from a variable or your secret store. The runner sets it for each agent it starts, and nowhere else:

Shell
# Claude Code on a machine with no browser: a long-lived token, kept in your secret store
claude setup-token
instruction agents accounts host claude-code --env CLAUDE_CODE_OAUTH_TOKEN --from-command 'vault kv get -field=token secret/agents/claude'

# Codex: an API key from your secret store
instruction agents accounts host codex --env CODEX_API_KEY --from-command 'vault kv get -field=key secret/agents/openai'

Renewing the key in your secret store is all a new sign-in takes.

Check before the agent starts

instruction agents check checks your instruction.md sign-in, the agent's app (installed, signed in, and for Claude Code whether its sign-in runs out within 3 days), and each server's account. It probes each server and gives the one command that fixes anything missing. Here the account work means nothing on this machine yet:

Output
$ instruction agents check --host claude-code
✓ signed in; this project follows acme/support-agent (v7)
✓ Claude Code 2.1.330, signed in
! desk@work: desk.example.com needs a sign-in — the agent's app will ask you (the instruction asks for the account "work")
    fix: instruction agents signin desk --account work --url https://desk.example.com/mcp   (or: instruction agents accounts set desk@work --env VAR | --command CMD)

Nothing stops the agent.

With --fleet it checks as the runner does, for a machine with nobody at it: a server that would ask for a sign-in blocks.

Output
$ instruction agents check --host claude-code --fleet
✓ signed in; this project follows acme/support-agent (v7)
✓ Claude Code 2.1.330, signed in
✗ desk@work: desk.example.com needs a sign-in, and nobody is here to give it
    fix: instruction agents signin desk --account work --url https://desk.example.com/mcp   (or: instruction agents accounts set desk@work --env VAR | --command CMD)

Something above stops the agent: fix it, then run `instruction agents check` again.
Option What it does
--host claude-code, codex or both The apps to check. Default: those of the last apply, else the follow file's, else claude-code.
--fleet Check as for an unattended agent: what would wait for a person blocks.
--no-probe Don't call the servers: only say whether a credential is ready.
--json { ok, findings }, each finding with its kind, level (ok, warn, block), what and fix.
--dir D, --url U, --token T Another project, server or token.
Shell
instruction agents check --fleet --no-probe --json

It exits 0 when nothing blocks, 1 when something does, and 2 on a usage error.

Your organization's policy

When the instruction belongs to an organization the signed-in person is a member of, apply and the runner ask that organization which of the servers and skills it approves:

  • Tools an admin blocked on an integrated server join that server's deny.
  • With Only approved integrations on, a server or a skill whose source isn't approved is skipped: the organization hasn't approved this server, or the organization hasn't approved this skill's source.

Plans On Pro, Team, and Enterprise

Plans On Team and Enterprise

The first badge is for blocking tools, the second for Only approved integrations. A plan without integrations restricts nothing. Blocking tools, approving sources and the switch are on Integrations and Policy and roles.

On a machine that runs agents

The runner does all of this for each agent before it starts it, in the agent's own folder:

  • Claude Code's servers and permissions go into .instruction/mcp.json and .instruction/claude-settings.json, which the runner hands it with --strict-mcp-config --mcp-config … --settings …. Nothing waits for an approval, and the machine's own servers stay out.
  • Codex's go into the folder's .codex/config.toml, and the runner marks the folder trusted.
  • The runner runs the same checks as check --fleet. An agent that would wait for a sign-in is not started. Settings ▸ Deployments shows Needs sign-in, with what is missing and the command to run on that machine, and whoever made the rule or the deployment is notified once. The agent starts by itself on a later pass once it's fixed.
  • An agent whose app exits because its own sign-in ran out is reported the same way, not as a failure.
  • A release that changes an agent's servers or skills restarts it, even when it takes new versions live.

--no-apply on the runner leaves the servers and skills out, and --accounts FILE names another accounts file.

An agent held back until its machine has a sign-in.

A worked example

From the instruction above to a running Claude Code session, on a developer's machine:

Shell
# 1. in the project: follow the instruction (writes .instruction/follow.json and the hooks, then applies)
instruction agents follow instruction://acme/support-agent@stable --host claude-code --write

# 2. say what the account "work" means on this machine
instruction agents accounts set desk@work --command 'vault kv get -field=token secret/desk'

# 3. check nothing stops the agent
instruction agents check

# 4. start Claude Code: its servers, skills and the instruction are there
claude

follow --write applied the servers and skills. The account entry made desk@work a key from Vault, so Claude Code's headersHelper gets it from instruction agents credential as it connects. check confirmed each piece. When a new version adds a server, the next session starts with it.

If it doesn't work

What you see Why What to do
(not set up: frontend-design — frontend-design: https://raw.githubusercontent.com/… is larger than 256 KB) The skill's file is over the limit. Shorten it, or split it into two skills.
… doesn't match the sha256 the instruction gives (it changed since it was named): not written The file on GitHub changed. Check the change, then update sha256 in the instruction and release.
(left alone, not ours: .mcp.json: desk) Someone else wrote a server of the same name. Rename one of them, or remove the other entry and apply again.
(not set up: desk — it is named by a registry, with no address to connect to) The server has no src. Give it its src.
the sign-in to desk@work lapsed and couldn't be renewed (…) Its refresh token was refused. Run the fix it prints: instruction agents signin desk --account work --url ….
the variable DESK_API_KEY isn't set The entry reads a variable the app's environment lacks. Set it where the app runs, or use --command.
Needs sign-in on Settings ▸ Deployments An unattended agent lacks a sign-in. Run the command shown, on that machine, as the runner's user.

Still stuck: ask us.

Last checked against the product:

Was this page helpful? Report a problem