Configuration reference

This page is the exhaustive, auto-generated reference for the operator settings.yaml surface. It is generated from the permconfig YAML schema (internal/adapter/permconfig/schema.go) — the same structs that strictly parse the file at startup — so it cannot drift from the code.

For configuration workflows and examples, see Configure Mecatl. To scaffold a complete commented file, run mecated config init (or mecated config init --print to print it). Validate the conventional file with mecated config validate, or select one with mecated config validate --file PATH; validation is offline, read-only, and never prints settings values.

The settings file lives at <XDG_CONFIG_HOME>/mecatl/settings.yaml (default ~/.config/mecatl/settings.yaml). The tier column records which configuration tier honours a subtree: operator-tier subtrees are honoured ONLY from this user-global file + CLI (a project .mecatl/settings.yaml copy is ignored with a WARN — honouring it would be a security downgrade); operator + project subtrees may also be set per-project (within the operator's cap / trust gate).

The Default column describes the settings.yaml schema/resolver fallback when an applicable key is ABSENT ((empty) for an unset string, (absent) for an unset map/list/sub-block). It is not a universal process-runtime default: command roots and modes can supply their own defaults, disable a feature, or reject a setting. The example values in the config init skeleton are ILLUSTRATIVE, not defaults. For the configuration planes and intentional per-mode differences, see Configure Mecatl.

permissions

Tier: operator + project

Allow/ask/deny rule-spec lists. Each entry is "Tool(pattern)" or a bare "Tool". Deny is deny-dominant and binds children too; allow/ask bind the main engine; the subagent block binds child engines. A project allow is trust-gated.

Key	Type	Default	Description
permissions.allow	[]string	(absent)	Allow lists rule specs that GRANT a tool call (effect Allow) on the MAIN engine. Under an untrusted project these are DROPPED by the trust gate (see Resolver).
permissions.ask	[]string	(absent)	Ask lists rule specs that REQUIRE approval (effect Ask) on the MAIN engine. Always honoured.
permissions.deny	[]string	(absent)	Deny lists rule specs that BLOCK a tool call (effect Deny) EVERYWHERE — main engine and subagents (a deny only tightens). Always honoured.
permissions.subagent	subagentpermissions	(absent)	Subagent holds the child-scoped rule-spec lists (issue #32): rules that bind ONLY subagent/member/branch engines, resolved through the child-ask model (a subagent allow can clear a substitution-floored ask; a subagent ask surfaces to the human or auto-denies; a subagent deny blocks).
permissions.subagent.allow	[]string	(absent)	Allow lists child-scoped rule specs with effect Allow (trust-gated for project tiers).
permissions.subagent.ask	[]string	(absent)	Ask lists child-scoped rule specs with effect Ask (always honoured). A configured subagent Ask is NEVER auto-approved by the isolation carve-out — it surfaces to a human or auto-denies.
permissions.subagent.deny	[]string	(absent)	Deny lists child-scoped rule specs with effect Deny (always honoured).

guardrails

Tier: operator

OPERATOR-TIER LLM content-checker (issue #27). Parsed strictly. A project-tier guardrails: block is IGNORED with a WARN (a project cannot weaken a security checker).

Enable: Configuring model: ENABLES guardrails; disabled: true is the kill-switch (the CLI --guardrails=off also sets it).

Key	Type	Default	Description
guardrails.model	string	(empty)	Model is the checker model id / alias. Empty leaves the CLI --guardrails-model to supply it; a value here is overridden by the CLI flag when both are set. Enable: Setting a model here ENABLES guardrails (the guardrails-parity enable model). A configured model with no rules runs the default BLOCK set (WebSearch/WebFetch/mcp__*/Shell, enforcing; downgrade via defaultMode: advisory). Leave empty (and pass no --guardrails-model) to keep guardrails OFF.
guardrails.minContentBytes	int	0	MinContentBytes skips the checker for content shorter than this. 0 = check all.
guardrails.disabled	bool	false	Disabled is the YAML-level kill switch (the CLI --guardrails=off also sets it).
guardrails.onCheckerDown	string	(empty)	OnCheckerDown sets the global posture when the checker model is unavailable (error/timeout): "warn" (default, fail-open) or "fail" (fail-closed for all rules). Per-rule failClosed overrides: failClosed:true tightens even under warn; failClosed:false (explicit) loosens even under fail. Empty = warn.
guardrails.defaultMode	string	(empty)	DefaultMode sets the enforcement mode for the built-in default rules when no explicit rules are configured: "block" (default), "advisory", or "sanitize". An explicit rules list replaces the defaults entirely (this key is ignored).
guardrails.escape	bool	false	Escape is the ADR-0080 escape knob: when true AND a checker model is configured, an out-of-root FS escape at posture auto routes through the guardrail checker (an unsafe verdict denies; a checker error fails closed to the write-escape Ask). Default false = the un-routed posture table.
guardrails.rules	[]guardrailrulespec	(absent)	Rules is the guardrail rule list.
guardrails.rules[].match	string	(empty)	Match is the tool-name matcher (exact / "prefix*" / "*").
guardrails.rules[].phases	[]string	(absent)	Phases lists "pre"/"post"; empty = both.
guardrails.rules[].mode	string	(empty)	Mode is "block"/"sanitize"/"advisory"; empty defaults to block.
guardrails.rules[].prompt	string	(empty)	Prompt overrides the built-in inspection rubric.
guardrails.rules[].failClosed	bool	false	FailClosed flips the fail-open default for enforcing modes.

posture

Tier: operator

OPERATOR-TIER posture-ladder scalar: strict < trusted < auto < yolo (the graduated trust/automation tier). A project-tier posture: is IGNORED with a WARN (a project cannot raise the automation posture). Empty = keep the CLI/default.

Value	Type	Default	Description
posture	string	(empty)	Posture is the OPERATOR-TIER posture-ladder scalar (the graduated trust/ automation tier: strict/trusted/auto/yolo). Like Guardrails it is honoured ONLY from the user-global + CLI tiers; a project-tier file's posture: key is IGNORED with a WARN (a project repo RAISING the automation posture — e.g. posture: yolo — is a security DOWNGRADE the tighten-only project gate forbids, the fail-closed core of this feature). Empty = absent (the resolver returns "" and composition keeps the CLI/default). The composition layer parses the string; permconfig only reads the scalar.

reasoning-effort

Tier: operator

OPERATOR-TIER reasoning-effort scalar (ADR 0055): "" / "auto" (unset — the provider default) / "low" / "medium" / "high" / "xhigh" / "max". OpenAI clamps xhigh/max down to high; Anthropic maps all five. A per-session CreateSession.reasoning_effort out-ranks this default. A project-tier reasoning-effort: is IGNORED with a WARN (a project cannot raise the model's reasoning spend). Empty = keep the CLI/default (provider default).

Value	Type	Default	Description
reasoning-effort	string	(empty)	ReasoningEffort is the OPERATOR-TIER reasoning-effort scalar (ADR 0055: the neutral vocabulary "" / "auto" / "low" / "medium" / "high" / "xhigh" / "max"). Like Posture it is honoured ONLY from the user-global + CLI tiers; a project-tier file's reasoning-effort: key is IGNORED with a WARN (operator-tier only, for consistency — a project cannot raise the model's reasoning spend). Empty = absent (the resolver returns "" and composition uses the provider default). The composition layer interprets + clamps the token; permconfig only reads the scalar.

plan-mode-auto-approve

Tier: operator

OPERATOR-TIER plan-mode auto-approve flag (issue #206): when true, a plan-mode session that parks awaiting a plan-approval ask is auto-approved (flip to default mode and execute) WITHOUT a human reviewing the plan. DEFAULT OFF. A project-tier plan-mode-auto-approve: is IGNORED with a WARN (a project cannot grant an autonomous approval capability).

Value	Type	Default	Description
plan-mode-auto-approve	bool	false	PlanModeAutoApprove is the OPERATOR-TIER plan-mode-auto-approve flag (issue #206 Wave 6a). Like Posture/ReasoningEffort it is honoured ONLY from the user-global + CLI tiers; a project-tier file's plan-mode-auto-approve: key is IGNORED with a WARN (operator-tier only — a project repo enabling autonomous plan approval is a security DOWNGRADE). false = absent (the resolver returns false and composition keeps the default OFF). The composition layer interprets the bool; permconfig only reads the scalar.

providers

Tier: operator

Strict operator-defined LLM providers. Project-tier definitions are ignored. Provider URLs must be HTTPS without userinfo, query, or fragment; credentials belong only in auth.yaml.

Key	Type	Default	Description
providers.team-gateway	providerdefinition	(absent)
providers.team-gateway.base_url	string	(required)
providers.team-gateway.default_model	string	(required)
providers.team-gateway.api_flavor	string	(required)
providers.team-gateway.auth	providerauth	(absent)
providers.team-gateway.auth.method	string	none

provider_overrides

Tier: operator

Strict endpoint overrides for built-in openai, openrouter, anthropic, and opencode only. Codex and ToolHive policies cannot be overridden here.

Key	Type	Default	Description
provider_overrides.openai	provideroverride	(absent)
provider_overrides.openai.base_url	string	(required)

learning

Tier: operator + project

Optional completed-trajectory observation policy. Off means no automatic completed-trajectory reflection or review; project settings may only tighten the operator ceiling off < review < auto. Separately configured consolidation schedules are independent.

Key	Type	Default	Description
learning.mode	string	off	Mode controls automatic completed-trajectory observation: off (default; no automatic reflection), review (signal-gated reflection stages durable proposals without memory writes), or auto (stage first, then conservatively promote only eligible non-conflicting facts). Operator settings establish the ceiling; project settings may only tighten it under off < review < auto and never raise autonomy. It does not override separately configured maintenance schedules such as --user-model-consolidate-interval.
learning.sensitivity	string	balanced	Sensitivity controls weighted automatic admission. Empty means balanced.
learning.skills	learningskillssection	(absent)	Skills controls learned-skill lifecycle policy.
learning.skills.activation	string	validated when mode is explicitly auto; evaluated otherwise	Activation is validated (default for Auto) or evaluated. Project settings may only tighten validated to evaluated.
learning.automatic	learningautomaticsection	(absent)	Automatic is operator-only admission policy. Standard non-off composition applies it through a durable ledger, making count/token windows, cooldown, and deduplication deployment-wide across cooperating processes.
learning.automatic.cooldown	duration	10m	Cooldown is the per-principal weighted-admission cooldown; zero disables it.
learning.automatic.window	duration	1h	Window is the sliding count/token window, strictly 1m..24h.
learning.automatic.max_reflections	int	8	MaxReflections is the global count cap; zero disables automatic reflection.
learning.automatic.max_tokens	int	100000	MaxTokens is the global reserved-token cap; zero disables automatic reflection.
learning.automatic.max_reflections_per_principal	int	4	MaxReflectionsPerPrincipal is the per-principal count cap; zero disables automatic reflection.
learning.automatic.max_tokens_per_principal	int	50000	MaxTokensPerPrincipal is the per-principal reserved-token cap; zero disables automatic reflection.

retention

Tier: operator

Versioned automatic session cleanup policy. Operator-tier only; project values are ignored. Zero disables each limit. Explicit compatibility flags outrank these values.

Key	Type	Default	Description
retention.version	int	1	Version is the required schema version; the only supported value is 1.
retention.main	retentionlimitsection	(absent)	Main controls top-level operator/service sessions.
retention.main.max_age	string	(empty)	MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit.
retention.main.max_count	int	0	MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit.
retention.child	retentionlimitsection	(absent)	Child controls subagent, parallel-branch, and team-member sessions.
retention.child.max_age	string	(empty)	MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit.
retention.child.max_count	int	0	MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit.
retention.scheduled	retentionlimitsection	(absent)	Scheduled controls scheduled-fire sessions.
retention.scheduled.max_age	string	(empty)	MaxAge deletes eligible rows older than this Go duration; 0 disables the age limit.
retention.scheduled.max_count	int	0	MaxCount keeps the newest eligible rows up to this count; 0 disables the count limit.
retention.sweep_cadence	duration	1h	SweepCadence is the repeat interval; 0 disables repeats while retaining the compatibility startup sweep.
retention.acknowledge_main_deletion	bool	false	AcknowledgeMainDeletion explicitly consents to destructive main-session cleanup.

temporary_storage

Tier: operator

Managed command temporary-storage policy. Read only from user-global settings.yaml; project and explicit CLI config values are ignored. Managed mode is Linux-only; system preserves inherited temporary-directory behavior.

Key	Type	Default	Description
temporary_storage.mode	string	managed
temporary_storage.managed_root	string	mecatl
temporary_storage.system_temp_dir	string	inherited
temporary_storage.command_reap_after	duration	1h
temporary_storage.reap_interval	duration	1h
temporary_storage.reap_timeout	duration	5m
temporary_storage.shutdown_reap_timeout	duration	1m

storage_management

Tier: operator

Exact verified OIDC issuer/subject pairs authorized for process-wide storage health, migration, and cleanup. Empty grants nobody; project values are ignored.

Key	Type	Default	Description
storage_management.version	int	1	Version is the required schema version; the only supported value is 1.
storage_management.principals	[]storagemanagementprincipal	(absent)	Principals lists exact verified OIDC issuer/subject pairs. Empty grants nobody.
storage_management.principals[].issuer	string	(empty)	Issuer must equal the verified token issuer byte-for-byte.
storage_management.principals[].subject	string	(empty)	Subject must equal the verified token subject byte-for-byte.

steer

Tier: operator

OPERATOR-TIER mid-run steer knob (steer-while-running, issue #512): when true (the DEFAULT), a client may inject an operator instruction into an in-flight run, drained at the next turn boundary. Set false to disable the steer inbox (the capability echo then reads false and a steer frame reports too_late). A project-tier steer: is IGNORED with a WARN (the harness's operator surface is not a project repo's to flip). Omit = keep the CLI/default (steer ON).

Value	Type	Default	Description
steer	bool	true	Steer is the OPERATOR-TIER mid-run steer knob (steer-while-running, issue #512): enable (default) or disable the mid-run steer inbox. Like Posture/ReasoningEffort it is honoured ONLY from the user-global + CLI tiers; a project-tier file's steer: key is IGNORED with a WARN (operator-tier only — the harness's operator surface is not a project repo's to flip, in either direction). It is a *bool so ABSENT is distinguishable from an explicit false: nil = absent (the resolver reports not-present and composition keeps the DEFAULT-ON); a non-nil value is honoured (composition maps steer: false onto the opt-OUT DisableSteer).

models

Tier: operator + project

Per-slot/alias/default model config (ADR 0030) + the operator allowlist cap and the semantic Subagent model-router taxonomy (ADR 0031/0042). At the operator tier all fields are honoured; a project tier honours slots/aliases/default within the operator allowlist on a trusted workspace (router/allowlist are operator-only).

Key	Type	Default	Description
models.slots	map[string]string	(absent)	Slots binds a slot name (a call-slot "compaction"/"ask-reviewer"/"guardrail" or a tier "cheap"/"fast"/"reasoning") to a model selector (alias or concrete id).
models.aliases	map[string]string	(absent)	Aliases binds a short alias to a concrete model id (merged onto the CLI --model-alias map, CLI winning per key).
models.default	string	(empty)	Default is the session-default model selector (alias or concrete id). It is the project-overridable session default (ADR 0030 Phase 4) — within the operator allowlist; the operator's own Default is uncapped. Empty = absent.
models.subagent	string	(empty)	Subagent is the OPERATOR-TIER def-less child-default model selector (alias or concrete id): the settings.yaml twin of the --subagent-model flag (issue #288). It sets the global default model for every Subagent / Parallel-branch / team-member child that does not pin its own model (via an agent definition or a per-call override). Operator-tier ONLY: a project-tier subagent: is IGNORED with a WARN (the child-default model is an operator decision — the same operator-only captureModels discipline as default_provider/allowlist/router). The CLI --subagent-model WINS when both are set. Validated FAIL-FAST at Build (normalizeSubagentModel): a value that does not resolve to a usable model id is a startup error (unlike fail-soft models.default). Empty = absent (the flag/inherit-parent behaviour is unchanged).
models.default_provider	string	(empty)	DefaultProvider is the OPERATOR-TIER deployment-wide default provider id (e.g. openai, openrouter, anthropic, toolhive). It mirrors the --default-provider flag (app.Config.DefaultProvider) so an operator can declare "toolhive is my default despite my API key" persistently in settings.yaml without unsetting the key. It feeds the UNCHANGED preferredDefaultProvider ladder as an explicit override — it does NOT lower the precedence of key-driven providers. Operator-tier only: a project-tier default_provider: is IGNORED with a WARN (the same operator-only captureModels discipline as posture/guardrails/allowlist). Validated FAIL-FAST at Build (validateDefaultModel): an unknown/unavailable provider is a startup error. Empty = absent (the ladder's preferred default wins). The name pair (default = model, default_provider = provider) mirrors the wire grammar exactly.
models.allowlist	[]string	(absent)	Allowlist is the OPERATOR-TIER, non-wideable cap (ADR 0030 Phase 4): the set of model selectors (alias names and/or concrete ids) a PROJECT-tier models: block may bind to. An empty/absent allowlist means project models stay WARN-ignored (the opt-in: no cap ⇒ no project override, byte-identical to pre-Phase-4). It is honoured ONLY from the operator tiers; a project-tier allowlist: key is ignored with a WARN (a project cannot widen its own cap).
models.router	routersection	(absent)	Router is the OPERATOR-TIER semantic Subagent model-router taxonomy (ADR 0031, Phase 5; enable model superseded by ADR 0042): a classifier slot, the routing categories, the default category, and the YAML kill-switch. It is operator-tier ONLY — a project-tier router: sub-block is STRIPPED with a WARN (the taxonomy is an autonomous-spend/capability decision the operator owns, like the allowlist). nil/absent = no taxonomy ⇒ the router is OFF (byte-identical, silent). Per ADR 0042 the TAXONOMY is the enable: a non-empty router: with categories turns the router ON unless disabled: true (or the CLI kill-switch) forces it off — the guardrails-parity enable model, replacing 0031's flag-to-enable. Enable: A non-empty categories list ENABLES the router (taxonomy-presence enable, ADR 0042 — NOT a CLI enable-flag); disabled: true (or --subagent-model-router=false) is the kill-switch. Operator-tier only.
models.router.classifier-slot	string	(empty)	ClassifierSlot names the model slot the CLASSIFIER itself runs on (the tiny, cheap one-turn classification call). Empty falls through to the router slot's default tier (cheap) — the classifier is housekeeping, not the routed work.
models.router.categories	[]routercategory	(absent)	Categories are the routing choices. Each carries a Name (the classifier's verdict key), a Description (the classifier's only signal — make them distinct), and a Model selector (an alias / slot / concrete id, resolved through the operator- merged alias map; operator taxonomy targets are UNCAPPED).
models.router.categories[].name	string	(empty)	Name is the routing key the classifier echoes back as its verdict and the key composition maps to Model.
models.router.categories[].description	string	(empty)	Description is the one-line summary the classifier reads to choose this category.
models.router.categories[].model	string	(empty)	Model is the model selector (alias / slot / concrete id) a task classified into this category is minted on, resolved through the operator-merged alias map.
models.router.default-category	string	(empty)	DefaultCategory is the category the classifier is told to choose when none clearly fits (advisory to the classifier; the real safety net is the fail-soft inherit).
models.router.disabled	bool	false	Disabled is the YAML-level kill switch (ADR 0042, mirroring GuardrailsSection.Disabled): per ADR 0042 a non-empty taxonomy ENABLES the router, so disabled: true is the "taxonomy defined but temporarily off" override. The CLI kill-switch --subagent-model-router=false also sets it (the two OR together). Default false ⇒ the router is enabled whenever categories are present.
models.context_windows	map[string]map[string]int	(absent)	ContextWindows is the OPERATOR-TIER exact provider ID → exact final model ID → total context token override map. It is intentionally not a selector map: aliases and slots are resolved before this lookup, and project values are ignored.

openrouter

Tier: operator

OPERATOR-TIER OpenRouter downstream-provider routing (issue #480): a per-model preferred DOWNSTREAM provider order, sent as OpenRouter's provider request-body object. Setting an order disables OpenRouter's default price load-balancing; allow_fallbacks: false pins hard to the order. A project-tier openrouter: block is IGNORED with a WARN (a project cannot pick the downstream provider).

Key	Type	Default	Description
openrouter.models	map[string]openroutermodelroute	(absent)	Models maps a model id (or alias, resolved in composition) to its downstream-provider routing preference.
openrouter.models.<key>.order	[]string	(absent)	Order lists downstream provider slugs (lowercase-kebab, e.g. "anthropic", "google-vertex", "deepinfra/turbo") tried in order. Setting it disables OpenRouter's default price load-balancing. Base-slug matching applies: "google-vertex" matches all its regions/variants (service tiers excepted).
openrouter.models.<key>.allow_fallbacks	bool	(absent)	AllowFallbacks, when explicitly false, pins the request to Order with no fallback to other downstreams. Omit the key to keep OpenRouter's default (true); set it to false to disable fallback.

telemetry

Tier: operator

OPERATOR-TIER opt-out product/adoption metrics (telemetry.productMetrics). Honoured ONLY from the user-global + CLI tiers; a project-tier telemetry: block is IGNORED with a WARN (a project repo cannot flip a user's own telemetry choice in either direction). Omit entirely to fall through to the DO_NOT_TRACK env var and finally the enabled-by-default posture.

Key	Type	Default	Description
telemetry.productMetrics	productmetricssection	(absent)	ProductMetrics is the opt-out product/adoption metrics config.
telemetry.productMetrics.enabled	bool	(absent)	Enabled is a *bool so ABSENT (nil) is distinguishable from an explicit false: nil = absent (composition falls through to DO_NOT_TRACK then the enabled-by-default posture); a non-nil value is honoured exactly.

mcp

Tier: operator

Strict OPERATOR-TIER Streamable HTTP MCP authority configuration. Mode selects one mutually exclusive global or session-broker authority; broker mode carries its callback configuration and neutral route declarations. Authentication is a closed none/static_bearer/oauth union. Broker OAuth may use trusted explicit OAuth2 endpoints; all secret-shaped values are MECATL_* environment references, never values in YAML. Project mcp blocks are ignored with a value-free warning.

Key	Type	Default	Description
mcp.mode	string	(empty)	Mode selects global or broker authority. Empty uses the command-root default.
mcp.broker	mcpbrokerprofile	(absent)	Broker contains options meaningful only in broker mode.
mcp.broker.callback_url	string	(empty)	CallbackURL is required exactly when broker mode contains an OAuth route. It must be an absolute HTTPS URL without userinfo, query, or fragment; an omitted path or / is normalized to /.
mcp.servers	[]mcpserverprofile	(absent)	Servers is the ordered list of neutral Streamable HTTP route declarations.
mcp.servers[].name	string	(empty)	Name is an ASCII [A-Za-z0-9_]+ identifier, unique case-insensitively.
mcp.servers[].url	string	(empty)	URL is an absolute HTTP(S) endpoint without userinfo or a fragment.
mcp.servers[].auth	mcpauthprofile	(absent)	Auth selects exactly one of none, static_bearer, or oauth.
mcp.servers[].auth.mode	string	(empty)	Mode is exactly none, static_bearer, or oauth.
mcp.servers[].auth.static_bearer	mcpstaticbearerprofile	(absent)	StaticBearer names the bearer-token environment reference.
mcp.servers[].auth.static_bearer.token_env	string	(empty)	TokenEnv is a MECATL_* environment variable name containing the opaque token.
mcp.servers[].auth.oauth	mcpoauthprofile	(absent)	OAuth declares the OAuth identity, client, credentials, scopes, and network policy.
mcp.servers[].auth.oauth.profile	string	(empty)	Profile is the required global-mode credential identity profile and is forbidden in broker mode.
mcp.servers[].auth.oauth.principal	string	(empty)	Principal is the required global-mode credential identity principal and is forbidden in broker mode.
mcp.servers[].auth.oauth.issuer	string	(empty)	Issuer is the canonical exact origin used by OIDC discovery. It is forbidden when Upstream explicitly selects generic OAuth2.
mcp.servers[].auth.oauth.upstream	mcpoauthupstreamprofile	(absent)	Upstream optionally selects OIDC discovery or explicit generic OAuth2. Omitted defaults to OIDC.
mcp.servers[].auth.oauth.upstream.mode	string	(empty)
mcp.servers[].auth.oauth.upstream.oauth2	mcpoauth2upstreamprofile	(absent)
mcp.servers[].auth.oauth.upstream.oauth2.authorization_endpoint	string	(empty)
mcp.servers[].auth.oauth.upstream.oauth2.token_endpoint	string	(empty)	TokenEndpoint is a canonical HTTPS URL with no query string or fragment: the hardened runtime token client pins the exact origin and controls the request query itself.
mcp.servers[].auth.oauth.client	mcpoauthclientprofile	(absent)	Client selects exactly one preregistered, CIMD, or DCR client declaration.
mcp.servers[].auth.oauth.client.mode	string	(empty)	Mode is exactly preregistered, cimd, or dcr.
mcp.servers[].auth.oauth.client.preregistered	mcppreregisteredclientprofile	(absent)	Preregistered declares a confidential client registered with the issuer.
mcp.servers[].auth.oauth.client.preregistered.id	string	(empty)	ID is the required preregistered OAuth client identifier.
mcp.servers[].auth.oauth.client.preregistered.secret_env	string	(empty)	SecretEnv is a MECATL_* environment variable name containing the client secret.
mcp.servers[].auth.oauth.client.cimd	mcpcimdclientprofile	(absent)	CIMD declares an HTTPS client-id metadata document URL.
mcp.servers[].auth.oauth.client.cimd.document_url	string	(empty)	DocumentURL is the required HTTPS metadata-document URL.
mcp.servers[].auth.oauth.client.dcr	mcpdcrclientprofile	(absent)	DCR declares an RFC 8414 metadata URL for RFC 7591 registration.
mcp.servers[].auth.oauth.client.dcr.discovery_url	string	(empty)	DiscoveryURL is the required HTTPS authorization-server metadata URL.
mcp.servers[].auth.oauth.scopes	[]string	(absent)	Scopes is the non-empty allowlist of OAuth scopes the client may request.
mcp.servers[].auth.oauth.request_refresh_token	bool	false	RequestRefreshToken asks the authorization server for refresh capability.
mcp.servers[].auth.oauth.credentials	mcpoauthcredentialprofile	(absent)	Credentials selects one global-mode local or environment credential source and is forbidden in broker mode.
mcp.servers[].auth.oauth.credentials.mode	string	(empty)	Mode is exactly local or environment.
mcp.servers[].auth.oauth.credentials.local	mcplocalcredentialprofile	(absent)	Local declares encrypted mutable credentials rooted at an absolute path.
mcp.servers[].auth.oauth.credentials.local.root	string	(empty)	Root is the required absolute credential-store root.
mcp.servers[].auth.oauth.credentials.local.key_env	string	(empty)	KeyEnv is a MECATL_* environment variable name containing the encryption key.
mcp.servers[].auth.oauth.credentials.environment	mcpenvironmentcredentialprofile	(absent)	Environment declares one externally provisioned read-only credential record.
mcp.servers[].auth.oauth.credentials.environment.credential_env	string	(empty)	CredentialEnv is a MECATL_* environment variable containing the opaque credential record.
mcp.servers[].auth.oauth.credentials.environment.allow_process_local_refresh	bool	false	AllowProcessLocalRefresh permits refreshed credentials to live only in this process.
mcp.servers[].auth.oauth.network	mcpoauthnetworkprofile	(absent)	Network is required. Global profiles enforce its exact-origin egress policy; broker OAuth accepts only an explicit empty mapping until ToolHive can enforce it equivalently.
mcp.servers[].auth.oauth.network.additional_origins	[]string	(absent)	AdditionalOrigins lists canonical exact origins additionally allowed for OAuth traffic.
mcp.servers[].auth.oauth.network.private_origins	[]string	(absent)	PrivateOrigins lists allowed origins that may resolve only to RFC1918 IPv4 or ULA IPv6 addresses. Loopback, link-local, metadata, unspecified, multicast, mapped, public, and other special addresses remain denied.
mcp.servers[].auth.oauth.network.max_redirects	int	0	MaxRedirects is the redirect bound, from zero through five.
mcp.servers[].auth.oauth.tools	[]mcpstatictoolprofile	(absent)	Tools optionally declares this protected backend's tool catalogue statically. Declarations are visible before connection; the first call starts ToolHive's aggregate authorization for every protected backend. The granted bundle unlocks the declared surface only. Omitted, the backend remains discoverable only through pre-prompt workspace enrollment.
mcp.servers[].auth.oauth.tools[].name	string	(empty)
mcp.servers[].auth.oauth.tools[].description	string	(empty)
mcp.servers[].auth.oauth.tools[].input_schema	[]uint8	(absent)
mcp.servers[].auth.oauth.tools[].read_only	bool	false

Flag- / file-configured features (NOT in settings.yaml)

By design, settings.yaml covers the subtrees above. Several other operator features are configured through CLI flags (and, for some, their own files) rather than this YAML. See Run mecated standalone for the full flag tables. The pointers below are the starting points:

Feature	How it is configured	See
Soul (operator persona)	--soul-file / --no-soul (+ its own soul.md file)	Skills, commands, and soul
User-model learning	--user-model-dir / --user-model-review	Memory and knowledge
Memory	--memory-dir / --memory-store-url	Memory and knowledge
Slash commands	--commands-dir (+ the command .md files)	Skills, commands, and soul
Session leasing	--session-lease-*	Run mecated standalone

The model slots / aliases above also have CLI twins (--model-slot / --model-alias); the guardrails checker model has --guardrails-model; the router kill-switch has --subagent-model-router=false. The CLI flag and the YAML key are two surfaces for the same setting. See Configure Mecatl for precedence.