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.