Archive

Where retired entries go.

docs/release-runbook.md says never to delete a feature entry: either strike its heading through and set status: retired, or move the whole entry here and leave a one-line stub in the feature list pointing at it. Heavy refactors move the old text here too.

This file is append-only and unordered. It is not a changelog and nothing reads it in sequence; it exists so that a question about why something was removed has an answer that is still in the tree, rather than only in a squashed commit message.

An entry keeps the key block it had when it was live, plus the reason it was retired and what replaced it.

It is empty because nothing has been retired yet. The runbook named it before it existed, which is the documentation form of a capability declared and not delivered; TestEveryDocumentationLinkResolves in internal/defaults is what noticed, and what will notice the next one.

The binary

Binary

mcpx ships as one Go binary, built from cmd/mcpx. This page states what is shipped — what the binary contains, what it needs next to it, and how the two packaged forms are built — not what could be built. Where a fact changes per release channel, this page says so and stops; release and install channels are a different page’s subject.

What is in it

The version is 0.1.0, hard-coded as the default in cmd/mcpx/main.go and stamped by the package with -X main.version=0.1.0; a build may override it with the same -ldflags variable, and nothing else about the binary changes.

Everything else is the module’s direct dependencies. go.mod is the source of truth — seven direct requirements:

The three charmbracelet modules are one decision: about 1.2 MB in the stripped binary, in exchange for not hand-writing terminal handling. dependencies.md argues each of the original five in full; it and package.nix still say “five” because both predate the last two rows — trust go.mod, and this table, over that count.

Two absences are as deliberate as the presences:

• No MCP SDK. mcpx is built on none — there is no MCP module in go.mod. The MCP client (internal/mcpclient), the server (internal/mcpserver) and the JSON-RPC framing are mcpx’s own code, about a package each. That is most of why the dependency list stays this short.
• Everything else is the standard library: the daemon and its HTTP API, the process pools, the JSON Schema to TypeScript compiler, the CLI.

How the shipped builds link

Every direct dependency is pure Go, so a CGO_ENABLED=0 build is fully static, and that is what the Nix package ships: env.CGO_ENABLED = "0" in package.nix, stripped (-s -w), so the shipped binary is a static executable that needs no libc next to it.

The container image makes the other choice, on purpose for now: its Containerfile defaults CGO_ENABLED to 1, so the binary it ships links glibc and the runtime stage is Debian bookworm-slim. A static container build was measured working end-to-end before that default was chosen — see container.md, which this page links rather than restates, because the container is still changing.

The behavioural difference between the two is narrow and worth stating exactly: with cgo off, pure-Go os/user reads /etc/passwd rather than asking NSS/LDAP, and the pure-Go resolver bypasses NSS modules — on Linux only; on macOS, CGO_ENABLED=0 changes neither, because Go uses the system resolver and user database there without cgo either way. Neither difference prevents a static build, and this page never claims they do; which form to ship where is a policy question, tracked with the release work, not a technical block.

Size, as last measured in container.md: the mcpx binary is about 14.8 MB in the container build. (The 21 MB figure sometimes quoted is an older linux/arm64 static build; measure the artifact you are shipping, not either number here.)

What it needs next to it

The binary alone answers ls, types, catalog, search and call. The rest of what it reaches for is external programs — the full table, with what degrades when each is missing, is in dependencies.md:

• A JavaScript runtime — deno, bun or node — for mcpx run and mcpx exec only. Without one, those two commands fail and everything else still works.
• git — a fallback only. mcpx reads .git itself for the repo and worktree scopes (see git-discovery.md) and runs git rev-parse only for a repository layout its own reader does not vouch for. Without git, those rare layouts degrade to keying by directory, and mcpx doctor says why.
• The configured MCP servers themselves — spawned with the command, args, env and cwd the config names, or reached over Streamable HTTP for url servers.

The Nix package wraps the binary with a PATH suffix naming git, deno, bun-bin and nodejs, so those four are findable without depending on the calling shell — and because it is a suffix, a runtime already on your PATH wins over the wrapped one. The same package installs the generated man page and shell completions (see the CLI page).

The container image ships exactly one runtime — bun — and sets MCPX_SCRIPT_RUNTIME=bun, so the runtime choice inside the image is unambiguous; it leaves git out entirely, for the reason above. What the image deliberately does not contain, and why, is container.md’s subject.

The CLI

The mcpx command line, in three parts: how a session with it normally goes, the two kinds of flag it accepts, and where the full command reference lives. The CLI is one of the client interfaces — everything it does goes through the daemon’s /v1 API, and anything a person can do here, a script or a plugin can do there.

The CLI

The loop

Almost every session is the same four steps (the same loop AGENTS.md teaches agents):

1. mcpx ls — which namespaces exist. Cheap; run it whenever.
2. mcpx search <words> — find a tool by name or description.
3. mcpx types <namespace> — load signatures for that namespace only (or mcpx types <namespace>.<tool> for one tool, which is far cheaper). mcpx catalog fits every namespace into a token budget when you are still deciding.
4. mcpx run <name> or mcpx exec '<code>' — do the work.

Do not run mcpx types for every namespace: loading one costs a few hundred tokens, loading all of them costs thousands and defeats the point of keeping schemas out of context until asked.

Output a program can read

Human output is for humans. Anything that has to be parsed gets --json instead:

mcpx --json ls
mcpx --json run screenshot

--json returns one document — for a script run, the result, the logs, the exit code and the duration. Never parse the human tables.

Bare invocation, and a runnable first argument

Bare mcpx opens the TUI (the tui browser) when there is a terminal to draw on, and prints help when there is not — a pipe gets the old behaviour.

A first argument that is obviously a script runs without naming a command: a path ending in .ts, .js, .mts or .mjs, any existing file, or text that is obviously source (it contains (){};, await , console., tools. or =>) is handed to run or exec as appropriate:

mcpx ./report.ts
mcpx 'await chrome_devtools.list_pages({})'

This is deliberately conservative: a bare word that is not a file fails as an unknown command, because guessing that mcpx serach was a snippet would replace a clear error with a baffling one.

Exit codes worth knowing

The man page and shell completions

Both are generated from the same command declarations as everything else, so they cannot drift from the binary:

mcpx man
mcpx completion bash   # also: zsh, fish

The Nix package installs both for you: the man page to share/man/man1/mcpx.1, and completions for all three shells.

CLI arguments

Flags come in two kinds, and most confusion about mcpx flags is really about which kind one is looking at.

Kind 1: hand-parsed global flags, before the subcommand

A short list, parsed by hand in cmd/mcpx/main.go before any subcommand is chosen. These, and only these, have fixed global meanings:

One extension to that list: a setting that every command accepts is also accepted as a global flag, so mcpx --plumbing-strict-unknown-keys ls means what mcpx ls --plumbing-strict-unknown-keys does. An unrecognised global flag is an error (exit 2), never a guess.

Kind 2: registry flags, bound per command

Every other flag is generated from the settings registry and bound per command: parseFlags calls BindFlags for the command being run, which binds exactly the settings that command reads (internal/cli/root.go, internal/settings/bind.go). A command accepts the settings it reads — no more, no less — so the flag list of mcpx run and the flag list of mcpx ls are different lists, on purpose. Flags for internals are marked [plumbing] in help rather than hidden.

Three consequences worth knowing:

• The full inventory is generated, not listed here. Every setting, its flag, its environment variable, its default and its scope are in configuration.md, which a test keeps identical to the registry; the environment names are in environment.md. mcpx help <command> shows one command’s own flags; mcpx settings shows the resolved values and where each came from.
• Aliases are spellings of one setting. A setting may publish shorter aliases (--runtime for --script-runtime). Giving two spellings of the same setting on one command line is an error that names both — they are the same setting, and mcpx will not guess which value you meant.
• Flag names are derived, not chosen per setting. The flag is derived mechanically from the setting’s dotted path (daemon.leaseTTL becomes --daemon-lease-ttl), so the spelling in configuration.md is authoritative; do not guess a spelling the table does not show.

Where a value can come from at all — built-in default, config files, environment, presets, flags — and which source wins, is the precedence chain in configuration.md (“Where a value can come from”). This page only adds: a contradiction between sources that the chain cannot resolve is reported once, up front, with exit code 2, rather than by whichever command happens to read the value first.

CLI commands

The command table is generated, and this page does not copy it. Every command is declared once in Commands() (internal/cli/manual.go) — name, aliases, group, usage, detail, examples — and from that declaration come mcpx help, the man page, the shell completions, and the generated CLI commands table in parity.md, which lists each command beside the operation it reaches. A test (TestEveryDispatchedCommandIsDeclared) holds the declaration and the binary’s dispatch table equal, in both directions: no dispatched command is missing from the list, and nothing on the list fails to run. That parity is recent — serve, api, registry, adapter, openapi, man and completion were once dispatched but undeclared, and therefore invisible to help, the man page and completions; the test exists so that cannot happen silently again.

What prose can usefully add over the generated table is the grouping mcpx help presents, and what each group is for:

For any one command, mcpx help <command> is the reference: it is printed from the same declaration the table is generated from, so the two cannot disagree.

The compendium: structure and mapping

created:      2026-10-29T19:00:00-05:00
last-updated: 2026-10-29T19:00:00-05:00
increment:    1
status:       standard
tags:         area:docs, area:compendium
description:  what the compendium is, the chapters in order, which file is the
              source of each, and the rule that keeps a file in exactly one.

The compendium is level 3 of the book: the encyclopedia. Level 1 is the overview, level 2 is the guides, and level 3 is where “basically everything that is built can be described here in as much detail as you want”. It is deliberately not limited to mcpx: note 88 asks it to catalogue MCP servers, resources, indexes, URLs and projects as well (chapter 7).

This page is the structure. The per-file mapping is compendium.manifest.json, next to it, and a test keeps the two in step (see Keeping this true).

Approach: the docs are the book source

Approach C, as recommended on #1867 and not reopened here:

• Source root pkgs/mcpx/docs. Files render where they already are.
• Navigation is generated from compendium.manifest.json, not written by hand and not kept in a second tree.
• README.md stays a symlink to docs/story.md (git mode 120000), and the <!-- table-of-contents-marker --> stays where it is. The runbook’s check test -L README.md && readlink README.md keeps passing.
• One home per document. Other levels link to a chapter or excerpt it; they do not copy it. That rule is what makes a level-3 page safe to be as long as it needs to be.

Approaches A (move the files under a book directory) and B (one stub page per document) were rejected on #1867 for the reasons recorded there: A breaks every relative link, internal/settings/docs_test.go, and the symlink; B needs a stub per document plus a check that the stubs have not drifted, and breaks links a different way.

Chapters, in order

A chapter’s source is a file or a directory. When it is a directory, its README.md is the chapter index and the rest of the directory is the chapter’s pages; a generated navigation therefore has to accept a directory, which is the concrete requirement the three in-flight directories from the 2026-09-30 inventory turned into.

The migration mapping

Every one of the 96 markdown files under pkgs/mcpx at origin/main is in the manifest, with a chapter or an explicit reason not to have one. The 2026-09-30 inventory on #1867 covered 20-odd of them; the seven it never saw now land as:

Explicitly not compendium, and why

These are in the manifest with role: not-compendium, so the mapping is complete rather than merely plausible:

Four more are role: included: AGENTS.md (the agent instruction file, linked and included but chapterless, per #1867), docs/configuration.md and docs/parity.md (reference, #144, and level 2, #146 — the compendium links to them; internal/settings/docs_test.go reads configuration.md), and plugin/opencode/README.md (install, level 2, agent twin #120).

README.md is in the manifest as a symlink entry rather than a source, so the generator has an explicit instruction about it instead of a rule it has to remember.

The catalogue chapter

Structure only in this change; the entries are a follow-up so that this page can be reviewed as a structure rather than as a directory listing.

• Source docs/catalogue/, with a chapter README.md and one page per section: servers.md, registries.md, resources.md, urls.md, projects.md.
• Generated or written: C. A hand-written list says which servers, registries, resources, URLs and projects are in the catalogue and why; the facts per server (mcpx --json ls tool counts, mcpx types tool lists, mcpx --json registry search publisher and version) are captured into a committed snapshot by a refresh script. Nothing at docs build time starts a server or calls the network, because CI must not have to start seven MCP servers to render a page.
• First entries are the seven servers configured on this machine — codebase-memory, codedb, fff, fff-nix, fff-worktree, chrome-devtools (the session-mode case) and context7 — plus the official registry registry.modelcontextprotocol.io, the recorded rejection (HAPI), and the projects list from #1867. Scope beyond that machine is open question 5.

Approach A (hand-written entries only) and B (mirror mcpx registry search) stay rejected for the reasons on #1867; C is recorded here so the follow-up does not have to re-argue it.

Open questions on #1867, answered

1. Split story.md per entry, or one long page? Split, at build time, at section IDs (#151). One page with good anchors is readable, but the feature list is also what level-2 pages excerpt (#146-#148) and what the catalogue and the decision records link to by name; a stable page per entry gives those links a target that survives an edit elsewhere in the list. The split pages are generated and not committed, so story.md and the symlinked README.md stay one file on GitHub.
2. Move ASSESSMENT.md and OPENCODE-V2.md into docs/, or include them from the root? Move them into docs/. Both are chapter sources for chapter 8, both are linked by relative path from story.md and proposals.md, and a chapter whose sources live in two trees needs every link rewritten twice. AGENTS.md stays at the root: it is the agent instruction file and the name is the convention.
3. ideas.md: unpublished, raw, or an index of issues? Publish the index-of-issues version in the proposed chapter; keep ideas.md itself as raw intake and do not publish it. It says of itself that it anticipates becoming “an index of links” once issues exist, and they do.
4. Which “resources” and which “indexes” does note 88 mean? All of them, and the chapter separates them instead of choosing: resources.md covers MCP resources (the protocol feature, and what the configured servers actually expose) and reading material as its own section, while registries.md covers registries and the code indexes the configured servers maintain (fff, codedb, codebase-memory). A reader looking for either arrives at the same page.
5. Catalogue scope: this machine’s servers, or also the ones mcpx was tested against? This machine’s seven first, because each has a recorded reason to be configured. Servers mcpx was merely tested against (the Swagger petstore in OPENCODE-V2.md, io.github.microsoft/playwright-mcp in story.md) go in a clearly marked second section, since the reason they are listed is different: evidence, not configuration.
6. Do stale facts in living documents get fixed before the compendium publishes them? Yes, as a separate small fix, not inside this structure change: dependencies.md (“One.”), the story.md “Nix packaging” entry (vendorHash = null, “one third-party Go dependency”), and the missing nix/darwin-module.nix that ASSESSMENT.md points at. Publishing them is what turns a known staleness into a citable error. Tracked as its own follow-up, and deferred to #1907 if it is not picked up first.

Constraint this structure keeps

The one test that pins a doc path is internal/settings/docs_test.go, which reads ../../docs/configuration.md. Nothing here moves a file, so it is untouched. No relative link changes either: this change adds two files under docs/ and edits nothing else, which is also why the story.md links written relative to docs/ (../AGENTS.md, ../ASSESSMENT.md, ../OPENCODE-V2.md, ./release-runbook.md, ../scripts/stress.sh) keep resolving. When open question 2 is implemented and the two root documents move into docs/, those links change in the same pull request.

Keeping this true

internal/settings/compendium_test.go walks every markdown file under pkgs/mcpx and fails when:

• a file is not in the manifest at all (a new document must be placed, and the failure names it);
• a manifest path does not exist (a moved or deleted document leaves a chapter pointing at nothing);
• an entry’s chapter is not one of the chapters listed here;
• a chapter-source entry has no chapter, or a not-compendium entry has one without saying why.

That is the whole mechanism: adding a document to pkgs/mcpx is not finished until it has a chapter, or a reason for not having one.

Related: #1867 (this structure), #1907 (level-3 tracker), #117 (generator source root), #150/#151 (section IDs and split), #153 (chapters 8), #154/#1871 (chapter 9), #157 (level-1 overview), #144/#146-#148 (reference and level 2), #120 (agent twin), #24 (elicitation as a design).

Configuration

Every number in mcpx is a setting, including the ones nobody will ever change.

That sounds like an overreaction until you have hit the alternative. A constant written next to the code that needs it is fine right up to the day somebody’s proxy kills an idle event stream at thirty seconds, or their sandbox refuses to exec the running binary, or a tool legitimately takes a five-megabyte argument. At that point the only remedies are a patched binary or a fork, and both are absurd outcomes for a number that was chosen in five seconds and never revisited. Declaring it costs one line and removes that outcome entirely.

So the rule is: nothing is hardcoded. A value lives in internal/defaults/defaults.json as data, and – wherever a user could conceivably want it different – it is declared once in the settings registry, from which its configuration key, its environment variable, its command-line flag, its /v1 representation and its MCP tool are all derived. There is no second place to update, which is the point: the arrangement this replaced had four, and they drifted.

The handful of exceptions are permission bits. 0700 on the state directory and 0600 on the socket are not preferences. The socket grants the power to run tools as you; a configuration key that widens it would be a footgun with no legitimate use. They are in defaults.json as data so there is still one place to read them, and they are deliberately absent from the registry.

A guard test enforces this. It matches inline durations in both spellings gofmt produces, byte sizes written as shifts, bounds assigned to variables whose names say they are bounds, and permission literals, with an allowlist that carries a reason for each exemption. The version it replaced matched fixed strings and missed every duration gofmt had compacted into a function argument – nine of them, including the daemon’s shutdown grace and the event stream’s keepalive.

Where a value can come from

Lowest to highest:

1. default – internal/defaults/defaults.json, embedded in the binary.
2. file – every configuration file on the search path, ranked by distance, nearest highest. mcpx config --sources lists them.
3. env – MCPX_*. Every setting has one, derived from its path, whether or not anybody uses it.
4. flag – the command line.
5. runtime – an override set through PUT /v1/settings/{path} or mcpx settings set. Highest because it is the most recent statement of intent: somebody changed their mind while the thing was running, and having a flag from ten minutes ago win would be inexplicable.

mcpx settings get <path> prints the winning value, where it came from, and what it displaced. “Why is this not what my config says” is the most common configuration question there is, and the answer is always in that list.

The search path itself is decided before any of those layers exist, in two passes. The discovery pass walks the default locations, seeded by MCPX_PATHS_CONFIG / --paths-config, and reads only paths.config. The load pass resolves that list and loads everything on it, nearest last: a file’s paths.config governs the rest of the chain from that point, a null entry stands for the locations the default walk provided, and a list with no null replaces the farther remainder. A paths.config found only in the load pass is reported by mcpx config --sources, not applied, and a cycle is refused naming the path that closed it. MCPX_CONFIG bypasses both passes and loads exactly one file.

Two spellings of one setting at the same level is an error rather than a race: --log-level and --logging-level together, or two variables that mean the same thing with different values. The environment has no order, so there is genuinely nothing to prefer, and picking one silently is how a configuration becomes unexplainable.

Scope: who reads it

Every setting says which process acts on it. This exists because of a failure with no symptom.

A daemon is started once, in whatever environment it happened to have, and then serves every command for hours. A flag on one of those commands that governs something the daemon does was simply lost: accepted, validated, printed back, and then ignored, because the process that would act on it had read its configuration an hour earlier. Nothing anywhere said so.

• daemon – the pooled servers, the listener, the log the daemon writes. A client changes one by persisting it and restarting, or through mcpx settings set if the setting is hot.
• client – the CLI process itself: how it renders, how it finds a daemon, whether it may start one. Setting it on the daemon does nothing.
• call – meaningful per request. The CLI sends its effective value with every request in an X-Mcpx-Settings header, and the daemon honours it for that request only. This is what makes mcpx search --limit 3 work against a daemon that was started without it. Only call-scoped settings are honoured from that header: widening it would make a header a way for any client to reconfigure a shared daemon.
• plugin – read by the opencode plugin, which is neither. The plugin reads process.env directly, so the variable names are the contract between the two and a test pins them.

Hot: does it take effect now

A hot setting is read afresh every time it is used, so changing it at runtime works. A cold one was consumed once at startup – a listener address, a log file that is already open – and recording a change to it would do nothing. PUT /v1/settings/{path} says so rather than accepting a value that would be silently inert.

Reaching them

mcpx settings list resolves locally, which is what the client will use. --daemon asks the daemon what it resolved, which is what a daemon-scoped setting actually is. The two differing is information, not a bug: it is exactly the case that used to be invisible.

--persist runtime changes the running daemon and nothing on disk, which is what an experiment wants. project and user write the corresponding configuration file and apply at once where the setting allows it – a change written to a file but not applied would leave mcpx settings get answering with the old value, which reads as the write having failed.

Local-model controls by surface

These are independent controls, not one fleet-wide Qwen switch. In particular, parking hosted chat-model listings does not disable embeddings or an interpreter. The checked-in state below is from this repository’s main configuration, not a guarantee about a running process: nearer files, environment, flags and runtime overrides can change it. See #2218 for the remaining single-switch work.

For catalog embeddings, auto tries the configured embeddings.url remote endpoint, then a successfully loaded embeddings.wasmPath, then the subword engine. remote and wasm each fall back to subword on failure; local uses subword directly. A remote endpoint may itself be local (for example Ollama): the backend name does not say where the model runs. embeddings.model names the remote model, not a local download. These settings select an embedder; they do not switch semantic search itself off.

For prompt generation, prompt.sample: never prevents an unmatched-recipe request from asking a model by default; ask allows it. An explicit request provider or model, or a non-none model.provider, also opts in even when prompt.sample is never. model.provider selects the newer model layer (none, auto, sampling, plugin, openai, anthropic, or google), with model.baseURL and model.default for a configured endpoint and model. An OpenAI-compatible local endpoint can serve Qwen, but it must be configured separately. model.provider: none alone is not a universal veto: the legacy scripting provider can resolve an explicit request, environment or installed CLI when generation is allowed. The legacy repair.provider and repair.model keys in the fleet file are not registered settings in this version, so do not assume that block selects the effective provider. Per-request mcpx prompt --provider / --model can also select a provider. None of these controls constrain independent callers of external services.

Use mcpx settings get embeddings.backend --daemon, mcpx settings get prompt.sample --daemon, and mcpx settings get model.provider --daemon to inspect the daemon’s resolved settings; check mcpx config --sources and the daemon environment as well. Embedding backends are constructed when settings are installed, so verify the running daemon after changing configuration rather than assuming an existing index or embedder has switched. Model provider and prompt sampling settings are daemon-scoped and cold.

Servers

Servers are configuration too, and until now adding one meant an editor and a restart.

The entry is written to a configuration file and the daemon reloads, so the server is callable immediately and is still there tomorrow. A server whose process definition did not change keeps its running child: adding one server must not restart the rest, or a stateful server – a browser holding a session – loses it because a neighbour appeared.

The daemon also re-reads its configuration files when they change on disk, checked on the same tick that reaps idle instances (daemon.watchConfig). An edit by hand therefore takes effect within daemon.reapInterval without anything being restarted.

Making that work required changing what identifies a daemon. The socket used to be keyed to the contents of the config files, so that editing one got a fresh daemon rather than a stale one. A daemon that reloads changes the contents of the files it is keyed by, which moves its own key, which makes it unreachable by the client that just edited it – and hands the next command a different daemon that happens to match the new key with old servers loaded. That was observed: mcpx servers remove succeeded, the file was correct, and the next mcpx servers list showed the removed server. The key is now the file set, and staleness is handled where it belongs.

Hiding tools

tools (an allowlist) and excludeTools (a denylist) go in a server’s mcpx block, or in the top-level pool block to apply to every server. A hidden tool is left out of every listing – mcpx tools, generated types, search, the MCP pass-through – and a call to it by name is refused with 400.

{
  "pool": { "excludeTools": ["delete_*"] },
  "mcpServers": {
    "datadog": { "command": "mcp-remote", "args": ["..."], "mcpx": { "excludeTools": ["execute_*", "/^(update|upsert)_.*dashboard/"] } }
  }
}

Each entry is one of:

A pattern that cannot compile is a configuration error naming the field, not a rule that silently matches nothing.

Constraining calls by their arguments

Hiding decides by tool name: a tool is callable with any arguments or not at all. argumentRules decides by the call: a per-server map in the mcpx block – also allowed in the top-level pool block – whose keys are tool patterns matched exactly as tools/excludeTools match (exact name, glob, or /regexp/), and whose values are JSON Schema objects. A call is allowed only if its arguments validate against every rule whose key matches the tool. Pool rules and server rules add up, and so do rules from layered config files: rules only tighten, and a nearer file cannot loosen a farther one.

{
  "mcpServers": {
    "github": {
      "command": "...",
      "mcpx": {
        "argumentRules": {
          "create_repository": {
            "required": ["private", "organization"],
            "properties": {
              "private": { "const": true },
              "organization": { "pattern": "^(my-org|my-org-sandbox)$" }
            }
          },
          "/^(push_files|create_or_update_file|delete_file)$/": {
            "required": ["branch"],
            "properties": { "branch": { "not": { "enum": ["main", "master"] } } }
          },
          "*": {
            "properties": { "owner": { "pattern": "^(my-org|my-user)$" } }
          }
        }
      }
    }
  }
}

Per-argument rules are the same mechanism: a "*" key whose schema is a properties object constrains that argument on every tool that carries it, and leaves tools without the argument untouched.

A refused call is a 400, as a hidden tool is, before the server is started: the message names the argument path, the value sent, the constraint it broke, and where the rule came from (config file, server, key). Over the MCP pass-through the same refusal arrives as a tool result with isError: true. Listings advertise the tightened schema: the inputSchema shown by mcpx types, the generated client, search, and the pass-through’s tools/list is the upstream schema allOf every matching rule, so an agent sees private: true before it ever calls.

A rule whose key matches no tool on its server warns at load and on catalog changes – a server that renames a tool must not silently disable the rule that guarded it. A value that is not a valid schema, or a pattern the validator cannot compile (JSON Schema patterns are ECMA-262; lookahead and backreferences are unsupported), is a configuration error naming the server and key, like a bad tool pattern.

Two cautions, plainly:

• Server defaults are invisible. A rule constrains what is sent, not what the server fills in. If a constraint matters, list the argument in required – never rely on a server-side default to satisfy it.
• Free-form arguments cannot truly be constrained. A pattern over a query/jql/sql string matches text, not meaning. A tool whose danger lives in a free-form argument belongs in excludeTools, not in a rule.

extraIncludeTools takes the same entries and adds them to the allowlist instead of replacing it, so a server can widen a pool-wide tools by one tool without restating the rest:

{
  "pool": { "tools": ["get_*", "list_*", "search_*"] },
  "mcpServers": {
    "datadog": { "mcpx": { "extraIncludeTools": ["create_datadog_monitor"] } }
  }
}

With no tools anywhere, extraIncludeTools is the allowlist – it includes, as tools does, so everything it does not name is hidden.

excludeTools wins over both. A server’s own tools replaces the pool’s; extraIncludeTools and excludeTools from the pool and the server all apply, so a server that hides one more tool does not undo a pool-wide rule. A nearer config file’s pool.extraIncludeTools likewise adds to a farther one’s. An alias (aliasOf) filters independently of the server it shares a process with.

Names are the server’s own tool names, as mcpx tools prints them in its tool column, not the generated function names.

Some servers can filter on their side too – Datadog’s omit_tools URL parameter, GitHub’s GITHUB_READ_ONLY – which keeps the tool from ever reaching mcpx. Those are each server’s own convention; this one works for any server.

Write policy (policy.write)

A tool call is a write when its tool is not annotated readOnlyHint true, read with the specification’s defaults: an unannotated tool may write, and may be destructive. The daemon-wide setting policy.write (default ask) gates every such call, between resolving an instance and using it:

A server’s own writePolicy in its mcpx block overrides the daemon mode for that server alone:

{ "mcpServers": { "datadog": { "command": "...", "mcpx": { "writePolicy": "deny" } } } }

Under ask, a caller that cannot answer questions is refused, not waited out and not let through: the error says the policy is ask, that there is no question broker to answer it, and that setting policy.write to allow (or deny) is the escape. An unanswered or refused confirmation refuses the call too.

elicit.confirmDestructive is a floor on top of this, not an alternative to it: with it on, a destructive call asks even under allow – raised by the destructive confirmation itself, with its annotation-trust rules unchanged – and the floor never weakens a deny. Under ask the policy has already asked once, so no call is asked about twice.

This gate is an operator consent gate, not the autonomy dial (docs/decisions/0002-autonomy-dial.md): the dial bounds what mcpx does on its own, the write policy bounds what a caller may do to the outside world through it, and neither clamps the other.

Every setting

Everything between the markers below is generated from settings.Registry() by TestTheDocumentationListsEverySetting, which fails when it is stale:

go test ./internal/settings -run TestTheDocumentationListsEverySetting -update

It used to say it was generated while being written by hand, and it had drifted: two settings were missing an alias their flag really answers to. mcpx config --schema --plumbing prints the same inventory, and mcpx settings list prints it with the values that are actually in force.

Entries marked (plumbing) are internals. They work and they are supported, but there is no ordinary reason to change one, so they are kept out of ordinary help rather than hidden – a flag a user can find in the source and that --help denies exists is worse than a long list.

paths.configFile is the one setting a configuration file may not set: it decides which file is read, so it is accepted from the environment and from the global --config, which goes before the command.

plumbing.strictUnknownKeys governs keys no setting claims, and keys a server entry declares that mcpx does not know — type, alwaysAllow and the rest, which belong to the other hosts that read the same file. Those are recorded, reported by mcpx doctor, and refused only when this is on.

A key inside a server’s "mcpx" block is not governed by it and is always refused. That block is mcpx’s alone — nothing else writes into it — so a key it does not know is a typo or a name that no longer exists, not another host’s field. This is deliberately not a setting: it is how mcpx init wrote "mode": "session" into every new config for months without anyone noticing, and a switch to turn the report off would have kept it quiet.

A script whose first line names its interpreter (#!) runs under that interpreter, ahead of every setting below: a -S/--split-string payload is re-split with shell quoting rules (so -S sh -c "printf hello" keeps printf hello one argument; an unterminated quote fails the run), VAR=value assignments reach the child even when the value contains /, env -u/env -i apply (the child starts from the parent’s environment minus what they remove, or from an empty one), and env -C/env --chdir moves the run, beating script.cwd the way the interpreter choice beats script.runtime. An env option mcpx does not implement fails the run rather than being dropped. A dispatched run never inherits MCPX_CLIENT, MCPX_RUNTIME, MCPX_ENTRY or MCPX_DISPATCH from an outer run, and its notice names anything else it goes without (no generated client, no enforced permission profiles, skipped launcher phases).

artifacts

autonomy

autostart

catalog

completion

daemon

deps

diagnose

doctor

elicit

embeddings

events

exec

hooks

http

logging

logstore

mcp

model

output

paths

plugin

plumbing

policy

pool

preset

presets

prompt

proto

protoMessages

protoTasks

recipes

registry

repair

retention

script

search

serve

session

spec

stats

tasks

transport

upstream

Adapter declarations

An entry in a paths.adapters file names a program and the subcommands worth exposing. command is normally a binary on PATH; runtime makes it a script instead, and resolves the interpreter for you:

{ "adapters": [{
  "name": "reports", "command": "./tools/report.py", "runtime": "py",
  "tools": [{ "name": "daily", "params": [{ "name": "day", "required": true }] }]
}] }

runtime is bash, js, ts or py. bash resolves bash (then sh), py resolves python3 (then python), and js/ts use the same deno/bun/node order script.runtimeOrder chooses for mcpx exec. This is a separate resolver on purpose: script.runtime names the runtime mcpx itself executes generated scripts on, not the one a declaration asks for. A relative command resolves against the declaration’s dir, then PATH. Without runtime, nothing changes: command is looked up on PATH and exec’d directly. mcpx adapter check reports a missing interpreter or script.

mcpx catalog also ends with the recipe tools in tools/list: how many are exposed against the recipe budget, and which recipes were kept out by a name collision or the cap.

mcpx as a consumer

Sampling, elicitation and completion are things a server asks of its client. mcpx is a client to its upstream servers and a server to whatever drives it, so today it only passes them through. Are there cases where mcpx should initiate them itself?

— issue #41

Four, and they are not equally good. This is the record of which, why, and what was deliberately not built.

1. Deterministic schema-change diagnostics

The most valuable thing here needs no model at all, and that was the central finding of the issue. mcpx already knows every tool’s input schema. What it did not know was what those schemas used to be — internal/codegen could fingerprint a catalog and diff two of them, but nothing ever stored one, so every diff was against nothing and the question “when did this change” had no answer anywhere in the program.

So internal/diagnose keeps one. Each time the daemon reads schemas, it records every tool’s flattened shape and appends whatever differs to a per-tool change list in <state>/catalog-history.json. That file is the missing half. With it, a script that calls a tool with no arguments after that tool gained a required one is not a mystery; it is two facts mcpx is holding, put next to each other:

demo.echo: the argument object is no longer optional: message is required
           (schema changed 2026-09-20: `message` became required)
  you wrote:  await demo.echo()   (line 2)
  minimum:    await demo.echo({ message: "" })

Three decisions inside that are worth stating.

The scanner does not parse TypeScript. It looks for two identifiers, a dot and a parenthesis, and skips every construct that could hide one: strings, template literals, both comment forms. A call assembled dynamically is invisible to it, and that is the correct failure — a diagnostic about a call nobody wrote is worse than no diagnostic. It also stops at the first sign of not knowing: a spread in an argument object silences the missing-argument check entirely, because a spread can supply anything.

Only configured namespaces are diagnosed. console.log(x) and JSON.parse(s) are indistinguishable from tool calls at this level. Having an opinion about somebody else’s code is not this package’s business.

The issue’s example needed correcting. It reads:

demo.create_issue: argument 1 is now required (`options` became required).
  you wrote:  await demo.create_issue("title")
  minimum:    await demo.create_issue("title", {})

mcpx’s generated client does not take positional arguments. codegen binds every tool as fn(args?: {...}) — one object, optional exactly when the schema has no required properties. So the diagnostic mcpx can actually produce is “the argument object is no longer optional”, which is the same fact in the shape the generated code has. Anything else would be advice that does not compile.

The upstream half, diagnose.CallError, runs in Registry.Call (internal/daemon/callerr.go), the one place a failed call passes on its way to every surface. The server’s error stays first and whole; the rendered diagnostic follows it, and /v1/call carries the same finding as data:

{ "error": "mcp error -32602: Invalid params\ndemo.create_issue: the call was rejected and repo is required but was not sent (schema changed 2026-09-30: `repo` was added and is required)\n  minimum:    await demo.create_issue({ repo: \"\", ... })", "diagnostics": [{ "kind": "invalid-params", "tool": "demo.create_issue", "field": "repo", "changed": { "when": "2026-09-30T…", "kind": "argument-added", "what": "`repo` was added and is required" }, "fix": "await demo.create_issue({ repo: \"\", ... })", "fatal": true }] }

So mcpx call prints it, mcpx --json call puts the document on stdout, a task’s result carries it, a script’s ToolError has .diagnostics, and mcpx_call shows the text. Data beside the prose, because an agent can act on field where it would have to parse a sentence.

Three conditions decide whether it runs, and each is there because of what it said without them. Only an answer from a server is explained: a timeout or a server that would not start never answered, so the arguments were not at fault. Not a code in -32000..-32099: mcpx’s own client reports a dropped connection as -32000 connection closed: unexpected EOF, and the text match read “unexpected” as “expected” — a crash was explained as a missing argument. And not a namespace whose schemas have not been read, where CallError said “no server is configured under this namespace” about a configured server; it used to answer that for any failure, before it looked at the code at all.

Not covered: mcpx_call from a client that can answer questions goes through CallAsk, which leases the pool itself; /v1/call/{server}/{tool} carries the text but not the field; and a server that reports bad arguments as a result with isError has made a successful call, so there is no failure to explain.

--diagnose-preflight is on by default on run and exec. The failure it catches surfaces otherwise as an error from a server, halfway through, after the side effects of every call before it.

2. Elicitation mcpx raises for itself

Two policies, both off by default, both landing on Registry.Call between resolving an instance and using it.

Disambiguation (elicit.disambiguate, never | ask). It asks only when the answer is genuinely open: the server is exclusive, so its instances are distinct things rather than copies; several are live; and the caller’s own scope key names none of them. When the caller already has an instance, the scope key is the answer and a question would be theatre. The form is an enum of the live keys plus “new”, each with what it is doing — holders, calls, idle time, pid — because a choice without that is not a choice.

Destructive confirmation (elicit.confirmDestructive, off). Before a call to a tool that may be destructive: annotated destructiveHint: true, or (the specification’s default) not annotated readOnlyHint: true or destructiveHint: false. This is the step a human-driven client has and a script does not.

The two disagree about what a silent deadline means, deliberately. An unanswered disambiguation takes elicit.disambiguateDefault, which is new — a caller that wanted a particular browser and did not say so gets a fresh one rather than somebody else’s. An unanswered confirmation refuses the call. There, doing nothing is safe; here, doing nothing is the destructive thing.

Routing needed no change in internal/elicit. A confirmation is a lone boolean called confirm, which Route already sends to a human because consent is not the agent’s to give; a disambiguation is an enum, which goes to the agent that raised the call. internal/elicit/policy.go adds only the constructors, whose job is to make it impossible to raise one of mcpx’s own questions without a default and a deadline.

The daemon had no access to settings before this — daemon.Options carries a config.Config and nothing else — so settings.Resolve folds the same configuration files and environment the CLI reads. Whether a destructive call is confirmed is not a question with two correct answers depending on which process asked.

Several daemons, the other disambiguation case in the issue, is not here. It belongs to the plugin: the question is which daemon serves a directory, and by the time mcpx is answering, that has been decided.

3. Recipes

A recipe is not a new artefact. It is a script already on the search path that declares its own holes:

// Close stale issues in a repository.
// @param repo:string        which repository, as owner/name
// @param days:number = 30   how old counts as stale

const found = await demo.search({ repo: @repo, olderThanDays: @days });

Declaration is a header comment because a comment survives every runtime, cannot affect execution, and is visible in the file somebody edits. References are @name, the spelling the launcher already uses for its own holes.

A recipe is also an MCP tool. The @param header is already a typed schema, so tools/list carries one tool per recipe, named recipe_<name>, with that schema and the summary as its description. Calling it runs the recipe through /v1/recipes/{name}/run – the same render, diagnostics and runner mcpx recipes run uses. Exposure is on by default; // @tool false in the header opts one out. The number exposed is capped (DefaultToolBudget, 25) so fifty saved scripts do not become fifty schemas in every host, and mcpx catalog ends with the count, the cap and any recipe kept out – a name another producer already claimed is reported there rather than silently dropped.

Values are substituted as JSON, never as text. A recipe runs with the user’s credentials; raw substitution would make every placeholder an injection site. A string arrives quoted, an object arrives as an object, and a recipe with an unfilled required hole is an invalid script — which is the right way round, because it cannot then be run by accident.

Matching is a score over four things the recipe already carries: its name, its summary, its placeholder names and the tools it calls. No model, no embedding, no index. The same request gives the same recipe every time, at no cost. Decide refuses to choose when the leader is not ahead of the runner-up by recipes.matchMargin (150%, half as much again), because running the wrong saved script is a side effect rather than a wrong answer.

JavaScript built-ins are excluded from the tool list. console.log counted as a tool makes every recipe match the word “log”.

Missing placeholders become one form with one deadline, not one question each: a person filling in four fields is doing one thing, and four deadlines are four chances for a run to die half-configured.

4. /prompt, which is POST /v1/intent

The name. POST /v1/prompt was taken, by the operation that renders an upstream server’s MCP prompt, and Go’s mux keys on method and path. Renaming somebody else’s operation to free a word was not worth it. The CLI command is mcpx prompt, which is what the issue asked for; the route is /v1/intent.

The order is recipes first, generation second, and generation is off by default (prompt.sample: never). The issue sequences sampling-backed generation last and conditions it on there being a caller that can answer sampling; most cannot, and a caller that cannot pays the entire deadline to find out. With it off, an unmatched request returns the ranked recipes and says so in one sentence. That is the honest default, and it is also the one that does not make mcpx prompt hang for ninety seconds on a machine with no answerer.

With it on, the request goes out as an ordinary MCP sampling request through the same broker that carries every other question — so the plugin, an agent watching mcpx elicit, and an MCP client that declared sampling all answer it without learning anything new. It is given the slice of the catalog the existing search ranked for this request, inside prompt.catalogBudget tokens, and nothing else. The whole reason mcpx is worth having is that tool schemas stay out of a model’s context; a generation request has to send some, so it sends as few as it can.

The generated script is validated with the step-1 diagnostics before anything runs, and returned rather than run unless autonomy: run is asked for.

Whatever is asked for, the daemon’s autonomy.max is the most it does: a request above it — in a body, the X-Mcpx-Settings header, the CLI’s --run, an MCP tool call or the plugin — is lowered to it, not refused, and the answer carries requested and clampedBy beside autonomy. The CLI prints requested run, clamped to propose by autonomy.max (...) on stderr. The same ceiling bounds repair.autonomy (whether a failed call carries diagnostics) and hooks.autonomy (whether configured script hooks run).

Running a script from the daemon

recipe_run and intent in run mode need to execute something, and the daemon has never run scripts. Server.execScript calls internal/runner directly, against the daemon’s own endpoint. This is a seam, not a design. POST /v1/exec has since landed, with its own options and permission model (internal/api/ops_exec.go, internal/daemon/routes_exec.go), but execScript (internal/daemon/consumer.go:517) has not yet been rerouted through it. It is one function, marked, for exactly that reason.

The concerns from the issue, and what was decided

Scope — “anything that makes mcpx call a model has to justify that it isn’t rebuilding the harness.” Three of the four things built here never call one. The fourth originally stopped there: option 3 from the issue, a configured provider with an API key, was not built, on the grounds that it is the one that makes mcpx an agent. That conclusion has since been reversed by the facts #1925 records: the 2026-07-28 MCP revision deprecates sampling (SEP-2577) and names integrating directly with provider APIs as the migration, and no opencode — the primary consumer — declares sampling at all. So a configured provider now exists, as one backend of the thin provider layer in internal/model: a Provider interface with a single Generate, reached only through the model.* settings, with model.provider defaulting to none — a user who configures nothing gets exactly the behaviour described above. Sampling through the caller survives as another backend of the same layer: it is mcpx asking the harness it already sits under, which remains right where a client declares it. What has not changed is the guard that made the original refusal coherent: no operation calls a model on a path where a deterministic answer exists, and a provider error returns the deterministic result plus a note that the model was unavailable. A Generate function is not an agent; the harness mcpx sits under still owns the loop, the tools and the session.

Trust — “generated code runs with the user’s credentials.” Return the script by default (prompt.autonomy: propose, one level of the dial in decisions/0002); run only on explicit request. Recipe values are JSON-encoded, so a recipe cannot be turned into an injection site by its arguments. A recipe name that would become a path is refused.

Latency and cost — “never sample on a path that doesn’t need it.” The deterministic diagnostics come first and answer the case the issue identified as the common one. Recipe matching is free and deterministic. Sampling happens on exactly one path, only when nothing matched, and only when it has been turned on.

Headless callers. Every question mcpx raises for itself carries a default and a deadline, and elicit.Ask exists so that forgetting either is not possible. The defaults differ by question, for the reasons above. A caller that gets no answer is told which question it raised, so it can look up what was asked rather than guessing.

Not built

• A language service. The issue is right that suggesting a fix to a script is LSP work rather than MCP completion, and right to keep the two apart. internal/diagnose is the part an LSP would need; the server itself is a separate piece of work and nothing here presumes its shape.
• Sampled rewrites of a diagnostic. When the caller is an agent it reads the error either way; the value is in the error being specific, not in a model rewording it. If a human-facing front end ever wants a proposed rewrite, diagnose.Diagnostic is already the structured input for one.
• Daemon disambiguation, as above: the plugin’s question, not mcpx’s.

Bugs found on the way

The schema cache (cacheVersion) is not invalidated when a cached entry gains a field. Adding Annotations to mcpclient.Tool parsed cleanly against an existing cache file and left it empty, which presented as the destructive-call policy silently never firing — the annotations were there upstream and absent from the cache nobody had reason to reread. The version is bumped, with a comment saying why; the shape of the trap is still there for the next field.

Running mcpx in a container

What Containerfile builds, what it deliberately does not, and what was measured along the way.

id:           running-mcpx-in-a-container
since:        pre-release
created:      2026-09-30T04:00:00-05:00
last-updated: 2026-10-30T06:40:00-05:00
status:       implemented

A starting point rather than a shipping image. The goal was the smallest thing that actually works – builds, runs, and can execute a script – so that the decisions that come next are made against something real instead of a design.

1. What it is

Three stages:

All three are pinned by tag and digest. The tag says what it is; the digest says which one. A tag moves, and a build that depends on when it ran is not a build.

The runtime stage adds ca-certificates, copies in bun and mcpx, drops to an unprivileged user, and sets ENTRYPOINT ["mcpx"]. It has no git; §3 says why that is not a loss.

The build context is the module directory, because the Containerfile copies go.mod and builds ./cmd/mcpx — both relative to pkgs/mcpx, not to the repository root:

cd pkgs/mcpx
docker build -f Containerfile -t mcpx .
docker run --rm mcpx --version
docker run --rm -v "$PWD/.mcpx.json:/work/.mcpx.json:ro" mcpx ls

2. The JavaScript runtime

The image ships bun. mcpx exec and mcpx run are the point of mcpx, and neither can do anything without a JavaScript runtime – runner.Detect returns no JavaScript runtime found and the command fails. An image that cannot run a script is an image that can only do the things a plain MCP client could already do.

Bun because it is the smallest of the three. Measured on this machine (linux/arm64, the binary inside each project’s own Debian image):

Smaller margins than the x86-64 figures usually quoted, but the same order.

runner.Resolve picks the first of script.runtimeOrder (by default deno, bun, node) on PATH, so an image with only bun would find bun anyway. MCPX_SCRIPT_RUNTIME=bun is set anyway, because relying on absence to select a default means adding a second runtime later silently changes which one runs. The setting is script.runtime (--script-runtime, script.runtime in config); naming a runtime the image does not contain is an error, not a fallback, so anyone who wants deno’s permission model has to add deno to the image.

That is the one real cost of choosing bun: bun has no permission model, so any script.permissions profile other than all is refused under it (see runtimes.md). Node enforces the readnet profile through --permission; deno enforces all of them. Inside a container that is a smaller gap than it is on a laptop, but it is a gap.

3. No git

The repo and worktree sharing scopes key server instances by the repository a call came from. They used to ask git, and the first version of this image installed git so they could: 105 MB, most of it perl.

They no longer ask git. mcpx reads .git itself – a port of git’s own discovery rules, compared against git rev-parse case by case in the test suite – and runs git only for the few layouts that port does not vouch for: a repository format newer than it knows, an extension it has not heard of, a config file it cannot parse. Without git those key by directory, and mcpx doctor says which file it could not read. The full record, every case and what was decided for it, is docs/git-discovery.md.

Taking git out cost nothing, because in this image it had not been working:

$ docker run --rm -v "$PWD:/work:ro" --entrypoint git mcpx:before -C /work/proj \
    rev-parse --git-common-dir
fatal: detected dubious ownership in repository at '/work/proj'
To add an exception for this directory, call:

	git config --global --add safe.directory /work/proj

A mounted checkout belongs to the host’s uid, the image runs as 1000, and git refuses a repository someone else owns. So with git installed, the repo and worktree scopes fell back to per-directory keys for every mounted checkout – the situation the old version of this section said git was there to prevent. Native discovery does not check ownership: safe.directory exists to stop git running configuration from a repository someone else controls, and discovery runs nothing.

What was verified in the image with no git on PATH, one daemon for the whole run, a real repository with a linked worktree (made with worktree.useRelativePaths, so its paths survive the mount) and a submodule, a bare repository, and a tmpfs mounted inside the checkout:

INSTANCE  CALLS  KEY
byrepo#2  4      repo:/work/proj/.git              proj, proj/sub, proj-wt/sub, and exec from proj-wt
byrepo#3  1      repo:/work/proj/.git/modules/mod  the submodule is its own repository
bytree#2  2      worktree:/work/proj               proj and proj/sub
bytree#3  2      worktree:/work/proj-wt            proj-wt/sub and exec
bytree#4  1      worktree:/work/proj/mod
bytree#5  1      cwd:/work/bare.git                no worktree: core.bare is true in /work/bare.git/config
bytree#6  1      cwd:/work/proj/mnt/inner          discovery stops at the mount point /work/proj/mnt
tiny#1    1      global

The old image’s git, told to trust the mount with safe.directory=*, gave the same answers for the submodule, the bare repository and the mount – and refused the other three directories with unknown repository extension found: relativeworktrees, because Debian’s git is 2.39 and the checkout was made by 2.55. With GIT_DISCOVERY_ACROSS_FILESYSTEM=1 in the container’s environment the mounted directory keys to worktree:/work/proj, as it would in git. mcpx ls listed all three namespaces, call and exec (on bun) reached each, and mcpx doctor -v from the linked worktree said:

ok    git   repo /work/proj/.git, worktree /work/proj-wt; resolved natively; no git on PATH,
            which only matters for a repository native discovery cannot read

A repository that does need git is visible, not silent: the key falls back to the directory, the daemon logs why once, and doctor turns the line into a warning that says to install git. Adding it back is one package in the apt-get install line.

4. Static linking: the policy

CGO_ENABLED is unset in an ordinary Go build, which means enabled on a native build, and two packages change behaviour when it is:

• internal/logging/trace.go:9 imports os/user, which under cgo calls getpwuid_r through libc rather than parsing /etc/passwd;
• net is reachable from most of the tree, and under cgo its resolver is getaddrinfo, which honours nsswitch.conf.

Policy (#1987): the artifacts that ship as a bare mcpx binary ship static. The trade-off is the two bullets above — pure-Go os/user does not consult NSS and the pure-Go resolver ignores nsswitch.conf — and it is accepted for these artifacts because neither behaviour is load-bearing for a daemon/CLI whose state lives in its own directories, while a binary that only runs beside one exact glibc (or one Nix store path) fails everywhere else silently.

Measured, not assumed (the CGO_ENABLED=0 build, before it became the default):

$ docker build -f Containerfile --build-arg CGO_ENABLED=0 -t mcpx:cgo0 .
$ docker run --rm --entrypoint sh mcpx:cgo0 -c 'ldd /usr/local/bin/mcpx'
	not a dynamic executable
$ docker run --rm mcpx:cgo0 --version
mcpx 0.1.0
$ docker run --rm -v "$PWD:/work:ro" mcpx:cgo0 \
    exec 'const r = await tiny.echo({ message: "cgo0" }); console.log(String(r));'
you said: cgo0

Same size to the byte-ish – 14 811 298 against 14 811 401 – so the pure-Go os/user and resolver cost nothing here.

Tier-2 container legs

Tier 2 (#1987) means: runs nightly and on pushes to main that touch pkgs/mcpx, never gates a PR. The legs are scripts/tier2-containers.sh, run by the mcpx tier-2 containers workflow; each leg asserts the surface its image can actually support, including mcpx’s own clean refusal where a surface is absent:

Deferred, with the reason recorded on #1987: an alpine + nodejs exec leg. Verified 2026-10-30, mcpx’s node path dies with ERR_NO_TYPESCRIPT under Alpine’s nodejs build, so the leg would enshrine a failure instead of catching one; it joins the matrix when the node invocation works on a musl node. Tier 3 (fedora, flatpak, silverblue/kinoite hosts, the Windows port) is unchanged: separate issues when a user appears.

5. Where the size goes

Measured on linux/arm64 with the digests pinned in Containerfile, before and after §3, both built on the same machine:

The 413 MB this document used to quote is the last row, which is the uncompressed layers plus the compressed blobs they were unpacked from. The layers are what a running container occupies; the compressed size is what a pull transfers.

git costing more than bun was not expected: with --no-install-recommends already set, the weight is perl, which Debian’s git depends on outright. What remains of the apt layer is ca-certificates and the openssl it pulls in, for the registry. perl-base is still in the image – it is part of Debian’s essential set, in the base layer – but nothing in mcpx uses it.

6. What was deliberately left out

• No per-PR container gate. The tier-2 legs (§4) run nightly and on pushes to main; building images on every PR is a cost the tier system deliberately does not pay.
• No full e2e suite inside an image. The e2e suite spawns daemons and binds unix sockets; the tier-2 legs assert surfaces, which is a different, smaller harness.
• No shipped scratch or distroless variant. They exist as tier-2 test legs; a shipped minimal image still drops exec (no static JS runtime exists to put in it), which is a product decision nobody has taken.
• Not wired into package.nix. The Nix build and the container build are two ways to produce the same binary; making one depend on the other buys nothing yet.

7. What to watch

The .dockerignore excludes result – a dangling symlink into the Nix store that does not exist inside the build. If a nix build has been run in the tree and this file is removed, the container build will fail on a broken symlink, and the error will not say why.

Declared but never read

A knob that does nothing is worse than one that does not exist. A missing flag fails loudly at the prompt; a flag that parses, appears in --help, appears in mcpx config --schema and then changes nothing costs somebody an afternoon before they conclude the feature is broken rather than the wiring.

This has shipped repeatedly. --typecheck on exec (#66). Five exec flags at once (#75). MCP sampling, declared and unreachable (#39). The opencode plugin’s permission.ask hook. Every one of them was found by a person trying the thing, which is the expensive way.

This is the audit that went looking for the rest of them, and the guard that makes the next one a test failure.

What the audit was

The settings registry had 149 entries when this audit ran; it has 164 today, and the counts below are the ones the audit measured, not current figures. Each one derives a config key, an MCPX_ variable and a flag from a single declaration, which is the whole argument for the registry existing. The question is therefore not “is this path string mentioned anywhere” but “does anything read the resolved value”.

Those are not the same question, and the difference is where the interesting half of the findings came from. pool.max was read from a config file, through config.Config.Pool, which the JSON decoder fills. MCPX_POOL_MAX and --pool-max landed in the resolved Set, and nothing on that path looked at them. Grepping for "pool.max" finds a match in internal/defaults (an error label) and calls it live. A user who set the variable, saw nothing change, moved it into their config file and saw it work would reasonably conclude the variable name was wrong rather than that the layer was. That is fixed now: config.ApplyPoolSettings (internal/config/poolsettings.go:36) copies every layer of the resolved Set into Config.Pool, and a runtime change through settings set reloads the pools (internal/daemon/routes_settings.go:268), so the change reaches pools that are already running.

So the audit looked for one specific shape: the path handed to an accessor on a resolved Set — set.Int("pool.max"), a.Settings().Bool(...), cs.Duration(...). That is the only reader in the program that has seen the file, the variable and the flag together. os.Getenv has seen one layer. A config struct field has seen one. A hand-written flag variable has seen one.

It found 54, in a registry of 149.

Verdicts

Counts: 24 wired, 3 deleted, 9 legitimately external (the plugin — seven are named below, and two more were reclassified while the audit ran; there are twelve plugin-scoped settings today), 1 left open, 2 added (the inverse bug), plus 15 settings the naive path-string grep called dead that the accessor scan cleared.

Wired

Deleted

Legitimately external

plugin.bin, plugin.binArgs, plugin.backend, plugin.toolTiming, plugin.env, plugin.instructions, plugin.tools are read by the TypeScript plugin through process.env, by the exact name the registry derives (mcpx-session.ts:180-191, mcpx/daemon.ts:848-850). Verified, and now guarded: a plugin-scoped setting whose variable appears nowhere in plugin/**/*.ts fails the test. README mentions do not count — a README can describe a knob nobody wired.

Left open

paths.config was circular by construction (#5): the config search path is what produces the settings, so the settings cannot decide it. It is no longer left open. config.ResolveChainFrom resolves the chain in two passes (issue #1842): a discovery pass over the default locations, seeded by MCPX_PATHS_CONFIG / --paths-config, reads only paths.config; the load pass then resolves that list, nearest last. A paths.config found in pass 2 that differs is reported by mcpx config --sources, not applied, and a cycle is refused naming the path that closed it. MCPX_CONFIG bypasses both passes.

The inverse bug

The plugin honoured four variables the registry had never heard of, which breaks the registry’s promise from the other side: mcpx settings was supposed to answer “what will the plugin do” without anybody reading TypeScript. plugin.remember and plugin.annotate are now declared. MCPX_PLUGIN_HEADLESS and MCPX_PLUGIN_DAEMON_TOOLS were allowlisted at the time, because their defaults are computed at boot — whether the plugin is on the main thread, whether discovery was ambiguous — so a declared value would be right in one of the two realms the plugin runs in and wrong in the other. They are declared now, as plugin.headless and plugin.daemonTools (internal/settings/plugin.go:105, :114), with the default auto: auto is the declared name for “work it out from the process shape”, which is the thing a number could not express.

The guard

internal/settings/consumed_test.go, three tests.

TestEverySettingIsReadSomewhere scans every non-test .go file outside internal/settings for each path used as the argument to a Set accessor. A plugin-scoped setting is checked differently: its EnvName() must appear in the plugin’s own TypeScript sources.

The obvious alternative was a ReadBy: "daemon" field on Setting. It was rejected, and the reason is worth stating because it generalises: that note lives in the same struct literal as the declaration. Whoever writes the declaration writes the note in the same keystroke, believing both, and nothing ever checks the second half. It would have been a second declaration, subject to exactly the bug it was meant to catch. A scan asks the code, which cannot be optimistic.

The narrowness is the other half of the design. A scan for the path string anywhere would have passed pool.max, script.prefix, logging.include and every other half-wired setting in the table above — the ones that were hardest to find and most confusing to hit. Requiring the accessor is requiring the whole promise, because the Set is the only reader that has all three layers.

TestNoHandRolledSettingEnv closes the other direction: os.Getenv of a variable the registry owns is how a setting becomes env-only. Three entries on its allowlist, each because the read genuinely happens before a Set exists. (Since replaced by TestNoUndeclaredEnvRead, which walks the syntax tree and also refuses a variable nothing declares – see docs/environment.md.)

TestThePluginReadsNoUndeclaredSetting closes the third: a variable the plugin honours that no setting declares.

Every allowlist entry carries its reason in the map. There is deliberately no way to silence any of the three in bulk.

The other three layers

The same shape exists wherever something is declared in one file and consumed in another.

/v1 parameters

161 declared across 60 operations at the time of the audit; 162 across 60 today. The parity tests in internal/api already bind every route to an op and every op to an MCP tool — but they match paths, not parameters, so a parameter can be declared, published in InputSchema(), rendered into the OpenAPI document, marshalled into the body by a generated MCP tool, decoded by the handler and discarded, with every test green.

• POST /v1/diagnose, session — decoded into the request struct and never referenced. Its own description said “for the record”, and no record was written. Fixed: a diagnose.run line now goes to the durable log, with the session on it, which is what makes it joinable to the run it was diagnosing.
• GET /v1/log?chain= — Chain(id, limitPerLevel) takes no filters, so level, event, server, tool, session, trace, grep, since and until were all accepted and dropped. The result is the whole trace tree at every level, which reads as “that trace touched everything” rather than as a filter that did not run. Fixed: the combination is refused, in /v1 and in mcpx log. The e2e test for chains was itself passing --level debug.
• GET /v1/stats?top= is inert for four of seven dimensions and GET /v1/events?since= loses to Last-Event-ID; both say so in their own descriptions. Not defects.

CLI flags

No flag declared with fs.String/fs.Bool in internal/cli is wholly unread. The defects are of two kinds.

The first is structural and was fixed: Schema.Bind registers every setting whose Commands list contains the command or is empty, so a command accepts flags it never reads. --budget and --bias were offered on types, ls and search; --catalog-instructions on ls and catalog. Narrowed.

The second is a class this audit did not resolve and is reported rather than fixed, because each case is a judgement about the command rather than a wiring error:

• logging.* declares no Commands, so --log-level, --logging-format, --include, --keep and the rotation flags bind on every command. Only daemon and run/exec read them. mcpx log --log-level debug parses and does nothing. Narrowing logging.* would be correct and is a larger change than this one.
• mcpx ls -v --json silently drops the per-instance detail -v asks for; the JSON branch returns before it is used. mcpx doctor -v --json likewise.
• mcpx stats errors --by slowest reports errors: a positional dimension wins over --by through firstSet, silently.
• mcpx stats --opencode returns before --server, --tool, --session and --log-dir are used.
• mcpx log --format json --fields ts,msg ignores --format: --fields bypasses the writer entirely.
• mcpx log --reverse --follow reverses the backlog and not the tail; followLog resets q.Reverse unconditionally.
• mcpx prompt --mode script --run becomes run; mcpx recipes run x --mode run --script becomes script mode. Both overwrite the flag they were given.
• mcpx servers add x --header K=V -- cmd accepts the headers and drops them: they are read only inside the --url branch.
• mcpx api tools --methods all does nothing without --spec: six flags are read only inside if *specFlag != "".
• mcpx elicit show --session S accepts --session and --audience on every subcommand and reads them in two.
• parseFlags leaks into the package-level flagSetCommand map when fs.Parse fails, and the map is unguarded while lazyMCP builds on a request goroutine.

MCP capabilities

• logging — declared to every pre-2026-07-28 client. The capability means “this server sends log messages to the client”; mcpx emits no notifications/message anywhere in the package. Withdrawn. The logging/setLevel method is still answered, because refusing would make a well-behaved client that asked anyway treat the whole connection as degraded.
• resources.subscribe, *.listChanged — gated on s.Notify != nil, a property of the server. Delivery is a property of the connection, and every HTTP connection the daemon serves is built with a nil send function. So every client over the transport the daemon actually mounts was told to subscribe, had its subscriptions/listen acknowledged, and then heard nothing for ever. Now gated on Conn.canPush().
• *.listChanged additionally requires a stream the client opened, and only 2026-07-28 has subscriptions/listen. An older client was told it would receive notifications it has no mechanism to receive. Now gated on the revision too.
• subscriptionId in _meta — 2026-07-28 makes it mandatory on every notification delivered on a listen stream (2026-07-28.ts:121-132). mcpx sets it on the acknowledgement only. A client with two subscriptions cannot correlate anything. Since fixed: every notification on a listen stream carries it (internal/mcpserver/listen.go:94), pinned by internal/e2e/subscribe_test.go and internal/e2e/protomsg_test.go.
• prompts and resources are declared unconditionally; both schemas say “present if the server offers any”. The handlers return [] correctly, so this is over-declaration rather than a lie. Not fixed — reported.
• events.MCPNotification translates ElicitCompleted to notifications/elicitation/complete, and nothing can reach that branch: ListenFilter has no field for it, correctly, since 2026-07-28 dropped it.

One thing the audit found that it did not fix

Setting.EnvName() derived MCPX_PROTO_ASK_T_T_L from proto.askTTL, and --proto-ask-t-t-l with it. The camel-case splitter did not know that TTL is one word. proto.stateTTL, proto.askTTL, daemon.leaseTTL and proto.serveMCP were affected.

Fixed since: a run of capitals is now one word (MCPX_PROTO_ASK_TTL, --proto-serve-mcp), and TestNoDeclaredNameHasASingleLetterWord fails if a derived flag or variable contains a one-letter word, which is what the next acronym split into letters would look like.

Dependencies

Everything mcpx needs, and why. Nothing here is incidental — if it is listed, something breaks without it.

Go libraries

Nine, and pkgs/mcpx/package.nix states the trade for each one beside the vendorHash that pays for them.

The three charmbracelet modules are one decision, not three: they cost about 1.2 MB in the stripped binary and replace raw terminal handling – escape sequences, resize, a redraw loop – which is the kind of code that is never finished and never correct on every terminal.

Everything else – the MCP client, the JSON-RPC framing, the process pools, the JSON Schema to TypeScript compiler, the HTTP API and the CLI – is standard library, and that is worth keeping.

Why this driver

modernc.org/sqlite is a pure-Go translation of SQLite rather than a binding. The usual choice, mattn/go-sqlite3, is cgo, and cgo would mean:

• a C toolchain required to build, which the Nix derivation would have to carry;
• cross-compilation broken, so no building a Linux binary from a Mac;
• CGO_ENABLED=0 builds failing outright.

That is a large bill for a database that is only ever an index. The JSONL files remain the source of truth: the index can be deleted at any time and is rebuilt on the next query. Paying in build complexity for something reconstructible was the wrong trade.

The cost of the pure-Go driver is a slower build and a larger binary. Both are acceptable; neither affects anyone running mcpx.

What this means for the build

• vendorHash is pinned in pkgs/mcpx/package.nix and must be updated when the dependency changes.
• The build still needs no network beyond the vendor fetch, and still needs no C toolchain.

The standard library packages doing real work: net/http (daemon and client), encoding/json (everything), os/exec + syscall (child processes and process groups), sync (pools), path/filepath (path identity), text/tabwriter (human output).

If a dependency is ever added, it should be for something genuinely hard — a tokeniser, a SQLite driver — and the trade should be stated here.

External programs

git is optional. mcpx finds a repository by reading .git itself – a port of git’s discovery rules, docs/git-discovery.md – and runs git rev-parse --path-format=absolute --git-common-dir --show-toplevel only for a layout that port does not vouch for, such as a repository format newer than it knows. That needs git 2.31 (March 2021); an older git’s answer is refused rather than misread. Nothing else about git is used — no fetching, no writing, no config.

A JavaScript runtime is chosen at first use: deno, then bun, then node. Override with --runtime or the runtime config key. Deno runs with --no-check; the generated client is machine-written and a type error in the agent’s own script surfaces at runtime anyway.

MCP servers are whatever the config names. mcpx spawns them with the given command, args, env and cwd, or connects over Streamable HTTP for url servers. Their own configuration is exactly those argv and environment entries — MCP has no separate configuration channel.

Network

The daemon binds two listeners, both local: a unix socket, and 127.0.0.1 on an OS-assigned ephemeral port. Generated script clients prefer the socket — Deno fetches over it with a custom HTTP client and Bun with a fetch option (internal/codegen/emit.go) — and fall back to the TCP port where a runtime cannot address a socket (Node’s fetch cannot, without undici). Neither listener is reachable off the machine; the tailnet identity transport (#1967) is the separate, authenticated exception, and it is opt-in.

Outbound traffic happens only when a configured server is a url server, or when a script makes its own requests.

Nix packaging

pkgs/mcpx/package.nix wraps the binary with git, deno, bun-bin and nodejs suffixed onto PATH, so behaviour does not depend on the calling shell. git is in that list because repo and worktree scopes are silently weaker without it — that was a real gap, found by asking this question.

The unit suites run in the build sandbox. The end-to-end suite spawns JavaScript runtimes and binds unix sockets, so it runs outside with go test ./....

Elicitation: a design

id:           elicitation-a-design
since:        pre-release
created:      2026-09-28T18:00:00-05:00
last-updated: 2026-09-28T18:00:00-05:00
status:       partial
tags:         area:protocol, area:integration
description:  how a server asks a question, and how the answer gets back
              through a CLI, a REST call, a script, an MCP host or a plugin.
note:         largely shipped, and differently in places

This was written before the feature existed, and the feature has since shipped – not always in the shape proposed here. It is kept as the design record, because the reasoning is still the reasoning. What actually ships is in docs/parity.md (the elicit_* rows) and docs/consumer.md; the authority is internal/elicit/, internal/cli/elicit.go and the three /v1/elicit routes in internal/daemon/server.go:424-426.

Where this document and the code disagree, the code is right. The disagreements worth knowing before you read on:

1. What elicitation actually is

Every other MCP method runs client → server. Elicitation runs the other way: a server asks the client a question in the middle of handling a tool call, and waits for an answer before finishing.

mcpx ──── tools/call ────────────────▶ server
mcpx ◀─── elicitation/create ──────── server     "which account?"
mcpx ──── {action:"accept", ...} ────▶ server
mcpx ◀─── the tool result ──────────── server

Two modes:

Three answers, and the distinction matters:

• accept — approved, with content matching the schema
• decline — explicitly refused. The server should offer an alternative.
• cancel — dismissed without choosing. The server may ask again later.

Collapsing decline and cancel is the obvious mistake. A server that treats “not now” as “never” stops offering something the user wanted.

Two eras, and mcpx is in the older one

This is bigger than elicitation, and correcting it is a prerequisite.

The spec divides implementations into two eras:

The current version is 2026-07-28. It is not a draft.

The compatibility matrix is unforgiving. A modern client against a legacy server fails. A legacy client against a modern server fails. Only a dual-era implementation bridges them, and it must implement both.

mcpx was legacy on both sides when this was written: its client sent initialize with ProtocolVersion = "2025-06-18", and its server answered initialize. It is dual-era now – the client offers 2025-11-25 (internal/mcpclient/client.go:22) and probes modern with server/discover first, and the server serves both eras.

And its server lies. negotiate() echoes whatever version the client asked for:

$ printf '{"jsonrpc":"2.0","id":1,"method":"initialize",
           "params":{"protocolVersion":"2026-07-28"}}\n' | mcpx serve
  we claimed: 2026-07-28
$ ... server/discover
  -32601 no method server/discover

A modern client is told “yes, I speak 2026-07-28”, and then finds no server/discover and no _meta handling. The spec says an unsupported version MUST get an UnsupportedProtocolVersionError (-32022) listing what is actually supported. This was a second live bug, independent of elicitation. It is fixed: negotiate echoes a version only when it is both supported and non-modern, and otherwise answers Latest (internal/mcpserver/server.go:1092-1095); server/discover is implemented (server.go:535) and -32022 exists (server.go:327).

Elicitation in each era

The delivery mechanism differs, which is why the era question comes first.

• Legacy: a genuine mid-flight request. The server sends elicitation/create while tools/call is still open, and waits.
• Modern: a retry. The call returns an InputRequiredResult carrying inputRequests, the call ends, and the client re-sends the original request with inputResponses attached.

The modern shape is dramatically easier for mcpx, because nothing stays open: an invocation can return and a person can answer an hour later. The legacy shape is what every server that exists today actually speaks.

So the broker below is designed around the modern semantics – a question is state with a deadline – and the legacy path is implemented by holding the call open and feeding it from the same broker. Both are needed. One shape of storage, two shapes of wire.

2. What is in the way today

recvLoop silently drops server-initiated requests

internal/mcpclient/client.go:

var resp rpcResponse
if err := json.Unmarshal(raw, &resp); err != nil { continue }
if resp.ID == nil { continue }       // notification
ch, ok := c.pending[*resp.ID]        // ← a request has an ID too
if ok { ch <- &resp }                // ← no match, frame discarded

A server→client request has both an id and a method. It unmarshals cleanly, finds no pending entry, and is dropped. The server then waits forever, the call hits pool.callTimeout, and the error says “timed out” — which is true and useless.

This was a live bug, not only a missing feature, and it has been fixed: recvLoop delegates to dispatch, which looks for a method as well as an id and routes the frame to handleServerRequest (internal/mcpclient/client.go:404-421).

initialize does not declare the capability

It did not, when this was written. mcpx advertised tools, resources, prompts, and a well-behaved server checking for elicitation would not send one – protection by silence, which is luck rather than design. The client now declares elicitation (with form, and url when a handler is set), roots and sampling (internal/mcpclient/modern.go:71-84, wired in at client.go:315).

Nothing owns “a question awaiting an answer”

Every existing mcpx state is either in-process (a lease) or durable and append-only (the log). A pending elicitation is neither: it outlives a process and it is mutated once.

3. The shape: a broker

One new component. internal/elicit.

type Request struct {
    ID        string            // elc-<16 hex>
    Trace     string            // the call that triggered it
    Parent    string            // that call's own parent
    Session   string            // who owns it
    Server    string            // which server is asking
    Tool      string            // during which tool call
    Mode      string            // form | url
    Message   string            // why, in words
    Schema    json.RawMessage   // form mode
    URL       string            // url mode
    Created   time.Time
    ExpiresAt time.Time         // Created + TTL
    State     string            // pending | answered | expired | abandoned
}

type Answer struct {
    ID      string
    Action  string            // accept | decline | cancel
    Content map[string]any    // accept, form mode only
    By      string            // which surface answered
    At      time.Time
}

Stored in the existing SQLite index beside records, in two tables. It is already there, already rotated, already queryable, and a pending question is exactly the kind of thing somebody will later want to ask mcpx log sql about.

The broker is one object with four operations:

Proposed as four operations; what shipped is seven, in internal/elicit/elicit.go:

OpenRequest(r Request) (Request, error)        // register; fills id, mode, TTL
Await(ctx, id) (Answer, error)                 // block until answered or expired
Respond(a Answer) error                        // from any surface
Get(id) (Request, bool, error)                 // the question
Lookup(id) (Answer, bool, error)               // its answer, once it has one
Pending(f Filter) ([]Request, error)           // what is outstanding
Close() error

Await takes no timeout: the deadline rides on the Request, so one question cannot be awaited with two different lifetimes.

Await blocks on a channel when the answerer is in-process, and polls the table when it is not. Polling is acceptable here because the interval that matters is human — a 250 ms poll against a question a person answers in twenty seconds is not a cost anyone can measure.

Time to live

Every request carries one. The default is elicit.ttl, 120 s, in internal/defaults/defaults.json (defaults.ElicitTTL). It is not a registry setting and not per-server overridable: OpenRequest (internal/elicit/elicit.go:206) and the daemon’s hooks use the constant unconditionally. Making it a setting is unfinished work, not a decision.

On expiry the broker answers cancel on the requester’s behalf, because that is what expiry means: dismissed without an explicit choice. Answering decline would tell the server the user said no, which is a different and wrong thing.

The TTL is also the backpressure. Without it a stuck server accumulates questions nobody will ever see, and the table becomes a graveyard.

4. The policy layer: answering without a human

A CLI invocation frequently has no human attached. Guessing is unacceptable; failing every time is unusable. So the broker consults a policy first, and only asks a human if the policy abstains.

Not built. None of elicit.mode, elicit.ttl as a setting, or elicit.rules is in the registry, and MCPX_ASSUME_YES does not exist. The policy that shipped is elicit.Route (internal/elicit/elicit.go:491), which chooses an audience rather than matching rules, together with the settings elicit.disambiguate, elicit.disambiguateDefault, elicit.confirmDestructive and elicit.askTimeout. The block below is the design, kept for the reasoning.

{
  "elicit": {
    "mode": "ask", // ask | auto | decline | error
    "ttl": "120s",
    "rules": [
      { "match": { "server": "github", "field": "username" }, "answer": "octocat" },
      { "match": { "mode": "url" }, "action": "decline", "because": "no browser in CI" },
      { "match": { "field": "confirm" }, "action": "accept", "when": "MCPX_ASSUME_YES=1" },
    ],
  },
}

The four modes:

• ask (default, interactive) — a human is expected
• auto — rules only; anything unmatched is cancel. This is the CI mode.
• decline — refuse everything, politely. For a sandbox that should never be asked.
• error — fail the call outright, so a script that did not expect a question does not silently get a cancelled one

Rules are matched before a human is ever asked, and every match is logged with the rule that fired. A policy nobody can audit is a policy nobody should trust.

5. Every surface

The same broker, six front doors. The rule throughout: an unanswered question is a first-class result, not an error.

5.1 CLI — the exchange you described

A call that elicits does not hang. It returns a document and a non-zero exit code reserved for this case (75, EX_TEMPFAIL, which is what it is).

$ mcpx call github.create_issue '{"title":"x"}'
{
  "status": "input-required",
  "elicitation": {
    "id": "elc-9f2c1a84bb0e7d31",
    "trace": "cal-d13e4c64102e9113",
    "session": "s87630-989154000",
    "server": "github",
    "mode": "form",
    "message": "Which repository should this issue go in?",
    "requestedSchema": {
      "type": "object",
      "properties": { "repo": { "type": "string", "description": "owner/name" } },
      "required": ["repo"]
    },
    "expiresAt": "2026-09-28T18:02:00Z",
    "ttlSeconds": 120,
    "respondWith": "mcpx elicit answer elc-9f2c1a84bb0e7d31 '{\"repo\":\"me/thing\"}'"
  }
}
$ echo $?
75

What shipped (#286) carries the same information in a different shape:

$ mcpx call ask.need_repo; echo $?
mcpx: ask.need_repo is waiting for input and nothing here can answer it.

  asks     Which repository should this go in?
  schema   {"properties":{"repo":{"description":"owner/name","type":"string"}},"required":["repo"],"type":"object"}
  expires  2026-09-30T22:31:37-05:00 (2m0s from now)
  answer   mcpx elicit answer elc-93e18b28a5a3c1f5 '{"repo":"..."}'
           mcpx elicit decline elc-93e18b28a5a3c1f5 | mcpx elicit cancel elc-93e18b28a5a3c1f5

The call keeps running until it is answered or expires; collect its result with: mcpx task result tsk-06654ccc9f064a5c
75
$ mcpx elicit answer elc-93e18b28a5a3c1f5 '{"repo":"me/thing"}'
$ mcpx task result tsk-06654ccc9f064a5c      # the call's real result

--json puts {"inputRequired": {callId, server, tool, questions[], text}} on stdout. A script under mcpx exec or mcpx run stops at the call that asked and exits 75 with the same message, even if it catches ToolError: the generated client sees the daemon’s 202 and exits rather than throwing.

Two limits. A daemon running inside the command (daemon.inline) stops with it, so the call cannot outlive the exit and the message says so. And when other calls share the server’s instance a question cannot be tied to one call for certain; it is still reported, marked ambiguous, because waiting out the TTL and exiting 0 was the bug.

respondWith is there because the alternative is the caller assembling it from three fields, and they will get it wrong once and then copy it forever.

$ mcpx elicit answer elc-9f2c1a84bb0e7d31 '{"repo":"me/thing"}'
$ mcpx elicit decline elc-9f2c...      # explicitly no
$ mcpx elicit cancel  elc-9f2c...      # dismissed
$ mcpx elicit list                     # what is outstanding, with time left
$ mcpx elicit watch                    # follow, for a terminal left open

Under the retry model, answering re-drives the original call automatically and the result lands in the log; mcpx elicit result <id> fetches it. Under the bidirectional model the original invocation is still blocked and simply proceeds.

A flag for the common case, where the caller is a person who will wait. Not built – mcpx call takes only -session and -raw, and --elicit=prompt is rejected as an undefined flag:

$ mcpx call --elicit=prompt github.create_issue '{...}'   # NOT BUILT
Which repository should this issue go in?
  repo (owner/name): me/thing

--elicit takes prompt | return | auto | decline | error, defaulting to prompt on a terminal and return otherwise. That default is the whole ergonomic story: interactive use just works, scripted use gets a document.

5.2 Scripts

A script is the one place where blocking is natural, because a script already awaits.

const issue = await tools.github.create_issue({ title: "x" });

By default the runtime answers from policy or cancels, and the call returns whatever the server does with that. To participate – not built: no onElicit and no ask are emitted into the script’s globals (internal/codegen/emit.go):

onElicit(async (q) => {
  // NOT BUILT
  if (q.mode === "url") return { action: "decline" };
  if (q.schema.properties.repo) return { action: "accept", content: { repo: "me/thing" } };
  return { action: "cancel" };
});

And for a script run on a terminal, ask(q) would prompt. The handler is registered rather than passed per call, because the question arrives from inside a call the script did not know would ask.

5.3 REST and OpenAPI

HTTP has a status code for exactly this, and it is not 400.

POST /v1/call/github/create_issue
→ 202 Accepted          # built only with X-Mcpx-Input: report, as {"inputRequired": {...}}; no Location/Retry-After
  Location: /v1/elicit/elc-9f2c1a84bb0e7d31
  Retry-After: 120

  { "status": "input-required", "elicitation": { ... } }

POST /v1/elicit/elc-9f2c.../accept   {"content":{...}}   # also /decline, /cancel
GET  /v1/elicit                       list
GET  /v1/elicit/elc-9f2c...           one, with time remaining

202 is right: the request was understood and accepted, and completion is pending. A 400 would say the caller made a mistake, which they did not.

The OpenAPI document gains a 202 response on every tool path and an Elicitation schema component. Both are generated, so they cannot drift. Neither is built: no operation declares a 202, and there is no Elicitation component in internal/api/openapi.go. What shipped instead is the MCP-side input_required result (internal/mcpserver/ask.go).

5.4 mcpx as an MCP server — the pass-through

This is the interesting one, and the reason the whole design is worth building. A question from a server three layers down has to reach the agent at the top.

agent ──▶ mcpx (MCP server) ──▶ mcpx daemon ──▶ github server
                                                      │
agent ◀── elicitation/create ◀── broker ◀────── "which repo?"

mcpx declares elicitation in its own initialize capabilities only if its client did. Capability negotiation has to be honest in both directions, or mcpx promises something it cannot deliver and the failure surfaces at the worst moment.

Then:

• Client supports elicitation → forward it, rewriting the message to name the real originator: “github (via mcpx) asks: which repository?”. The agent must know which server is asking; that is a spec requirement and also just decent.
• Client does not → fall back to policy, then to returning input-required in the tool result text so the agent can call mcpx_elicit_answer itself.

That fallback means an agent can answer a question with no client support at all, which matters because most MCP hosts do not implement elicitation yet.

Two new tools on the MCP surface:

• mcpx_elicit_list — what is waiting, with schemas and deadlines
• mcpx_elicit_answer — answer one

5.4a Who is the question for: the agent or the person?

The spec does not have a field for this, and deliberately so. From the Python SDK’s own words: “If the client is an agent, it might decide how to handle the elicitation – either by asking the user or automatically generating a response.” The decision is the client’s, not the server’s.

So mcpx needs a routing policy, and the useful thing is that the elicitation itself carries enough to route on:

The last row is the one that matters. A model asked “which repository?” with no way to know will produce a plausible name. The default for anything the agent cannot verify must be decline, not guess, and the skill in §5.7 exists mostly to say so.

A server may hint through _meta – io.mcpx/audience: "user" – and mcpx should honour a hint toward the human and ignore one toward the agent, because a server pushing a question past a person is exactly the direction that needs resisting.

In the plugin this becomes concrete: notify puts it to the agent, ask puts it to the person, and the routing policy decides which when the mode is auto. A question routed to the agent that the agent declines is re-raised to the person rather than failing – that escalation is the behaviour somebody would expect and would otherwise have to build by hand.

5.5 The opencode plugin

The plugin is where this becomes genuinely good, because opencode has a real user and a real UI.

"tool.execute.after": async (input, output) => {
  const pending = await pendingFor(input.sessionID)
  if (!pending.length) return
  output.output += "\n\n" + renderElicitation(pending[0])
}

Three levels, opt-in as everything else in that plugin is. Not built: MCPX_PLUGIN_ELICIT is not a variable the registry derives or the plugin reads, and there is no --plugin-elicit.

1. MCPX_PLUGIN_ELICIT=notify — a pending question is appended to the tool result, so the agent sees it and can answer via a tool. No UI needed.
2. MCPX_PLUGIN_ELICIT=ask — the plugin uses opencode’s own permission mechanism (ask({ permission, metadata })) to put the question to the user. This is the real prize: a genuine dialog, in the harness the person is already looking at.
3. MCPX_PLUGIN_ELICIT=auto — policy only.

The session id the plugin already injects is what makes this work. A question raised by a call from session X is offered to session X and to nobody else. No new plumbing; the existing injection is exactly the binding the spec requires between an elicitation and a user identity.

5.6 TUI

Not built – nothing in internal/tui/ mentions elicitation.

A seventh view, and a badge in the header when something is pending — because the one thing worse than a question nobody answers is a question nobody knows was asked.

Form mode renders the schema as fields. URL mode shows the URL and offers to open it. a accepts, d declines, c cancels, enter opens the detail.

The header badge is deliberately loud: ● 1 question in the accent colour.

5.7 Skills

Not built – there is no mcpx-elicitation skill in plugin/opencode/skills/.

mcpx-elicitation, loaded on demand, would cover: what input-required means, that decline and cancel are different, how to answer from a tool, and the one thing an agent gets wrong — inventing a value rather than declining. A model asked “which repository?” with no way to know will happily guess. The skill’s job is to say: if you do not know, decline and explain why.

6. What it unlocks

Elicitation is not only a feature. It is the missing half of four things mcpx already has.

Third-party authorisation flows

I overstated this in the first draft. Two different things share the word OAuth:

1. MCP’s own authorization spec – how a client authenticates to a remote MCP server over HTTP. That is a separate document, separate machinery (OAuth 2.1, resource metadata, token handling), and elicitation does not provide it. It remains a genuine gap.
2. A server sending its user through someone else’s authorisation flow – “connect your GitHub account”. That is url-mode elicitation, and it does fall out of this design.

The second is common and currently impossible. The first is unaffected. The line in OPENCODE-V2.md should be split accordingly rather than crossed off.

Write operations in OpenAPI and CLI adapters

Both currently default to read-only, because a specification describes what a service can do rather than what you meant to allow. With elicitation there is a middle setting: expose writes, and elicit a confirmation before each one.

{ "methods": ["all"], "confirm": ["POST", "DELETE"] }

That is strictly better than the two options available now, which are “no writes” and “all writes, no questions asked”.

Credentials at the moment of need

mcpx registry add currently reports which variables a server requires and leaves them empty, because inventing a secret is wrong. With elicitation the server can ask for it on first use, and the answer can go to a keychain rather than a config file. The current behaviour is the best available without elicitation; this is better.

Disambiguation instead of guessing

“Three repositories match, which did you mean?” is the single most common thing a tool cannot currently do. Today it either guesses or fails. Neither is what a person would do.

And two things it unlocks that are not about servers at all

mcpx can elicit on its own behalf. mcpx doctor finding an unconfigured server could ask rather than report. mcpx registry add could ask for the secrets it currently lists. The broker does not care whether the asker is an upstream server or mcpx itself, and building it only for pass-through would leave that on the table.

Long-running approvals become possible. With a TTL measured in minutes and a durable store, “this deploy needs a second pair of eyes” is expressible: a question raised by CI, answered by a person from a terminal or the TUI, and the call resumes. That is a different product feature that falls out of the same machinery.

6a. How the answer travels: four mechanisms, not one

The re-exec shape in §5.1 is right for one case and wrong as the only option. There are four ways an answer can reach the broker, and each is best somewhere.

The daemon already owns a unix socket and a loopback port. A long-lived client – the TUI, the plugin, a mcpx elicit watch left running – should subscribe rather than poll:

GET /v1/events                    → server-sent events, carrying elicit.* kinds
                                    (GET /v1/elicit/subscribe was proposed and not built;
                                     mcpx elicit watch polls, internal/cli/elicit.go:164)

That removes the polling in §3 for every case that matters, and polling survives only as the fallback for a process that cannot hold a connection.

The defaults follow from the table:

• terminal → prompt, no re-exec, no state to reconcile
• non-terminal → return the document, expect mcpx elicit answer
• TUI, plugin → subscribe
• REST caller → the HTTP endpoints, which they are already speaking

Re-exec is the conventional shape because it is the only one that works when the asking process is gone, and that is the case a CLI has to handle. It is not the best shape when the process is still there.

6b. Continuity across the re-exec

A re-exec means a new process, and the question is whether anything is lost.

Nothing needs to be, because session identity already lives in the environment rather than the process. MCPX_SESSION_ID is injected by the harness; a second invocation in the same shell carries the same value and therefore leases the same pooled server.

What the audit trail needs, and what the design should record:

elicit.open      trace=cal-d13e… elicit=elc-9f2c… session=s876… pid=41201
elicit.answered  elicit=elc-9f2c… action=accept by=cli
                 session=s876… pid=41533 answeredAfterMs=18420
elicit.resumed   trace=cal-a77b… parent=cal-d13e… elicit=elc-9f2c…

Three things fall out of that. The pid changes and is recorded on both sides, so “who answered this” is answerable. The session is the same, so mcpx log --chain walks from the resumed call back through the elicitation to the original call. And answeredAfterMs is the metric worth having: it is the human latency, and it is the number that tells you whether a TTL is set sensibly.

If the session id is absent – a bare shell, no harness – the broker binds the question to the config fingerprint and the working directory instead, and says so in the record. Refusing to work without a session would make the feature unusable from a plain terminal, which is where people debug.

7. Cost, and what could go wrong

Roughly 1,200 lines, in five pieces. The broker and its two tables. The recvLoop fix plus a bidirectional path. Policy evaluation. Six surface adaptations, most of them under fifty lines each. The TUI view.

Three things I would expect to go wrong:

Deadlock under the bidirectional model. A call holds a lease while waiting for an answer; the answer arrives through a surface that needs the same pool. Mitigated by the TTL, but the retry model avoids it entirely — which is the strongest argument for preferring it.

Questions nobody sees. A CLI invocation that returns input-required into a script that ignores exit codes produces a question that expires unanswered, and the user sees only a mysterious cancellation. The TUI badge and mcpx elicit list are the mitigation; so would be a --elicit=error, which would make not expecting a question a loud failure rather than a quiet one. Neither the badge nor the flag is built.

Rule-based auto-answers drifting into dishonesty. A rule that answers “yes” to everything is a policy that lies to a server about a user’s consent. Logging every rule that fires is the minimum; I would also make auto mode refuse to match a rule whose match is empty, so there is no “match everything” shorthand.

8. The explainer

Everything mcpx does today assumes the conversation goes one way. You ask a server to do something; it does it; you read the answer. Every part of mcpx — the CLI, the scripts, the REST endpoints, the MCP server, the TUI — is shaped by that assumption.

Elicitation breaks it. It lets a server stop halfway through a job and ask a question: which repository did you mean? are you sure you want to delete this? I need you to log in — here is the link. The server cannot continue until somebody answers.

That is awkward for mcpx specifically, because mcpx is usually invoked by something that cannot answer. A shell script has no opinion about which repository. A cron job cannot log in. A model can answer, but it will happily invent a repository name it has no way to know, which is worse than not answering at all.

So the design turns a blocking question into a piece of state that anything can answer, later. The question gets an identity, a deadline and a home in the existing database. The tool call stops and says “I need input, here is what and here is the ticket”. Anyone holding that ticket — a person at a terminal, a script that knew this might happen, an agent through a tool, a dialog in the editor — can supply the answer, and the call resumes.

Three consequences are worth stating plainly.

The answer does not have to come from whoever asked. CI can raise a question a human answers from a laptop twenty minutes later. That is not a special feature; it falls out of the question being state rather than a blocked function call.

“No” and “not now” stay different. The spec separates decline from cancel, and it matters: a server told “no” should offer an alternative, and a server told “not now” should ask again later. Collapsing them — which is the tempting simplification — makes tools worse in a way nobody traces back to this decision.

Not answering is a legitimate outcome. A deadline expires, the question becomes a cancellation, the server is told honestly that nobody chose. The failure mode to avoid is a system that waits forever, or one that invents an answer to avoid waiting.

The reason to build it is not the feature itself. It is that four things mcpx already does are currently half-finished for want of a way to ask a question. OAuth is elicitation. Safe write access is elicitation plus a confirmation. Credentials-on-first-use is elicitation. Disambiguation is elicitation. Each of those is presently either missing or solved by refusing to do the risky thing, and they all become available from one piece of machinery.

The catch worth knowing when this was written – since fixed: mcpx’s receive loop treated every inbound frame as a reply to something it sent. A server that asks a question gets silence, waits, and eventually times out — and the error mcpx reports is “the call timed out”, which is true, useless, and points at entirely the wrong thing. That is worth fixing whether or not the rest of this is ever built.

The script environment

Settings are what a person tells mcpx. This page is the other direction: what mcpx, and the opencode plugin, tell a program they start.

A script reads its session from here. The generated client finds the daemon from here – the endpoint, the socket, whether the daemon can see this filesystem. An mcpx command run inside a script, or inside a shell the editor opened, learns which session it belongs to from here, which is what lets a session-scoped server give each agent its own browser instead of sharing one. It is an interface with as many consumers as the settings have.

Until #172 it was declared nowhere. The only list was the code that happened to set each name, spread across five packages and a TypeScript file, and the documentation had already drifted from it: it said the plugin sets MCPX_SESSION and MCPX_CALL. The plugin sets MCPX_SESSION_ID and MCPX_CALL_ID; MCPX_SESSION is a different variable, set by mcpx for its own scripts; and MCPX_CALL has never existed. Two variables, one renamed in somebody’s head, is exactly the drift a hand-written list produces.

How it is kept true

The table below is generated from settings.ScriptEnv() in internal/settings/scriptenv.go, and tests hold that table to the code:

• Everything set is declared, by the right setter. The Go sources are walked as syntax – a map key, an assignment to an index, a KEY=VALUE string, os.Setenv – and the plugin’s put(e, "MCPX_...") calls are read, and every name found must be in the table with the part of mcpx that set it listed. A setter the table names that sets nothing fails too.
• Everything read is declared. A lookup of an MCPX_ variable anywhere outside internal/settings must be either a setting read through the resolved settings, a variable in this table, or one of four lookups on an allowlist that carries the reason for each – three happen before any settings exist, the fourth where there is no App to ask. An entry nothing needs fails the test. A variable the registry owns may not be read by name even when it is also here, because that would ignore the config file and the flag.
• The “read by” column is checked. If it says the generated client reads a variable, the generated TypeScript does; if the plugin reads one, the column says so.
• This page is current. The test regenerates the table and fails when it differs.

This table is what mcpx adds, not all a child gets

Every one of these is added to the environment mcpx itself was started with. A child gets the parent’s environment entire, and then these on top — unless its shebang replaces part of it: env -i starts the child from an empty environment, and env -u NAME removes just that name (both then get these on top). Both the dispatched path and the JavaScript path apply what the shebang asked for:

• internal/runner/runner.go:359 — cmd.Env = append(os.Environ(), …), every script the runner starts
• internal/adapter/adapter.go:239 — cmd.Env = os.Environ()
• internal/mcpclient/stdio.go:66 — env = append(env, os.Environ()...), under InheritEnv, for every stdio MCP server the pool starts

So a script also sees SSH_AUTH_SOCK, GITHUB_TOKEN, AWS_*, and whatever else was in the shell that started the daemon. PATH is inherited rather than constructed, which means a daemon started from a shell with an unusual PATH passes it on.

script.permissions does not change this. It sandboxes the filesystem and the network through the runtime’s own flags; there is no allowlist or denylist for the environment, and nothing here is filtered.

This is worth knowing before putting a secret in the environment of a shell you then run mcpx serve from. It is stated rather than fixed because the alternative — an allowlist — would break every server that expects its own API key to arrive this way, which is most of them.

Configuration is not here

A variable here is a fact about one run – which session, which daemon, which file – handed from a parent to a child. A knob is a setting, with a configuration key, a flag, a /v1/settings row and an MCP tool; those are in configuration.md. Two names are both: MCPX_LOG_LEVEL and MCPX_DAEMON_ENDPOINT are written for a child, and a child that is mcpx reads each as the setting it names.

Some variables are read by mcpx and are neither: which configuration file to load (MCPX_CONFIG, the setting paths.configFile) and where the state lives (MCPX_STATE_DIR, MCPX_CACHE_DIR) are needed before there is a configuration to resolve settings from. They are settings, marked as such, and read by name for that reason.

The variables

Examples

Four scripts you can run as they are. Each one calls the same deterministic fixture server, prints something short, and has its output checked into examples/ beside it. go test ./examples/ runs every script and compares stdout with that file, so an example that stops being true fails the build instead of sitting here looking plausible.

They are deliberately small. tools is on globalThis, so none of them imports anything, and the first one is barely longer than the command that runs it.

Run them from pkgs/mcpx. The first run writes mcpx-client.ts and its declarations beside the script, which is how mcpx run works for any file; the .gitignore in that directory keeps them out of git.

Set up the demo server first

Every script calls the demo namespace, which is not a public server: it is the deterministic fixture in internal/testsupport/fakemcp, and outside the test harness nothing configures it for you. From a clean checkout, build the fixture and mcpx itself, then give mcpx a config that maps demo to the fixture — the same arrangement examples/examples_test.go builds for itself:

cd pkgs/mcpx
go build -o /tmp/mcpx-bin/mcpx ./cmd/mcpx
go build -o /tmp/mcpx-bin/fakemcp ./internal/testsupport/fakemcp
cat > /tmp/mcpx-bin/demo.json <<'JSON'
{
  "mcpServers": {
    "demo": { "command": "/tmp/mcpx-bin/fakemcp" }
  }
}
JSON
export MCPX_CONFIG=/tmp/mcpx-bin/demo.json
export PATH="/tmp/mcpx-bin:$PATH"

MCPX_CONFIG is how the mcpx run commands below pick that config up. With it set, the first example prints exactly what the page shows; without it, the same command fails, because no server answers to demo.

Call one tool

The whole shape: top-level await, one argument object, print the result. demo.echo answers with a text block, which arrives as a string.

// Call one tool and print what it returns.
//
// Nothing is imported: `tools` is already on globalThis.

const echoed = await tools.demo.echo({ message: "hello from a script" });

console.log("demo.echo:", String(echoed));

mcpx run examples/call-a-tool.ts

demo.echo: hello from a script

Find a tool from inside the script

search() and describe() read the generated client, so looking something up costs no round trip to the server. This one lists the namespace, reads one tool’s signature, then calls two tools — one returning text, one returning structuredContent, which arrives already parsed.

// Find out what a namespace offers from inside the script, then call two of
// the tools it lists.
//
// `search()` and `describe()` read the generated client, so they cost no
// round trip to the server.

console.log("tools:", Object.keys(tools.demo).join(", "));
console.log(describe("demo.echo").trim());

const echoed = await tools.demo.echo({ message: "two tools" });
const structured = await tools.demo.structured();

console.log("echo:", String(echoed));
console.log("structured:", JSON.stringify(structured));

mcpx run examples/discover.ts

tools: boom, chatty, echo, fancy_name, open, slow, state, structured, wipe
demo.echo({ message })
      Echo a message back.
echo: two tools
structured: {"n":42}

State that survives between calls

open records a value in the server process and state reads it back. The daemon keeps one process for the session, so a later call sees what an earlier one did — no local variable involved. The script prints only whether its own two values are there, because the full list also holds whatever an earlier run recorded.

log() is on globalThis too, and writes to the durable log on stderr. The expected output below is stdout, which is what the test compares.

// `open` records a value in the server process and `state` reads it back, so
// a later call in the same script can see what an earlier one did.
//
// log() writes to the durable log on stderr; console.log is the script's
// stdout, which is what the expected output below holds.

log("recording two values");

console.log(String(await tools.demo.open({ value: "alpha" })));
console.log(String(await tools.demo.open({ value: "beta" })));

const state = await tools.demo.state();

console.log("alpha recorded:", state.seen.includes("alpha"));
console.log("beta recorded:", state.seen.includes("beta"));

mcpx run examples/stateful.ts

opened alpha
opened beta
alpha recorded: true
beta recorded: true

A recipe with parameters

The header declares the holes and the body uses @name, which is the whole recipe convention. mcpx run refuses a file like this — it cannot fill the holes — so it is saved and run with values instead. times has a default and is not passed here.

// Echo a message a few times through the demo server.
//
// The header declares the holes; `mcpx recipes run` fills them. A plain
// `mcpx run` refuses this file, because @message would reach the runtime
// unfilled.
//
// @param message:string   what to echo
// @param times:number = 2   how many times

for (let i = 0; i < @times; i++) {
  console.log(String(await tools.demo.echo({ message: @message })));
}

mcpx recipes save recipe-echo examples/recipe-echo.ts
mcpx recipes run recipe-echo message="piped through a recipe"

The mcpx: recipe recipe-echo line goes to stderr; the two echoed lines are stdout:

piped through a recipe
piped through a recipe

Every one of these is executed by go test ./... on each change, against the same fixture server, so the output above is what the scripts print today rather than what they printed when the page was written. For why the fixture is a fake and not a real server, see the FAQ.

exec and artifacts

A script produced a screenshot. Who gets it, and what does it cost them?

The thing that was wrong

mcpx exec ran the script in the CLI process. The CLI generated the client, spawned deno, and the script called back into the daemon over its socket. That is the right arrangement for a person at a terminal — the script owns stdout, reads real standard input, and a relative path in it means what it means on the command line.

It is the only arrangement, and that was the problem. Two callers could not use it at all:

• The opencode plugin holds a unix socket and nothing else. It has no mcpx binary to spawn. It could list tools, call one, read the log — and could not run a script, which is the thing mcpx exists for.
• A daemon on another machine could not be asked to run one. The servers are over there; the script ran over here and reached across the network for every single call.

So POST /v1/exec: the daemon runs the script. The generated client it writes points at the daemon’s own socket, so the calls that used to cross a network now cross a socket, and a caller with no binary has one request to make.

The refactor that made that safe is internal/execsvc. Two implementations of “run a script” would be two sets of bugs and a script that behaves differently depending on who asked — which is exactly what this whole feature is trying to stop. There is one.

Why the CLI still builds its own runner options

execsvc.Run is the wire entry point: everything arrives as ExecOptions and nothing is inherited from a terminal that is not there.

execsvc.RunWith takes runner options the caller assembled. The CLI uses it, because mcpx run genuinely has more knobs than /v1/exec does — launcher templates, five injection phases, --keep, a typecheck mode, placeholder files — and flattening all of that into the wire type would make the wire type a mirror of one command’s flag list.

What must not be duplicated is everything after the process starts: which frames are produced, how artifacts are reconciled, when media is intercepted, how delivery is applied. That is all in RunWith, and it is the same code for both. Hooks the caller already set are chained rather than replaced, so the CLI keeps rendering logs to a terminal while the service collects the same records for the result.

Where a script runs

exec.where is auto, local or remote, spelled --local and --remote at the command line.

Auto runs locally when the daemon is on this machine and on the daemon when it is not. That is the rule that makes the common case right without anyone choosing: a person gets a terminal-shaped run, and a configured remote endpoint gets a remote one, because running locally against a remote daemon means every call crosses the network and every file the script writes lands on the wrong side.

--local against a remote endpoint is refused rather than attempted. It does work, in the sense that the script runs and the calls succeed; it just quietly produces a different artifact story, and saying so beats a subtly different result.

A remote run sends the script’s text, not its path. A path would mean the daemon’s filesystem, and somebody typing mcpx run ./report.ts --remote means the file in front of them. The consequence is that relative imports do not survive the trip: the daemon writes the text to its own disk, and a sibling module is not beside it. --export does survive, because the launcher imports the written file and calls the named export there.

Every flag that shapes the program travels with it: --env, --typecheck, --launcher/--no-launcher, --allow-repeat, --no-capture-console, --export, and the five phases (--before, --prefix, --suffix, --on-success, --on-error). The CLI resolves them – reading any file a phase or launcher names on its side – and sends source, so the daemon runs the program that would have run locally. Until #192 the remote path sent five of these and silently dropped the rest; TestEveryExecFlagChangesSomething now runs every row both ways.

ExecOptions

One flat object that grows, rather than a new endpoint per capability. This is step 7 of the issue and it is the right shape: the caller declares what it can receive, the script declares what it produced, mcpx handles delivery.

type ExecOptions = {
  runtime?: "auto" | "deno" | "bun" | "node";
  timeout?: string;
  permissions?: string;
  placeholders?: Record<string, unknown>;
  session?: string;
  cwd?: string;
  env?: Record<string, string>;
  stdin?: string;
  output?: "text" | "structured" | "stream";
  capabilities?: string[];
  artifacts?: {
    delivery?: "reference" | "inline" | "stream";
    maxBytes?: number;
    sharedFs?: string;
    dir?: string;
  };
  task?: { ttl: number };
  ns?: string[];
  args?: string[];
  export?: string;
  typecheck?: "off" | "on" | "strict";
  launcher?: string;
  launcherName?: string; // template text, or "none"
  allowRepeat?: string[];
  captureConsole?: boolean;
  phases?: { before?: string[]; prefix?: string[]; onSuccess?: string[]; onError?: string[]; suffix?: string[] };
};

cwd, env and stdin are the caller’s context, not the daemon’s. A remote daemon has a different working directory and a different environment, and a script that reads either should see the one belonging to whoever asked. A local caller passes its own, which is how the two cases stay identical.

Three fields are not in the issue’s list. ns and args are there because mcpx exec --ns and mcpx run script a b already exist, and an option the CLI has and /v1 does not is a parity hole — the one thing this repository checks for automatically. dir sits beside sharedFs because they are different statements: sharedFs is “I can see your disk”, dir is “put them here for me”. They happen to be implemented the same way when the caller is local, and they are not the same claim.

task reuses internal/tasks unchanged. A long exec with artifacts is a task whose result holds references, which already fits tasks/result.

Output shapes

Three renderings of one run.

• text — the CLI default. stdout is the script’s answer and a person reading it wants it unadorned. It goes to the terminal as it is produced, not collected and printed at the end; a long run that printed as it went must keep doing so.
• structured — the /v1 and MCP default. One document: {result, emits[], logs[], stdout, artifacts[], exitCode, durationMs, error?}. A caller over HTTP wants fields, not text it has to scrape.
• stream — frames as they happen. SSE by default because it is plain HTTP and a browser consumes it with no code; NDJSON on Accept: application/x-ndjson, because a program with a JSON decoder should not have to strip data: off every line first.

result is the script’s stdout parsed when stdout is JSON. That rule is inherited from mcpx --json run rather than invented, so the two agree.

The frame order, and why it is the order

start{runId}
hook{phase:"before",...}       (one per before hook, in declaration order)
log | emit | stdout | call{server,tool,argsHash,durationMs,ok,error?,destructiveHint?}   (interleaved, as they happen)
artifact{id,name,mime,size,sha256,uri}
hook{phase:"onSuccess"|"onError",...}
result | error
hook{phase:"suffix",...}       (one per suffix hook, either path)
end{exitCode,durationMs}
---- only for delivery:"stream" ----
artifact.chunk{id,seq,data}
artifact.end{id}

A call frame records one tool call the script made while it ran: the server and tool, a hash of the arguments (never the arguments – a stream is a thing other people read), how long the call took, whether it succeeded, and the tool’s destructiveHint when its annotations declare one. Call frames appear on runs the daemon itself executes, whose call path can reach the run’s stream; a run whose calls arrive at a daemon that is not executing it has no stream there to join.

Hook frames sit where the hook ran, so the answer a consumer reads is the final one: an onSuccess/onError hook frame precedes the result/error frame it may have replaced (its frame carries the original when it changed the value), and a suffix hook frame follows the outcome, before end. A replaced error produces no error frame at all.

Artifact metadata comes before end; artifact bodies come strictly after it. That is the whole point of the design, and it is step 5 of the issue: a streaming consumer reads the emits and the return value, decides it does not need the 4 MB video, and disconnects at a frame boundary having paid for none of it.

A disconnect is not merely tolerated. The sink returning an error cancels the run context, which kills the process group; and every file the CLI writes from a stream goes to a temporary name and is renamed on artifact.end. A cancelled stream must not leave something that looks like a complete file, because the next thing to read that directory cannot tell the difference.

Artifacts

The script API is the same everywhere

const shot = await chrome_devtools.take_screenshot({ format: "png" });
await artifact("checkout.png", shot);
return { total };

data may be a string, a Uint8Array, an ArrayBuffer, { path }, an MCP image/audio/resource content item, or a tool result carrying one on .raw. Accepting the content item directly is what makes the common case one line: a screenshot arrives as {type:"image",data,mimeType} and that is exactly what gets passed in.

The script never asks where it is running. The issue’s step 1 — if (mcpx.session.isRemote) — was rejected for that reason: an author who has to know about remoteness writes two code paths and one of them is never tested.

What actually happens underneath differs, and only in a way nobody has to think about. artifact() POSTs to /v1/artifacts over the transport the generated client already has. When the runner set MCPX_ARTIFACTS_LOCAL=1 — which it does when a unix socket proves the daemon shares this filesystem — a {path} is sent as a header and the daemon reads, hashes, and copies the file into the store. Otherwise the bytes travel once to the daemon and are then fetched by whoever wants them.

Remoteness is declared, never inferred. A unix socket can be ssh-forwarded and loopback TCP can be a container with its own filesystem; neither transport tells you whether the caller can see the daemon’s disk. So the caller says so, with capabilities: ["artifacts"] and optionally sharedFs.

An ssh:// endpoint is the clearest case of sharedFs: false: the bytes cross a process boundary on another machine, so the caller uploads a {path} artifact’s bytes rather than giving the daemon a path it can read.

The store

Content-addressed by sha256 under <state>/artifacts/blobs/ab/cdef..., with a SQLite index beside it. SQLite because it is already a dependency and because “list the artifacts of this run” is a query rather than a directory walk.

The handle is not the hash. A content hash is guessable by anyone who can guess the content — and for a screenshot of a public page, that is everyone. So an artifact is served by a separate random 128-bit id mapped to the hash. That id is the entire access control until OAuth privilege levels land, which is why it is sized as a secret rather than as an identifier. When scopes arrive, the natural shape is that the session that produced an artifact owns it and a privileged scope can read any of them; the index already carries the session for exactly that.

Two registrations of the same bytes share one blob and get two handles. The quota counts distinct content, so a script that produces the same screenshot twice pays once. Deleting a registration only removes the body when no other registration refers to it.

Everything is written to a temporary name and renamed on completion — in the store, in --artifacts-dir, and in the stream consumer. A cancelled upload leaves nothing a later reader could mistake for a whole file.

Names are untrusted

The name comes from the script, and a script is not trusted with a path. SanitizeName takes the last component (so ../../etc/passwd is passwd), keeps [A-Za-z0-9.-_+], turns spaces into hyphens and everything else into underscores, strips leading and trailing dots, and truncates to artifacts.nameMaxLength while keeping the extension. An empty result becomes artifact, because a file has to be called something.

Removal rather than rejection: a caller whose artifact is refused over its name has lost the file, and the name is decoration — the artifact is reached by id.

Collisions get a numeric suffix before the extension — shot-1.png, not shot.png-1 — so the file still opens in whatever the extension implies. Nothing is ever overwritten: two files called shot.png are two files, and silently keeping one of them is data loss. The reservation uses O_CREAT|O_EXCL, because testing with Stat and then creating is a race two concurrent runs of the same script would lose.

Delivery

A sharedFs or dir lets the caller read the destination directly, but the store still copies the bytes into that directory; this saves a later transfer, not filesystem I/O.

Reference is the default because of the round-trip arithmetic. Over a unix socket a second request costs about 0.2 ms, so separate GETs are free locally and bring Range and parallel downloads with them. Remotely a single stream is better, which is why stream exists — and artifacts remain fetchable by id afterwards either way, so choosing the stream costs nothing.

inline’s ceiling is deliberately well under the per-artifact ceiling. Inline delivery puts bytes in the caller’s context, which is the cost this whole feature exists to avoid.

Intercepting upstream media

When a structured or streamed result — or an emit — contains an MCP image, audio or blob resource block, and the caller declared artifacts, the block is stored and replaced by a resource_link carrying the URI, the name, the type and the size.

This is the local win, and it is worth having with no remote daemon anywhere. chrome-devtools returns a screenshot as base64 image content; left alone that lands in an agent’s context, where one screenshot costs more than the rest of the task and where nobody will ever look at it.

It happens at the output boundary, not inside the script. A script that received a handle instead of the bytes could not inspect the image it just took — measure it, crop it, compare two — which is a real thing scripts do. So the script sees whatever the upstream server sent, and only what crosses back to the caller is rewritten. artifacts.interceptImages turns it off.

Reaching an artifact

GET /v1/artifacts/{id} goes through http.ServeContent, which brings Range, conditional requests and 206 for free — and Range is what makes reading the tail of a large artifact cheap, one of the three things printing the file could not do. Content-Disposition is attachment with the sanitised name, because a browser deciding to render somebody else’s bytes inline is how a store of arbitrary files becomes an XSS surface.

resources/read carries text, so a binary body comes back base64 with its real type stated. That is lossy in exactly one way — the client decodes — and it is what the protocol offers. A client that wants raw bytes has the /v1 route.

One edit outside this area

mcpserver.dispatch returns a string, which cannot carry a resource_link. Threading a content array through a dozen cases to serve one of them would make eleven signatures worse to serve the twelfth. So mcpx_exec encodes its blocks into the string it already returns (mcpserver.EncodeResult), and tools/call decodes it in exactly one place. EncodeResult returns the text unchanged when there are no blocks, so every other tool is byte-for-byte what it was.

Settings

Everything is declared in internal/settings/exec.go. It is not declared once: unlike internal/settings/consumer.go and internal/settings/wire.go, which read defaults.*, every Default: in exec.go is an inline string literal ("120s", "64MiB", "10m", …), so each value that also lives in defaults.json is written in two places with nothing holding them equal. Three of them — exec.where, artifacts.enabled and artifacts.dir — have no defaults.json key at all. The values below are what both say today.

Exceeding maxBytes is an error, not a truncation. A truncated screenshot is worse than a refused one, because it looks like it worked.

nameMaxLength, nameCollisionLimit, idBytes and listLimit live in defaults.json without a registry entry: they are read at package initialisation and a configuration file arriving later could not change them, and a setting that does nothing is worse than no setting. (This paragraph used to offer plumbing.eventHistory as the comparison. That one is a setting — events.history, internal/settings/wire.go:239, flag --events-history — so it was the wrong example.)

Not done

• The other direction. An inbox — uploading a file a script needs as input, with a script-side input("name") — is out of scope for this cut. Nothing here prevents it: POST /v1/artifacts already stores by content and the index already carries a session.
• OAuth scoping. Artifacts are served by an unguessable id on an unauthenticated API, which is the same access control every other /v1 route has. The index carries the session so a scope check has something to check.
• multipart/mixed. The issue offers it as an alternative to base64 in the stream. NDJSON and SSE carry chunks base64’d, which costs 33% on the wire. Worth revisiting; not worth a second framing before the first one has a user.
• Relative imports on a remote run. They need sibling modules on the runtime’s disk, and a remote run sends one file’s text.

FAQ

The five questions a skeptical first-time reader asks first, in the order they ask them, answered in the same voice.

Short answers here; the long ones live in the pages each answer links to. Every question keeps the wording it was written in.

“so why’d you get rid of all the mcp and then make one, do you like mcp or not”

We like MCP fine. What we got rid of is tool schemas sitting in the model’s context, not MCP itself: mcpx is an MCP client of every server you configure, across four protocol revisions, reading the same mcpServers config every other host reads, and “mcpx puts every MCP server behind one command so their schemas stay out of the model’s context until something asks for them”. The server we made is deliberately tiny. “Exposing three hundred tools over MCP would rebuild the problem mcpx was built to solve, with extra steps”, so it is /mcp on the daemon, mcpx serve --transport stdio, and mcpx_exec as the one tool that matters.

More: the story.

“i mean, opencodemode is right there”

It is, and not only in v2. opencode v1 ships code mode behind OPENCODE_EXPERIMENTAL_CODE_MODE, v2 has it on by default, and both accept TypeScript. Its version is better confined: a purpose-built interpreter that runs only the language features upstream implemented, plus OAuth and elicitation for remote servers. What it does not do is what mcpx is for. It only runs inside a model turn — there is no opencode2 exec — one daemon here serves every harness with a real process per session for stateful servers, and our scripts run on a real runtime with imports and a filesystem. Our own recommendation still stands: let code mode own ordinary MCP inside opencode’s loop, and use mcpx for stateful servers and everything outside a turn.

More: the opencode plugin.

“is it safe?”, no.

No. Scripts run on a real runtime with your authority — filesystem, network, subprocesses. script.permissions defaults to all. What a narrower profile does depends on the runtime, and the defaults say so exactly (internal/defaults/defaults.json): on Deno the profiles become Deno permission flags, and on node readnet / read-net are enforced with --permission --allow-fs-read=*. net, read, and strict are defined for Deno only. Ask for a named profile that has no entry for the runtime you chose and mcpx refuses to run the script at all — “permission profile %q defines no flags for %s, so %s cannot enforce it” (internal/runner/runtimes.go) — it never runs the script unenforced and pretends otherwise. Bun has no permission model, so no narrower profile is defined for it and every narrower ask there is refused the same way. The profiles that are defined for bun and node — all, none, off, unsandboxed — carry an empty flag list by design: defined, and deliberately unrestricted, not enforcement. The daemon API is unauthenticated. It listens on loopback and on a socket only you can open, and binding it wider prints a warning. mcpx prompt hands you a generated script instead of running it, because generated code runs with your credentials. So treat a script like a shell command you are about to paste: configure only servers you would run by hand, and do not expose the port. That is the whole answer.

More: the script contract.

“but why would you..”

Three reasons, then the history. Context cost: tool schemas sit in every request whether or not the tools get used, so mcpx’s always-on cost is zero — “there are 27 Chrome tools live on this machine and not one byte of their schemas is in the agent’s context”. Concurrency: two agents sharing one browser corrupt each other, so each session gets its own process. Reach: the same tools from a shell, CI or any harness. The history is that this replaced lootbox, a fork 51 commits ahead of a quiet upstream, where discovery was uncached (about 650 ms per request) and the architecture “cannot express the one thing you actually need (more than one Chrome)”.

More: the assessment.

“but can i get some examples?”

Yes. examples/ holds short scripts that CI runs on every change, against a deterministic fixture server, paired with the output they print today — so an example cannot quietly rot, and one of them is a real recipe (mcpx recipes). The gallery page pairs each script with its command and its expected output; copy one, change the server name, run it. They are deliberately small, and none of them needs Chrome or the network. If one is wrong, that is a bug worth reporting, because the only reason these are trustworthy is that they fail the build when they stop being true.

More: the examples gallery.

Finding the repository without git

How the repo and worktree scopes decide which repository a caller is in, why that no longer runs git, and what was decided for every layout git understands.

created:      2026-09-30T07:30:00-05:00
last-updated: 2026-09-30T07:30:00-05:00
status:       implemented

This is the decision record for the change. docs/container.md §3 is the short version; it lives here rather than under docs/decisions/ because that directory belongs to another area.

1. Two questions

A server scoped repo gets one process per clone – every linked worktree of one repository shares it. A server scoped worktree gets one per checkout. The keys are the answers to two questions git already has commands for:

Until this change mcpx asked exactly those, by forking git twice per directory and caching both answers – negative ones included – for the daemon’s lifetime. That had four costs, three of which were only found by testing the replacement: