@smthrs/mcp 0.0.0-stage → 1.0.0-rc.3

package/docs/concepts/the-session.md

@@ -0,0 +1,135 @@
+---
+title: "The life of a session"
+description: "How an MCP session starts, what it holds, when it ends, and what happens to in-flight requests: the handshake, the catalog snapshot, scope-bound teardown, and cancellation."
+sidebar:
+  order: 2
+---
+
+An MCP session is a subprocess. Everything surprising about this package follows
+from that: the process has to be started, negotiated with, bounded, and torn
+down, and any of those steps can end the session in the middle of a call.
+
+## Starting
+
+`McpClient.connect` performs five steps before it returns, and a failure at any
+of them fails the whole effect:
+
+1. Spawn the command with `stdin`, `stdout`, and `stderr` piped. A spawn that
+   fails is `spawn_failed`.
+2. Send `initialize`, proposing `2025-06-18` and disclosing the frozen
+   `McpClient.clientInfo` identity: name `"smithers"` and this package's
+   version.
+3. Validate the result. The server's `protocolVersion` must be one of
+   `McpClient.supportedProtocolVersions`, and its `capabilities` must declare a
+   `tools` object. A server that serves no tools is refused with
+   `protocol_error` rather than connected and left useless.
+4. Send `notifications/initialized`. This is a notification, not a request: the
+   server never replies, and the handshake is not complete until the client
+   sends it.
+5. Walk `tools/list`, following `nextCursor` until the server stops sending one.
+
+Steps 2 through 5 are each bounded by `handshakeTimeoutMs`, which defaults to 10
+seconds and is separate from the deadline later tool calls get.
+
+## Holding
+
+What the session holds is small: the server name, the tool catalog, and a way to
+call one entry of it.
+
+The catalog is a **deeply frozen snapshot**, including tool entries and their
+schemas. Editing the public catalog cannot change future dispatch or validation;
+make a separate copy if a consumer needs a mutable view. It is fetched once and
+never refreshed. A server
+that later announces `notifications/tools/list_changed` is not re-polled, and
+server-initiated notifications are received and dropped. To pick up a changed
+catalog, close the scope and connect again.
+
+That choice is what makes the projection stable. `McpFlows` derives flow
+declarations from the catalog, and a declaration digest that changed underneath a
+running cell would be refused by the boundary that recorded it.
+
+`callTool` checks the name against that snapshot before it writes anything: an
+unknown tool fails with `tool_not_found` without a JSON-RPC frame reaching the
+server.
+
+## Ending
+
+The connection is scoped, and the scope is the lifetime. Closing it tears the
+process down. Four other events end a session, and all five are the same
+terminal transition:
+
+| Event                        | The error every waiter gets                    |
+| ---------------------------- | ---------------------------------------------- |
+| The scope closes.            | `connection_closed`, "connection scope closed" |
+| The child exits.             | `connection_closed`, "exited with code N"      |
+| Its stdout reaches EOF.      | `connection_closed`, "stdout closed"           |
+| Its stdin closes.            | `connection_closed`, "stdin closed"            |
+| A tagged reply is malformed. | `protocol_error`, naming what was malformed    |
+
+Whichever arrives first wins. It closes the connection once, fails every pending
+request with that one error, and rejects all later traffic with the same error,
+so a caller never waits on a reply that can no longer come. A clean child exit
+is still a closed session: Node reports an ordinary exit by ending stdout
+successfully. When a healthy connection's scope closes, its terminal reason is
+recorded before I/O teardown, so cleanup does not report "stdin closed".
+
+For `spawn_failed`, `timeout`, and `connection_closed`, the message withholds
+process details. A child's stderr may contain credentials, so the client
+redacts each complete stderr line as it arrives and caps only the redacted text.
+A cap cannot cut a credential's recognizable prefix, and a line longer than
+64 KiB is withheld whole. The bounded, whitespace-collapsed tail is available
+only to an explicitly installed
+[private host diagnostic observer](../api.md#diagnostics); it is never appended
+to the ordinary error. Without that observer, private details are discarded.
+
+## Noise and protocol traffic on stdout
+
+MCP servers commonly log to stdout, so this client distinguishes noise from
+protocol:
+
+- A blank line, invalid JSON, a JSON scalar, an array, `null`, or a JSON object
+  with no own `jsonrpc` property is **noise**, and is dropped.
+- An object that does carry `jsonrpc` is **protocol traffic**. Its version must
+  be exactly `"2.0"`. A valid method-bearing envelope without an id is a
+  notification and is dropped; with an id it is a server request. Anything
+  else must be a valid reply with an id and exactly one of `result` or `error`.
+
+Server `ping` requests receive `{ result: {} }`, preserving the exact string or
+integer id, including while a tool call is pending. Unsupported server methods
+receive JSON-RPC `-32601` (`Method not found`); they are never silently dropped.
+Server-request ids are independent of client-request ids. Reply frames use the
+same outbound byte and queue bounds, with `requestTimeoutMs` limiting queue
+admission; a blocked response closes the connection instead of hanging the
+reader. This implements the negotiated
+[MCP ping contract](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/ping).
+
+A malformed tagged envelope closes the connection with `protocol_error`. A
+well-formed reply for an id nobody is waiting on is dropped. The raw frame is
+never attached to the error.
+
+A valid error reply with `id: null` cannot be correlated to a request. Its code,
+message, and data go only to the private diagnostic observer as `remote-error`,
+then the reply is dropped. The connection stays open and pending requests keep
+waiting for their own replies or deadlines. A null id on a result, or a malformed
+error object with a null id, still closes the connection with `protocol_error`.
+
+## Cancelling
+
+Every MCP tool flow is declared `irreversible`, so an abandoned in-flight
+mutation is a durability problem rather than a tidiness one. When a `tools/call`
+times out or its fiber is interrupted before dispatch, the writer skips its
+queued frame. Once handed to the writer, an abandoned request triggers one
+best-effort `notifications/cancelled` for that request id.
+
+The notification is best effort. A full outbound queue drops it rather than
+delaying the deadline it reports, because a cancellation that made a timeout
+late would defeat the timeout. `initialize` is never cancelled, and a request
+that already received a reply, whether a result or a JSON-RPC error, is never
+cancelled either.
+
+## Next
+
+- [Connect a server](../guides/connect-a-server.md): the options that shape all
+  of this.
+- [Bound an untrusted server](../guides/bound-an-untrusted-server.md): the ten
+  limits and what each one protects.

package/docs/concepts/tools-as-flows.md

@@ -0,0 +1,116 @@
+---
+title: "A remote tool as a flow"
+description: "What McpFlows projects from a tool catalog: the flow name, the input document, the result shape, and the declaration every MCP tool flow shares."
+sidebar:
+  order: 1
+---
+
+The whole adapter is one idea: a remote MCP tool is a flow declaration plus the
+code that runs it, which is what every other flow already is. Nothing about the
+harness, the registry, or the cell loop learns that a given flow proxies a
+remote `tools/call`. A cell that reads a file and a cell that calls an MCP tool
+run the identical two lines: find the flow in `ctx.flows`, invoke it with
+`ctx.call`.
+
+That is why this package is small. It is a client and a projector, not a second
+capability system.
+
+## What one tool becomes
+
+`McpFlows.mcp` walks the catalog and produces one `FlowBinding.Binding` per
+tool. Each binding declares:
+
+| Field           | Value                                                                                                                                                                       |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`          | `<prefix>/<tool>`, where the prefix defaults to `mcp/<server>`.                                                                                                             |
+| `description`   | `MCP tool "<tool>" on server "<server>"`, followed by `. Server-supplied description: <text>` when the server sent one, so the model reads the text as the remote server's. |
+| `input`         | `McpFlows.Args`, a permissive `Record<string, unknown>`.                                                                                                                    |
+| `inputDocument` | The server's own `inputSchema` document, carried by value.                                                                                                                  |
+| `output`        | `McpFlows.Result`: `content`, `isError`, and optional `structuredContent`.                                                                                                  |
+| `capabilities`  | `McpFlows.capabilities`, the same frozen list for every tool.                                                                                                               |
+| `effects`       | `McpFlows.effects`, the same conservative envelope for every tool.                                                                                                          |
+
+The name is scoped by server so two servers may offer a tool of the same name
+without colliding. A tool name may not contain `/`, which is what keeps
+`mcp/<server>/<tool>` unambiguous.
+
+## Two schemas, on purpose
+
+The runtime decode and the disclosed parameter shape are different documents,
+and the difference is deliberate.
+
+`input` is `McpFlows.Args`, which accepts any string-keyed record. The adapter
+does not validate arguments, because the remote server owns that decision: its
+schema is the authority, and a second validator here would either duplicate it
+or disagree with it.
+
+`inputDocument` is the server's own JSON Schema, passed through unchanged. That
+is what a caller reading `ctx.flows` sees, and what a model is shown. So the
+model gets the real parameter shape while the boundary stays out of the
+server's way.
+
+This is why every catalog entry must declare an `inputSchema` whose `type` is
+exactly `"object"`. A tool with no usable parameter document would be disclosed
+to a model as if it had one, so the catalog is rejected at connect time
+instead.
+
+## A tool-level failure is data
+
+A `tools/call` that reaches the server and comes back is a success, whatever it
+says. MCP distinguishes "the call failed" from "the tool ran and reported a
+problem", and the second one arrives as `{ isError: true }` on a successful
+reply. The binding returns it in the success channel.
+
+`McpError` is the other channel entirely, reserved for failures of the session:
+the server would not start, the pipe closed, a reply could not be parsed.
+The binding explicitly publishes `McpError.message` as a catchable
+`flow_failed` result. The client authors this model-facing text with remote
+error bodies and process diagnostics withheld. Custom clients must preserve
+that public-message contract. See
+[Handle a failed tool call](../guides/handle-a-failed-tool-call.md).
+
+## One declaration for every tool
+
+Every projected flow declares the same authority and the same effects, because
+an MCP tool is opaque code this adapter does not control. Guessing narrower
+would be a claim nobody can back.
+
+`McpFlows.effects` declares `reads: ["**"]`, `writes: ["**"]`,
+`mode: "expected"`, `onConflict: "serialize"`, and `tier: "irreversible"`. The
+irreversible tier is why a timed-out call sends a cancellation: an abandoned
+in-flight mutation is a durability problem.
+
+`McpFlows.capabilities` is one exact `namespace:operation:resource` string per
+host action, at resource `**`, derived from `Capability.Action.literals`. It is
+spelled out one action at a time rather than as a wildcard because the cell
+boundary parses a declared capability with `Capability.parse`, which requires
+exactly three colon-separated components. A bare `"*"` parses as nothing, and an
+unparseable declaration counts as unauthorized, so a wildcard would refuse every
+MCP tool before it ran, under every envelope including an unrestricted one.
+
+Deriving the list rather than restating it means a new action in
+[`@smthrs/capability`](/api/capability) cannot be silently dropped from what an
+MCP tool declares.
+
+The consequence for a host is that the projected declaration is a ceiling, not a
+recommendation. Narrowing it is the host's decision and its own step; see
+[Grant authority to MCP tools](../guides/grant-authority-to-mcp-tools.md).
+
+## Where the source goes
+
+`FlowBinding.Source` is the same type `StandardFlows.filesystem` and
+`StandardFlows.shell` return, so a projected server composes with them in one
+array:
+
+```ts
+const catalog = yield * FlowBinding.catalog([
+  StandardFlows.filesystem(filesystemServices),
+  StandardFlows.shell(shellServices),
+  mcpSource
+])
+```
+
+Duplicate flow names fail composition rather than dispatching one descriptor to
+another implementation, which is another reason the default prefix carries the
+server name. For the harness side of this, see
+[Bind flows](/pkg/harness/guides/bind-flows).

package/docs/guides/bound-an-untrusted-server.md

@@ -0,0 +1,158 @@
+---
+title: "Bound an untrusted server"
+description: "The ten limits McpClient enforces on a remote server, their default values, what each one protects, and the rules a tool name must satisfy."
+sidebar:
+  order: 6
+---
+
+The server sizes the frames it sends, the catalog it declares, and the flow
+names a model reads. All three are inputs from a process you do not control, so
+every one of them is bounded, and every bound is an option with an exported
+default constant.
+
+You rarely need to change these. Read this page when a real server trips one, or
+when you are deciding what to allow a server you do not trust.
+
+## The ten limits
+
+| Option                  | Default | Constant                                 | What it bounds                                      |
+| ----------------------- | ------- | ---------------------------------------- | --------------------------------------------------- |
+| `handshakeTimeoutMs`    | 10000   | `McpClient.defaultHandshakeTimeoutMs`    | Each `initialize` and `tools/list` exchange.        |
+| `requestTimeoutMs`      | 120000  | `McpClient.defaultRequestTimeoutMs`      | Each later `tools/call` exchange.                   |
+| `queueCapacity`         | 64      | `McpClient.defaultQueueCapacity`         | Outbound frames waiting to be written.              |
+| `maxFrameBytes`         | 1048576 | `McpClient.defaultMaxFrameBytes`         | One inbound JSON-RPC frame, in UTF-8 bytes.         |
+| `maxOutboundFrameBytes` | 1048576 | `McpClient.defaultMaxOutboundFrameBytes` | One outbound JSON-RPC frame, in UTF-8 bytes.        |
+| `maxTools`              | 256     | `McpClient.defaultMaxTools`              | Tools accepted across every catalog page.           |
+| `maxToolNameBytes`      | 128     | `McpClient.defaultMaxToolNameBytes`      | UTF-8 bytes in one tool name.                       |
+| `maxToolDocumentBytes`  | 65536   | `McpClient.defaultMaxToolDocumentBytes`  | One tool's description plus JSON `inputSchema`.     |
+| `maxCatalogPages`       | 32      | `McpClient.defaultMaxCatalogPages`       | `tools/list` pages walked while following a cursor. |
+| `maxStderrBytes`        | 2048    | `McpClient.defaultMaxStderrBytes`        | Child stderr retained as a diagnostic tail.         |
+
+Every one must be a positive safe integer. A zero, a negative number, a fraction,
+or a number above `Number.MAX_SAFE_INTEGER`
+fails with `protocol_error` naming the option, before the process is spawned.
+
+```ts
+const client = yield * McpClient.connect({
+  server: "large",
+  command: "node",
+  args: ["server.mjs"],
+  maxTools: 512,
+  maxFrameBytes: 4 * 1024 * 1024
+})
+```
+
+## What each one is actually protecting
+
+**The two frame sizes** protect memory. The stdout reader never retains more
+than one bounded partial frame, so a server that writes a gigabyte without a
+newline fails at the limit rather than growing the heap. The outbound bound
+catches the mirror case: a tool argument large enough to be its own problem is
+refused before it is written.
+
+**`queueCapacity`** bounds outbound frames waiting on a server that has stopped
+reading its stdin. Past capacity, an offer blocks until the deadline for that
+request expires.
+
+**`maxTools`, `maxToolNameBytes`, `maxToolDocumentBytes`, and
+`maxCatalogPages`** bound the catalog, which is the part a model reads.
+`maxToolDocumentBytes` counts the UTF-8 bytes of a tool's description plus its
+JSON-encoded `inputSchema`, so one tool cannot flood the model's context with
+server-authored text. A catalog past `maxTools` fails with
+`invalid_response` rather than being truncated, because a silently truncated
+toolset is worse than a refused connection. `maxCatalogPages` and a repeated
+cursor both end a cursor walk that would otherwise never finish.
+
+**`maxStderrBytes`** bounds a diagnostic buffer. Child stderr is drained
+continuously and only the tail is retained, so a chatty server cannot fill
+memory through the channel that exists to explain its failures.
+The tail never enters an ordinary error. Only an explicitly installed
+[private diagnostic observer](../api.md#diagnostics) may receive it, wrapped in
+`Redacted`. This per-event bound does not bound memory retained by a host's own
+observer; that observer must also limit its history.
+
+**The two deadlines** are separate because they answer different questions. A
+server that never completes a handshake is broken and should fail fast; a tool
+that takes a minute may be working.
+
+## JSON depth and expansion
+
+Bytes alone do not make recursive consumers safe. All incoming JSON-RPC messages
+are checked iteratively before catalog/result validation, and may contain at
+most `McpClient.maxJsonDepth` (128) nested object/array containers, counting the
+wire envelope. This bound is fixed, not increased by raising `maxFrameBytes`.
+Outgoing arguments have the same bound: their root object already counts as
+container three, inside the envelope and `params`. A scalar adds no container.
+An oversized depth or numeric overflow to infinity is a typed `protocol_error`,
+not a stack-overflow defect.
+
+Argument copying also stops when a lower bound on its expanded encoded size
+exceeds `maxOutboundFrameBytes`. A compact JavaScript graph with shared children
+can expand exponentially as JSON; each repeated occurrence consumes the budget.
+Exact UTF-8 frame sizing, including escapes and protocol overhead, still runs
+before writing. The argument root must be a JSON object. A rejected argument
+does not send a request or close the session.
+
+The host still owns memory it allocated before calling this library and any
+executable Proxy traps it supplies. Incoming frames are parsed before the
+iterative depth check, with parse allocation bounded by `maxFrameBytes`; this is
+not a constant-memory streaming JSON parser.
+
+## The rules a tool name must satisfy
+
+Beyond the byte length, a tool name may not contain:
+
+- `/`, because the name is embedded in `mcp/<server>/<tool>`.
+- A control character (Unicode category Cc): C0 (U+0000 through U+001F),
+  U+007F, and C1 (U+0080 through U+009F).
+- A format character (Unicode category Cf), which includes zero-width marks
+  (U+200B through U+200F, U+2060, U+FEFF), bidi overrides and isolates
+  (U+202A through U+202E, U+2066 through U+2069), and the soft hyphen.
+- U+2028 or U+2029, the line and paragraph separators.
+- A lone UTF-16 surrogate.
+
+The name also may not be exactly `.` or `..`, which read as path segments.
+
+A name that breaks any of these fails the connection with `invalid_response`.
+The name reaches a model inside a flow name and the journal inside a declaration
+digest. An invisible or reordering character would let one tool read as another
+to the model or to a person reviewing an approval, so none of these is cosmetic.
+
+Two tools with the same name in one catalog also fail: a duplicate would make
+`mcp/<server>/<tool>` ambiguous.
+
+## The rules a catalog entry must satisfy
+
+- `tools` must be an array, and every element an object.
+- `name` must be a non-empty string.
+- `inputSchema` must be an object whose `type` is exactly `"object"`. A tool
+  with no usable parameter document is refused rather than disclosed to a model
+  as if it had one.
+- `outputSchema`, when present, must be a JSON object.
+- `nextCursor`, when present, must be a non-empty string, and must not repeat a
+  cursor already seen.
+
+## Persisting a configuration
+
+`McpClient.ConnectOptionsSchema` is the authoritative decoder for a stored
+server entry. It requires a non-empty `server` and `command`, string `args`, a
+string-valued `env` record, and positive integers for every limit:
+
+```ts
+import * as McpClient from "@smthrs/mcp/McpClient"
+import { Schema } from "effect"
+
+const decode = Schema.decodeUnknownSync(McpClient.ConnectOptionsSchema)
+const options = decode(JSON.parse(fileContents))
+```
+
+Use it wherever connection options arrive from a file or a database, so a bad
+entry is a decode failure at the edge rather than a `protocol_error` at connect
+time. See
+[Configure servers for the CLI](./configure-servers-for-the-cli.md).
+
+## Next
+
+- [The life of a session](../concepts/the-session.md): what the limits are
+  protecting.
+- [Troubleshooting](../troubleshooting.md): the message each limit produces.

package/docs/guides/configure-servers-for-the-cli.md

@@ -0,0 +1,167 @@
+---
+title: "Configure servers for the CLI"
+description: "Write the --mcp-config file the Smithers CLI reads, know which fields it validates, and understand when a bad entry fails."
+sidebar:
+  order: 7
+---
+
+The CLI composes this package behind one flag. `smthrs --mcp-config <path>`
+names a file of MCP servers that the local executor connects at startup and
+projects into a run's flow catalog, so a flow can call them.
+
+`SMITHERS_MCP_CONFIG` sets the same path. The flag wins when both are present,
+and omitting both configures no MCP servers.
+
+## Install the server
+
+Install a reviewed server version and its dependencies before supplying any
+credentials. This example pins the deprecated GitHub server to `2025.4.8`;
+review it for your use before running it. Use a dedicated directory, review and
+retain `package.json` and `package-lock.json`, then install from that lockfile:
+
+```bash
+mkdir -p /path/to/mcp-servers
+env -u GITHUB_TOKEN -u GITHUB_PERSONAL_ACCESS_TOKEN npm install --prefix /path/to/mcp-servers --package-lock-only --ignore-scripts --save-exact @modelcontextprotocol/server-github@2025.4.8
+# Review the pinned package and lockfile before installing.
+env -u GITHUB_TOKEN -u GITHUB_PERSONAL_ACCESS_TOKEN npm ci --prefix /path/to/mcp-servers --ignore-scripts
+```
+
+Both npm commands remove the GitHub credential variables from their environment.
+Launch the installed executable directly and supply the token only in the
+server's `env`. This server reads `GITHUB_PERSONAL_ACCESS_TOKEN`.
+
+## The file
+
+A JSON array. Each entry is a stdio server (`command`) or a Streamable HTTP
+server (`url`), never both, plus `McpFlows.ProjectionOptions`:
+
+```json
+[
+  {
+    "server": "github",
+    "command": "/path/to/mcp-servers/node_modules/.bin/mcp-server-github",
+    "args": [],
+    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." },
+    "exclude": ["delete_repository"],
+    "namePrefix": "github"
+  },
+  {
+    "server": "reports",
+    "command": "node",
+    "args": ["./tools/reports-server.mjs"],
+    "cwd": "/srv/reports",
+    "requestTimeoutMs": 30000
+  }
+]
+```
+
+By default, tools arrive as flows named `mcp/<server>/<tool>`. With the custom
+`namePrefix` above, GitHub tools arrive as `github/<tool>`.
+
+## Remote servers
+
+A remote server takes a `url` instead of a `command`. Its bearer token is
+never written in the file: `bearerTokenEnv` names the environment variable the
+CLI reads it from.
+
+```json
+[
+  {
+    "server": "tracker",
+    "url": "https://mcp.tracker.example/mcp",
+    "bearerTokenEnv": "TRACKER_MCP_TOKEN",
+    "namePrefix": "tracker"
+  }
+]
+```
+
+Export `TRACKER_MCP_TOKEN` from your secret store in the shell that runs
+`smthrs`; never type the token on the command line.
+
+Requests go through the host's egress client, so its proxy settings and
+capability grants apply. A grant that denies `net:post` to the server's origin
+stops the executor before the first request is sent.
+
+## What the flag validates
+
+The CLI decodes every stdio entry with `McpClient.ConnectOptionsSchema` and
+every HTTP entry with `McpClient.HttpConnectOptionsSchema` before any layer is
+built. A bad file is a usage error naming the flag and path.
+
+A stdio entry:
+
+| Field                                                               | Requirement                       |
+| ------------------------------------------------------------------- | --------------------------------- |
+| `server`, `command`                                                 | Required non-empty strings.       |
+| `args`                                                              | Required array of strings.        |
+| `cwd`                                                               | Optional non-empty string.        |
+| `env`                                                               | Optional object of string values. |
+| `handshakeTimeoutMs`, `requestTimeoutMs`                            | Optional positive integers.       |
+| `queueCapacity`, `maxFrameBytes`, `maxOutboundFrameBytes`           | Optional positive integers.       |
+| `maxStderrBytes`, `maxTools`, `maxToolNameBytes`, `maxCatalogPages` | Optional positive integers.       |
+| `maxToolDocumentBytes`                                              | Optional positive integer.        |
+
+An HTTP entry:
+
+| Field                                                                      | Requirement                                                         |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `server`                                                                   | Required non-empty string.                                          |
+| `url`                                                                      | Required absolute `http:` or `https:` URL without user or password. |
+| `bearerTokenEnv`                                                           | Optional environment variable name, set and non-empty at startup.   |
+| `handshakeTimeoutMs`, `requestTimeoutMs`, `maxFrameBytes`                  | Optional positive integers.                                         |
+| `maxOutboundFrameBytes`, `maxTools`, `maxToolNameBytes`, `maxCatalogPages` | Optional positive integers.                                         |
+| `maxToolDocumentBytes`                                                     | Optional positive integer.                                          |
+
+Four failures are usage errors that name the path: the file is missing, it
+cannot be read, it is not valid JSON, or it is not an array of entries accepted
+by the schemas. For example, `maxTools: 0` fails here before connecting a server.
+An unset `bearerTokenEnv` variable is a usage error naming the server and the
+variable.
+
+## Select and name tools
+
+The CLI preserves these projection fields and passes them to
+`McpFlows.connected`:
+
+| Field        | Meaning                                                                   |
+| ------------ | ------------------------------------------------------------------------- |
+| `include`    | Optional array of exact tool names. Omitted or empty includes every tool. |
+| `exclude`    | Optional array of exact tool names to drop, applied after `include`.      |
+| `namePrefix` | Optional replacement for the default `mcp/<server>` flow-name prefix.     |
+
+The checked projection constructor rejects an empty `namePrefix` before
+spawning and unknown `include` names after reading the catalog. These are
+projection errors, separate from the connection schema's file validation.
+
+## When a bad server fails
+
+Every configured server is connected when the executor starts, because naming it
+in the file is an operator opting into it. A server that fails to spawn, is
+denied by the egress grants, or refuses the handshake takes the executor down
+loudly rather than leaving a run silently short of the tools it was configured
+to have.
+
+That is the right trade for a configured dependency and the wrong one for an
+experiment. Try a new server in a scratch config before adding it to the one a
+production run uses.
+
+## The flag does nothing under --remote
+
+Under `--remote`, the executor is not this process's to configure, so
+`--mcp-config` is meaningless. Configure MCP servers where the executor actually
+runs.
+
+## The other direction
+
+This flag is Smithers calling somebody else's tools. The reverse, an agent such
+as Claude Code driving Smithers, is the Smithers MCP server: see
+[`smthrs mcp`](/cli/mcp) and
+[Wire the MCP server into an agent](/pkg/cli/guides/wire-the-mcp-server). The two
+share a name and nothing else.
+
+## Next
+
+- [Bound an untrusted server](./bound-an-untrusted-server.md): what the numeric
+  fields do.
+- [Select the tools a run sees](./select-the-tools-a-run-sees.md): narrowing a
+  large catalog and choosing a projection constructor.