@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/guides/give-a-caller-a-scope.md

@@ -0,0 +1,203 @@
+---
+title: Give a Caller a scope
+description: Make a named token for a CI job or a bridge, give it only the scopes that it needs, and rotate it.
+---
+
+# Give a Caller a scope
+
+Give a CI job, a bridge or a script a token of its own, with only the scopes that it needs.
+
+A [Caller](../reference/glossary.md#caller) is a client that acts on the Instance from outside its
+[Machines](../reference/glossary.md#machine). The CLI on your kubectl context is the Caller `token/instance`, and it can
+do everything. A named Caller token can do less. Declare each one in
+[`callers.tokens`](../reference/config.md#callers-tokens) of `jr2.config.ts`, with its scopes. This example declares
+three. It needs the [Workflow](../reference/glossary.md#workflow) `release` with its
+[Gate](../reference/glossary.md#gate) `review`: save `workflows/release.ts` from [Answer a Gate](answer-a-gate.md) in
+your Instance first. `jr2 up` refuses a `{ workflow, gates }` item for a Workflow that the Instance does not have (see
+[Rules](#rules)).
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  callers: {
+    tokens: {
+      // A CI job: it starts runs of release and follows them, and does nothing else.
+      ci: { may: { start: ["release"], read: ["release"] } },
+      // A bridge to a chat service: it reads each run and answers the Gates of any Workflow.
+      "chat-bridge": { may: { read: "all", answer: "all" } },
+      // A release manager: it answers only the Gate "review" of release, and reads the runs of release.
+      "release-manager": { may: { read: ["release"], answer: [{ workflow: "release", gates: ["review"] }] } },
+    },
+  },
+});
+```
+
+Each scope is `"all"`, or a list of the names of the Workflows that it opens:
+
+| Scope    | What the Caller can do                                                              |
+| -------- | ----------------------------------------------------------------------------------- |
+| `start`  | Start a run.                                                                        |
+| `read`   | Read the full state of a run, follow it, list the runs, and read its conversations. |
+| `answer` | Answer a Gate, and read the open Gates.                                             |
+| `cancel` | Cancel a run.                                                                       |
+| `steer`  | Send a [Steering message](../reference/glossary.md#steering-message) to an Agent.   |
+
+The list of `answer` can also hold an item that names single Gates of a Workflow: `{ workflow, gates }`. A Caller with
+`answer: ["triage", { workflow: "release", gates: ["review"] }]` answers each Gate of `triage`, and only the Gate
+`review` of `release`. The name of a Gate is its invoke id: the `id` of its `invoke`, or else the path of its state,
+such as `review` or `review.open`. `jr2 up` refuses a name that the Machines of the Workflow do not have, and a name
+that two Machines of the Workflow have. It cannot check the Gates of a runtime [Chart](../reference/glossary.md#chart),
+so for a [Chart wrapper](../reference/glossary.md#chart-wrapper) it warns and does not refuse.
+[`jr2 gates`](../reference/cli.md#gates) and `GET /runs/:runId` show only the Gates that the Caller can answer. A value
+of the `groups` map of an issuer takes the same item. Only `answer` takes it.
+
+In the example, `release-manager` answers the Gate `review` of `release`, and no other Gate. When `release` has a second
+Gate, such as a Gate for a security check, a different Caller answers it. `jr2 gates` with the token of
+`release-manager` lists only the `review` Gates.
+
+A scope that the entry does not give opens nothing. A scope does not limit what the run does: a run that a Caller starts
+can start a run of a different Workflow with a [`dispatch`](../reference/authoring-surface/dispatch.md) Effect.
+
+## Make the tokens
+
+Run `jr2 up`. It makes the value of each new name one time, and keeps it in a Secret of its own:
+
+```sh
+jr2 up
+```
+
+```text
+…
+caller token "chat-bridge": made — `jr2 caller token chat-bridge` prints it, and it works when `jr2 up` says converged
+caller token "ci": made — `jr2 caller token ci` prints it, and it works when `jr2 up` says converged
+caller token "release-manager": made — `jr2 caller token release-manager` prints it, and it works when `jr2 up` says converged
+…
+```
+
+The [Orchestrator](../reference/glossary.md#orchestrator) gets only the SHA-256 digest of each value. A value is `jr2c_`
+and 43 more characters.
+
+## Give the token to the Caller
+
+Print the value with [`jr2 caller token`](../reference/cli.md#caller-token). It reads the Secret over the Kubernetes
+API, so your Kubernetes RBAC decides who can read it:
+
+```sh
+jr2 caller token ci
+```
+
+```text
+→ context <context> / namespace <namespace>
+jr2c_<value>
+```
+
+Only the value goes to stdout. Put it in the secret store of the CI job, as `JR2_TOKEN`. Keep it as you keep a password.
+
+## Check what the token can do
+
+The Caller reaches the Orchestrator at a URL. In a new terminal, forward a port to the Orchestrator. Keep this command
+open:
+
+```sh
+kubectl -n <namespace> port-forward svc/jr2-orchestrator 4000:4000
+```
+
+Run [`jr2 whoami`](../reference/cli.md#whoami) with the token:
+
+```sh
+JR2_URL=http://localhost:4000 JR2_TOKEN=$(jr2 caller token ci) jr2 whoami
+```
+
+```text
+→ http://localhost:4000
+{"via":"token","name":"ci","may":{"start":["release"],"read":["release"]}}
+```
+
+The CI job runs `jr2 run`, `jr2 status` and `jr2 watch` with the same two variables, as
+[Start a run](start-a-run.md#use-the-cli-without-the-instance-folder) shows. The run records its Caller in `startedBy`,
+and `jr2 status` prints it on stderr as `started by: token/ci`.
+
+## Rotate a token
+
+Run [`jr2 caller rotate`](../reference/cli.md#caller-rotate). It makes a new value, and prints no value:
+
+```sh
+jr2 caller rotate ci
+```
+
+```text
+→ context <context> / namespace <namespace>
+caller token "ci": waiting for the kubelet to deliver jr2-caller-digests to the Orchestrator
+caller token "ci": rotated — the old value no longer works; `jr2 caller token ci` prints the new one
+```
+
+Give the new value to the Caller. No pod restarts.
+
+## Remove a token
+
+Remove its entry from `callers.tokens`, and run `jr2 up`. It deletes the Secret of the name, and the value stops
+working:
+
+```text
+…
+caller token "chat-bridge": deleted — callers.tokens no longer declares it
+…
+```
+
+## Rules
+
+- The config load refuses a name that is not a DNS label of 40 characters or fewer:
+  `<file> at callers.tokens.<name>: a token name is lowercase letters, digits and -, at most 40, starts with a letter and ends with a letter or digit — <shape>`.
+  `<shape>` is the shape of the `callers` block.
+- The config load refuses the name `instance`, which is the name of the Instance token:
+  `<file> at callers.tokens.instance: the name instance is the Instance token's — <shape>`
+- The config load refuses a scope that is not one of the five, and a list with no Workflow:
+  `<file> at callers.tokens.<name>.may<path>: <problem> — <shape>`
+- The config load refuses an item `{ workflow, gates }` in a scope other than `answer`. `<problem>` is then:
+  `only "answer" can name single Gates; "<scope>" names whole Workflows, because it acts on a whole run`
+- `jr2 up` and `jr2 check` check each `{ workflow, gates }` item of `callers.tokens` and of the `groups` map of each
+  issuer. Each line starts with the place of the item: `callers.tokens.<name>.may.answer` for a token, or
+  `callers.issuers.<index>.groups.<group>.answer` for an issuer. The lines below show the token form.
+- They refuse a Gate name that the Machines of the Workflow do not have. The line lists the Gates that the Workflow has,
+  as `its Gates are "<gate>", "<gate>"`, or `it has no Gate` when it has none:
+  `callers.tokens.<name>.may.answer: Workflow "<workflow>" has no Gate "<gate>" — a Gate's name is its invoke id: the invoke id that the author wrote, or else the key path of its gated state; its Gates are "<gate>", "<gate>" (ADR-0011, ADR-0078)`
+- They refuse a Gate name that two Machines of the Workflow have:
+  `callers.tokens.<name>.may.answer: Gate "<gate>" of Workflow "<workflow>" is in more than one Machine (<machines>), so the one name would open each of those Gates: give one of them an invoke id of its own (ADR-0078)`
+- They refuse an item for a Workflow that the [Assembly](../reference/glossary.md#assembly) does not register:
+  `callers.tokens.<name>.may.answer: { workflow: "<workflow>", gates } names the Gates of a Workflow that this Assembly does not register, so jr2 cannot check them: name a registered Workflow or a Chart file (ADR-0078)`
+- For a Chart wrapper that takes runtime Charts, a Gate name that jr2 cannot find is a warning, not a refusal. The line
+  ends with `; a runtime Chart of it may have one, which jr2 up cannot check`.
+- An item for `<wrapper>/<name>` that is no Chart file of the Assembly is a warning when the wrapper takes runtime
+  Charts:
+  `callers.tokens.<name>.may.answer: { workflow: "<wrapper>/<name>", gates } names a Chart that is no Chart file of this Assembly; a runtime Chart's Gates cannot be checked at jr2 up (ADR-0070, ADR-0078)`
+- When the wrapper takes no runtime Chart, the same item is a refusal, and the line ends with
+  `, and "<wrapper>" takes no runtime Chart`.
+- The Orchestrator refuses a value that it does not know, such as a value from before a rotation, with the status code
+  `401`: `unauthorized`. `jr2 caller rotate` returns when the Orchestrator has read the new digest, so the old value no
+  longer works then.
+- The Orchestrator refuses a request that needs a scope that the token does not have for the Workflow, with the status
+  code `403`: `the Caller token/<name> needs the "<scope>" scope for Workflow "<workflow>" (ADR-0078)`
+- It refuses an answer to a Gate that an `answer` item with `gates` does not name, with the status code `403`:
+  `the Caller token/<name> needs the "answer" scope for Gate "<gate>" of Workflow "<workflow>" (ADR-0078)`. The body
+  also holds `scope`, `workflow` and `gate`.
+- It refuses a request that needs a scope that the token has for no Workflow, with the status code `403`:
+  `the Caller token/<name> has no "<scope>" scope for any Workflow (ADR-0078)`
+- It refuses a route that no scope opens, such as a runtime Chart, with the status code `403`:
+  `this route needs the Instance token: no scope opens it, so the Caller token/<name> cannot`
+- `jr2 caller token` prints nothing on stdout and exits with `1` when the Secret is not there:
+  ``error: no Caller token "<name>" here (context <context>, namespace <namespace>) — declare it in callers.tokens of jr2.config.ts, then `jr2 up` makes it``
+- `jr2 caller rotate` changes nothing and exits with `1` when the Secret is not there:
+  ``error: no Caller token "<name>" in namespace "<namespace>" — declare it in callers.tokens of jr2.config.ts and run `jr2 up` (tokens here: <names>)``.
+  The part `(tokens here: <names>)` shows only when the namespace has a token.
+- `jr2 caller token` and `jr2 caller rotate` take `-n` and `--context`, and not `--url`: the Orchestrator holds no
+  value.
+
+## Read next
+
+- [Callers and Hooks](../concepts/callers-and-hooks.md)
+- [Secrets and trust](../concepts/secrets-and-trust.md)
+- [ADR-0078](../reference/decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md): the
+  Callers, the scopes, and the named tokens.
+- [ADR-0014](../reference/decisions/0014-observation-is-open-run-state-is-not.md): which scope opens which route.
+- [Start a run](start-a-run.md)

package/docs/guides/give-an-agent-mcp-tools.md

@@ -0,0 +1,422 @@
+---
+title: Give an Agent MCP tools
+description: Declare MCP servers in jr2.config.ts, and give an Agent the tools that it can call on each server.
+---
+
+# Give an Agent MCP tools
+
+Declare the MCP servers of your [Instance](../reference/glossary.md#instance) in `jr2.config.ts`, and give an
+[Agent](../reference/glossary.md#agent) the tools that it can call on each server.
+
+An MCP server gives tools for a service, such as a chat, a ticket tracker or a forge. The tools that an Agent gets from
+the servers that its definition names are its [MCP tools](../reference/glossary.md#mcp-tools). The model calls them in
+its [Turn](../reference/glossary.md#turn), as it calls its [Working tools](../reference/glossary.md#working-tools). A
+call of an MCP tool is not a pick: the Turn goes on after it. When a call needs the approval of a person, the
+[Machine](../reference/glossary.md#machine) makes it.
+[Call an MCP tool from a Machine](call-an-mcp-tool-from-a-machine.md) tells how.
+
+In this [Workflow](../reference/glossary.md#workflow), a Menu-only Agent reads the stand-up channel of two chat
+workspaces, Acme and a partner. Then it posts one summary to the Acme workspace, and picks `posted`. Each workspace has
+its own server entry and its own token. Save the file as `workflows/standup.ts` in your Instance:
+
+**Anthropic**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+
+// The Agent's one pick. Each MCP tool call before it is not a pick, and the Turn goes on.
+const posted = defineEvent({
+  name: "posted",
+  description: "Call this after you posted the summary. Give the link to your message.",
+  input: z.object({ link: z.string().describe("The link to the message that you posted.") }),
+});
+
+const door = z.object({ day: z.string().describe("The day of the stand-up, such as 2026-11-04.") });
+
+type Input = z.infer<typeof door>;
+type Ctx = Input & { link?: string; fault?: string };
+
+export const machine = jr2Setup({
+  types: {} as { context: Ctx; input: Input; output: { link: string } },
+  events: [posted],
+  actors: {
+    reporter: agent({
+      model: "anthropic/claude-haiku-5-5",
+      instructions: "You read what two teams said at their stand-up, and you post one short summary for both teams.",
+      // No Sandbox and no Working tools. Its Turns run on the Instance Harness.
+      workspace: "none",
+      // The servers of the mcp block of jr2.config.ts, by name, each with the tools that the Agent can call.
+      mcp: [
+        { server: "slack-acme", tools: ["read_channel", "post_message"] },
+        // Only read: the Agent cannot post to the partner's workspace.
+        { server: "slack-partner", tools: ["read_channel"] },
+      ],
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "standup",
+  input: door,
+  context: ({ input }) => ({ day: input.day }),
+  initial: "summarizing",
+  states: {
+    summarizing: {
+      invoke: {
+        src: "reporter",
+        input: ({ context }) => ({
+          prompt: `Read #standup in the Acme and the partner workspaces for ${context.day}. Post one summary to #standup of Acme.`,
+        }),
+      },
+      on: {
+        posted: { target: "done", actions: assign({ link: ({ event }) => event.link }) },
+        // A server that does not answer at the first Turn fails the Turn. The reason names the server.
+        "agent.fault": { target: "failed", actions: assign({ fault: ({ event }) => event.reason }) },
+      },
+    },
+    done: { type: "final" },
+    // Not a final state: the run ends `failed`, with the reason of the Turn.
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.fault ?? "the Turn failed" }) } },
+  },
+  output: ({ context }) => ({ link: context.link ?? "" }),
+});
+```
+
+**Local**
+
+```ts
+import { assign } from "xstate";
+import { z } from "zod";
+import { agent, defineEvent, fail, jr2Setup } from "@jr2/orchestrator";
+
+// The Agent's one pick. Each MCP tool call before it is not a pick, and the Turn goes on.
+const posted = defineEvent({
+  name: "posted",
+  description: "Call this after you posted the summary. Give the link to your message.",
+  input: z.object({ link: z.string().describe("The link to the message that you posted.") }),
+});
+
+const door = z.object({ day: z.string().describe("The day of the stand-up, such as 2026-11-04.") });
+
+type Input = z.infer<typeof door>;
+type Ctx = Input & { link?: string; fault?: string };
+
+export const machine = jr2Setup({
+  types: {} as { context: Ctx; input: Input; output: { link: string } },
+  events: [posted],
+  actors: {
+    reporter: agent({
+      model: "local/qwen3.6-35b-a3b",
+      instructions: "You read what two teams said at their stand-up, and you post one short summary for both teams.",
+      // No Sandbox and no Working tools. Its Turns run on the Instance Harness.
+      workspace: "none",
+      // The servers of the mcp block of jr2.config.ts, by name, each with the tools that the Agent can call.
+      mcp: [
+        { server: "slack-acme", tools: ["read_channel", "post_message"] },
+        // Only read: the Agent cannot post to the partner's workspace.
+        { server: "slack-partner", tools: ["read_channel"] },
+      ],
+    }),
+    fail: fail(),
+  },
+}).createMachine({
+  id: "standup",
+  input: door,
+  context: ({ input }) => ({ day: input.day }),
+  initial: "summarizing",
+  states: {
+    summarizing: {
+      invoke: {
+        src: "reporter",
+        input: ({ context }) => ({
+          prompt: `Read #standup in the Acme and the partner workspaces for ${context.day}. Post one summary to #standup of Acme.`,
+        }),
+      },
+      on: {
+        posted: { target: "done", actions: assign({ link: ({ event }) => event.link }) },
+        // A server that does not answer at the first Turn fails the Turn. The reason names the server.
+        "agent.fault": { target: "failed", actions: assign({ fault: ({ event }) => event.reason }) },
+      },
+    },
+    done: { type: "final" },
+    // Not a final state: the run ends `failed`, with the reason of the Turn.
+    failed: { invoke: { src: "fail", input: ({ context }) => ({ reason: context.fault ?? "the Turn failed" }) } },
+  },
+  output: ({ context }) => ({ link: context.link ?? "" }),
+});
+```
+
+The Agent uses the model of the tab. Add the two servers and their tokens to `jr2.config.ts`, beside the fields and the
+entries that are there:
+
+```ts
+import { defineConfig } from "@jr2/orchestrator";
+
+export default defineConfig({
+  // The two tokens. The values come from .env.
+  secrets: [
+    { name: "SLACK_ACME_TOKEN", value: process.env.SLACK_ACME_TOKEN },
+    { name: "SLACK_PARTNER_TOKEN", value: process.env.SLACK_PARTNER_TOKEN },
+  ],
+  // Two servers of one service, each with its own token. The names are yours.
+  mcp: {
+    "slack-acme": { url: "https://mcp.slack.example/mcp", secret: "SLACK_ACME_TOKEN" },
+    "slack-partner": { url: "https://mcp.slack.example/mcp", secret: "SLACK_PARTNER_TOKEN", timeout: "90s" },
+  },
+});
+```
+
+`https://mcp.slack.example/mcp` is an example. Write the URL of the MCP endpoint of your service. Then put the two
+tokens in `.env`:
+
+```sh
+SLACK_ACME_TOKEN=<acme token>
+SLACK_PARTNER_TOKEN=<partner token>
+```
+
+`<acme token>` and `<partner token>` are the tokens that the service gave you for each workspace. Run
+[`jr2 up`](../reference/cli.md#up). Then start a run:
+
+```sh
+jr2 run standup --input '{"day":"2026-11-04"}'
+```
+
+## Declare the servers
+
+The [`mcp`](../reference/config.md#mcp) block of `jr2.config.ts` gives each server a name of yours. An Agent and an
+[Effect](../reference/glossary.md#effect) name a server by this name, and never by its URL or its token. A name has
+lowercase letters, digits and `-`, and it starts with a letter. `jr2` is not a server name, because the tools of the
+[Menu](../reference/glossary.md#menu) have the names `mcp__jr2__<event>`.
+
+A server is one of two kinds:
+
+- **A remote server**, `{ url, secret?, timeout? }`. The Harness speaks to it over Streamable HTTP. `secret` is the name
+  of an entry of the [`secrets`](../reference/config.md#secrets) list: the bearer token of the server. With a `secret`,
+  the URL is `https://`. With no `secret`, it can be `http://`.
+- **A stdio server**, `{ command, args?, timeout? }`. It is a program of the
+  [Sandbox Image](../reference/glossary.md#sandbox-image). See [A stdio server](#a-stdio-server).
+
+`timeout` is the longest time of one call, such as `"90s"` or `"5m"`. The default is 60 seconds. After it, jr2 cancels
+the call, and the model reads that the server did not answer. The server can still do the work of the call.
+
+The token of a remote server is a [Held secret](../reference/glossary.md#held-secret). The Harness sends
+`Authorization: Bearer <Stand-in>`, and the [Custodian](../reference/glossary.md#custodian) puts the token in place of
+the [Stand-in](../reference/glossary.md#stand-in). The model and the
+[Workspace code](../reference/glossary.md#workspace-code) never read the token. With no `hosts`, `headers` or `paths` on
+the entry of the `secrets` list, jr2 binds the token to the host of the server's URL, in the header `authorization`.
+When you set them, they must let the Stand-in through to the URL.
+
+## Name the servers in the Agent
+
+The `mcp` field of the definition is a list. Each entry names one server, and `tools` is the allowlist for a remote
+server:
+
+- `tools: ["read_channel", "post_message"]`: the Agent gets these tools of the server, and no other tool.
+- `tools: "*"`: the Agent gets each tool of the server.
+
+A stdio server takes no `tools`. The Agent gets each tool of the server.
+
+The model reads each tool as `mcp__<server>__<tool>`, such as `mcp__slack-acme__post_message`. That name has only
+letters, digits, `_` and `-`, and at most 128 characters. When `"*"` gives a tool whose name breaks this rule, the
+Harness does not give the tool, and it writes one line in its log that names it.
+
+An Agent can name a server only one time. A Menu-only Agent can name remote servers only. Its Turns run on the
+[Instance Harness](../reference/glossary.md#instance-harness), where no Workspace code runs.
+
+## When the allowlist is a guarantee
+
+The allowlist guards the token of the server. For a remote server, it is a guarantee: the Harness gives the model only
+those tools, and it runs only those tools. The Harness holds the Stand-in of the token in a file that no Workspace code
+can read. Thus only a call of the Harness gets the token from the Custodian.
+
+Workspace code in the Agent's [Sandbox](../reference/glossary.md#sandbox) can spend the token in three cases. In each
+case, jr2 takes only `tools: "*"`:
+
+- The [`workspace()`](../reference/authoring-surface/workspace.md) of the Sandbox lists the secret under `secrets`.
+- A `command` Effect of that Workspace names the secret in its `env`.
+- An `http` Effect of that Workspace sends a file of a Worktree with the secret.
+
+In these cases, a file that the Agent wrote can call each tool of the server with the token. Thus a list would not be a
+limit, and `jr2 up` refuses it. A Menu-only Agent keeps its list, because its Turns run on the Instance Harness.
+
+The scopes of the token are the outer limit. The allowlist makes what the Agent can do with a token smaller, and it
+never makes it larger. Give the server a token with the smallest scopes that the Agent needs. jr2 cannot see one token
+under two secret names. When you do that, a list on one name does not limit what the other name can do.
+
+## Two servers of one service
+
+In the example, `slack-acme` and `slack-partner` have the same URL, and each has its own token. Each Agent that names
+one of them gets its own tools: `mcp__slack-acme__read_channel` and `mcp__slack-partner__read_channel` are two tools.
+
+The two tokens go to one host in one header. The Custodian chooses the token by the Stand-in that the request carries.
+Thus each call goes out with the token of its own server.
+
+## A stdio server
+
+A stdio server is a program in the Sandbox Image. Name its `command` and its `args` in the `mcp` block. The Harness
+starts the program for each conversation of an Agent that names it, at the first Turn. The program runs until the
+conversation ends, or until the Harness stops. Two Agents never share one process. When the process stops, its call
+fails, and the next call starts the program again.
+
+The program is Workspace code. The Harness starts it through the spawner, inside the Landlock confinement of the
+Sandbox, in the directory of the Turn. Its env has only the Stand-ins that the `workspace()` grants, so a stdio server
+has no `secret` of its own. [Write a tool as an MCP server](write-a-tool-as-an-mcp-server.md) adds a stdio server to the
+Sandbox Image.
+
+## The tools of a conversation
+
+`jr2 up` asks each remote server for its tools before it converges, from the check pod and through its Custodian. Each
+name in an allowlist must be a tool of the server:
+
+```text
+…
+mcp: listing the tools of "slack-acme" at <your MCP URL> on the Instance Harness, through a Custodian that holds SLACK_ACME_TOKEN, with its Stand-in
+mcp: listing the tools of "slack-partner" at <your MCP URL> on the Instance Harness, through a Custodian that holds SLACK_PARTNER_TOKEN, with its Stand-in
+provider: the check pod has up to 5 min to start, then up to 6 min for its model and 1 min for each of its 2 MCP servers
+…
+mcp: "slack-acme" lists 2 tool(s); every allowlisted name is there
+mcp: "slack-partner" lists 2 tool(s); every allowlisted name is there
+…
+```
+
+`<your MCP URL>` is the URL of your server. The check pod has the placement of the pods that run the Agent: here, the
+Instance Harness. The number in `lists 2 tool(s)` is the number of tools of the server, and yours can be different.
+`jr2 up` stops when a name is not there, and when the server refuses the token. It only warns when the server does not
+answer. `--skip-provider-preflight` skips the check of the tools and the check of the models. `jr2 up` does not check a
+stdio server.
+
+The Harness reads the tools of each server at the first Turn of a conversation. It keeps the allowed tools, sorted by
+name, and it records them with the conversation. Each later Turn of the conversation gets the same tools, also after a
+park and after a restart of the Harness. A change in the tools block makes the model provider read the full conversation
+again, so the Harness does not read the list again. When the server removes a tool, a call of it fails with the text
+`<server> no longer has the tool <tool>`. A new conversation gets the new list.
+
+The tools block has the Working tools first, then the MCP tools, then the Menu. The
+[Briefing](../reference/glossary.md#briefing) of an Agent with MCP tools tells the model that a call of an MCP tool is
+not a pick and does not end its Turn (see [The Briefing](../concepts/agents-and-turns.md#the-briefing)).
+
+The printed conversation shows a call of an MCP tool as `[<server>/<tool>] <input>`, such as
+`[slack-acme/post_message] {"channel":"C024","text":"…"}`. A pick prints by the name of its event, so the two never look
+the same. The Harness does not print the result of an MCP tool. [Watch a run](watch-a-run.md) gives each line.
+
+## What the model reads
+
+- The text of the result. A result with `structuredContent` and no text gives the JSON as text.
+- The images of the result, such as a screenshot. A model that reads no image gets a line of text in place of each
+  image. An image larger than about 5 MiB is one line of jr2:
+  `[jr2: the result has an image that is too large or not base64, which the model does not read]`.
+- One line of jr2 for each audio or resource in the result:
+  `[jr2: the result has <kind>, which the model does not read]`.
+- A result with `isError` as an error.
+- At most 64 KiB of a result. At the cut, the model reads `[jr2 cut this result at 64 KiB]`.
+- When a call passes the `timeout` of its server:
+  `<server> did not answer the call of <tool> in <seconds> s, so jr2 cancelled the call. The server can still do the work that the call asked for`
+- When the server asks for input during a call:
+  `<server> asked for input during the call of <tool>, and no one can answer it: an Agent's MCP call cannot ask for input. The call failed`
+- When a stdio server stops during a call: `<server> stopped while it ran <tool>. The next call starts it again`
+
+When a server does not answer at the first Turn of a conversation, the Turn fails before the model reads anything. The
+Machine gets [`agent.fault`](../reference/mechanism-events.md#agent-fault), and its `reason` is
+`<server> did not answer: <reason>`. In the example, `agent.fault` goes to `failed`, and the run ends `failed` with that
+reason. At a later call, the model reads the same text, and the Turn goes on.
+
+A result comes from outside the Instance. It can hold text that tries to give the model orders, as a web page can. The
+allowlist limits what the Agent can do with the token. The Machine limits what the run does.
+
+## Bind the servers of a packaged Machine
+
+A Machine from a package names the servers that its Agents need. When your `mcp` block has other names, bind the Agent
+to your servers with [`customize()`](../reference/authoring-surface/customize.md), on the line that registers the
+Machine. For example, `customize(standup, { agents: { reporter: { mcp: [{ server: "chat-main", tools: "*" }] } } })`
+gives the `reporter` each tool of your server `chat-main`.
+
+The list replaces the whole `mcp` list of the Agent. [Bind a shipped Machine's Open parts](bind-open-parts.md) tells how
+to bind the parts of a Machine that you get from a package.
+
+## Rules
+
+When the config loads, it refuses:
+
+- the name `jr2`:
+  `<file> at mcp.jr2: the server name jr2 is reserved — the Menu's tools are named mcp__jr2__<event>; give the server another name (ADR-0079)`
+- a name with other characters:
+  `<file> at mcp.<name>: a server name is lowercase letters, digits and -, and starts with a letter ([a-z][a-z0-9-]*) — it is the <server> of the tool names mcp__<server>__<tool> (ADR-0079)`
+- a `secret` that the `secrets` list does not have:
+  `<file> at mcp.<name>.secret: "<NAME>" is not an entry of secrets — add it: secrets: [{ name: "<NAME>", value: process.env.<NAME> }] (ADR-0079)`
+- a `timeout` that is not a positive duration:
+  `<file> at mcp.<name>.timeout: a timeout is a positive duration, such as "90s", "5m" or "1h" — an entry is <name>: { url, secret?, timeout? } for a remote server, or <name>: { command, args?, timeout? } for a stdio server (ADR-0079)`
+- an entry that is not one of the two kinds, such as one with a `url` and a `command`:
+  `<file> at mcp.<name>: Unrecognized key: "<key>" — an entry is <name>: { url, secret?, timeout? } for a remote server, or <name>: { command, args?, timeout? } for a stdio server (ADR-0079)`
+
+`jr2 up` refuses a URL:
+
+- that is not `http://` or `https://`, such as an empty URL from a variable that `.env` does not set:
+  `refusing: mcp.<name>.url "<url>" is not an http:// or https:// URL — an unset .env variable reads as empty; set it, such as url: process.env.<NAME>_URL (ADR-0079)`
+- with a user name or a password:
+  `refusing: mcp.<name>.url carries userinfo — put the credential in secret, never in the url (ADR-0079)`
+- with `http://`, for a server with a `secret`:
+  `refusing: mcp.<name>.url must be an https:// URL — the server has a secret, <NAME>, and the Custodian carries TLS only (ADR-0059, ADR-0079)`
+
+`jr2 up` refuses a binding of a server's secret that does not let its Stand-in through to the URL. `<i>` is the place of
+the entry in the `secrets` list:
+
+- `secrets[<i>].headers leaves out "authorization", where the Harness sends the Stand-in of <NAME> to mcp.<name>.url — each call of that server would arrive with no credential. Add it, or drop headers to take that default (ADR-0059, ADR-0079)`
+- `secrets[<i>].hosts leaves out <host>, the host of mcp.<name>.url, whose secret <NAME> is — each call of that server would arrive with the Stand-in and fail with 401. Add it, or drop hosts to take that default (ADR-0059, ADR-0079)`
+- `secrets[<i>].paths does not cover <path>, the path of mcp.<name>.url, whose secret <NAME> is — each call of that server would be refused with 403. Add "<path>", or drop paths (ADR-0059, ADR-0079)`
+
+`jr2 up` refuses an Agent's `mcp` list, and prints the line to write. Each refusal starts with
+`refusing: workflow "<workflow>": Agent "<slot>"`, then:
+
+- a server that the `mcp` block does not declare:
+  `names the MCP server "<server>", which the mcp block declares "<names>" — bind the Agent to a declared server where the Machine is registered: export const machine = customize(<import>, { agents: { <slot>: { mcp: [<entries>] } } }); or declare it in jr2.config.ts: mcp: { "<server>": { url: "https://<host>/mcp", secret: "<SECRET>" } } (ADR-0079)`
+- a remote server with no `tools`:
+  `names the remote MCP server "<server>" with no tools — a remote server needs its allowlist: { server: "<server>", tools: ["<tool>"] }, or tools: "*" for every tool (ADR-0079)`
+- an empty list:
+  `gives MCP server "<server>" an empty tools list, which offers no tool — name the tools, or drop the entry (ADR-0079)`
+- a list for a stdio server:
+  `gives a tools list for the stdio MCP server "<server>" — a stdio server takes none: the Agent gets every tool, because the server runs as Workspace code, and a list would guard nothing. Write { server: "<server>" } (ADR-0079)`
+- a stdio server on a Menu-only Agent:
+  `has workspace: "none" and names the stdio MCP server "<server>" — a stdio server runs as Workspace code, inside a Sandbox's confinement, and a "none" Agent's Turns run on the Instance Harness, which has none: name a remote server, or give the Agent a Workspace (ADR-0079, ADR-0031)`
+- a tool whose name breaks the rule:
+  `lists the tool "<tool>" of MCP server "<server>": the model would read it as "mcp__<server>__<tool>", and a tool name is [A-Za-z0-9_-], at most 128 characters — a model provider refuses any other (ADR-0079)`
+- a tool that the list names two times:
+  `lists the tool "<tool>" of MCP server "<server>" twice — a model provider refuses a tools block that has one name two times: list each tool once (ADR-0079)`
+- a server that the list names two times: `names the MCP server "<server>" twice — one entry for each server (ADR-0079)`
+- a list where Workspace code in the Sandbox can spend the secret. `<how>` is one of
+  `its workspace() lists it under secrets`, `the command Effect "<effect>" names it` and
+  `the http Effect "<effect>" sends a Worktree file with it`:
+  `gives a tools list for MCP server "<server>", and Workspace code in its Sandbox can spend that server's secret, <NAME>: <how>. A list would be a hint, not a limit — write { server: "<server>", tools: "*" }, or keep <NAME> out of that Workspace (ADR-0079, ADR-0028)`
+
+For a child Machine, `(on the Machine composed as "<slot>")` comes after the Agent's slot. The publish door of the
+Orchestrator runs the same check of the lists. Thus a publish that did not go through `jr2 up` is refused too, and the
+Orchestrator keeps the Assembly that it has.
+
+`jr2 up` checks the tools of each remote server from the check pod. It stops with an error for:
+
+- a name in an allowlist that the server does not list:
+  `error: mcp: workflow "<workflow>": Agent "<slot>" allowlists the tool "<tool>", which "<server>" does not list — it lists: <tools> (ADR-0079)`
+- a server that refuses the request with 401 or 403:
+  `error: mcp: "<server>" at <url> refused the request from a pod on <where> (HTTP <status>) — a wrong or expired value of <NAME>, or a binding of it (hosts, headers, paths) that does not let its Stand-in through to the url; every call of an Agent that names it would fail (ADR-0079)`
+
+It warns about a server that does not answer:
+`warning: mcp: "<server>" at <url> did not answer from a pod on <where> (<reason>) — its tool names are not checked; a Turn of an Agent that names it fails if it does not answer then (ADR-0079)`.
+With `--skip-provider-preflight`, it warns:
+`warning: provider: preflight skipped (--skip-provider-preflight) — these models were not checked: <models>; these MCP servers' tool lists were not checked: <servers>`.
+
+## Read next
+
+- [Agents and Turns](../concepts/agents-and-turns.md#the-mcp-tools): the MCP tools beside the Working tools and the
+  Menu.
+- [Secrets and trust](../concepts/secrets-and-trust.md): who holds the token of a server.
+- [Call an MCP tool from a Machine](call-an-mcp-tool-from-a-machine.md): a call that a person approves first.
+- [Write a tool as an MCP server](write-a-tool-as-an-mcp-server.md): your own tool, in the Sandbox Image.
+- Reference: [`mcp`](../reference/config.md#mcp),
+  [`AgentMcpServer`](../reference/authoring-surface/type-agentmcpserver.md) and
+  [`AgentDefinition`](../reference/authoring-surface/type-agentdefinition.md).
+- [ADR-0079](../reference/decisions/0079-an-agent-holds-mcp-tools-a-machine-calls-them-as-an-effect-and-the-machine-is-the-approval.md):
+  an Agent holds MCP tools, a Machine calls them as an Effect, and the Machine is the approval.
+- [ADR-0028](../reference/decisions/0028-what-an-agent-may-do-to-the-workspace-is-part-of-its-definition.md): the
+  allowlist is a guarantee about the credential.
+- [ADR-0059](../reference/decisions/0059-a-harness-holds-stand-ins-and-the-custodian-holds-the-keys.md): the Custodian
+  holds the keys.