Skip to content

MCP servers (mcp.json)

mast connects agents to tools over the Model Context Protocol (MCP). Server definitions live in a catalog file, mcp.json; a workload bundle references them by name via tool_catalog.mcp[].server. mast wires each referenced server generically, dispatched by transport kind — no server is special-cased.

  • Directory mode (--workload=<path>) — next to the workload: <path>/mcp.json.
  • Name mode (--workload=<name>) — at the config root selected by .agents/ discovery.

A workload that references a server absent from mcp.json is a fatal load error — mast refuses to start rather than silently drop a tool.

{
"version": 1,
"command_allowlist": ["/usr/local/bin/fs-mcp-server"],
"servers": {
"gke": {
"transport": "http",
"url": "https://container.googleapis.com/mcp",
"auth": {
"google_oauth": {
"scopes": ["https://www.googleapis.com/auth/cloud-platform"]
}
}
},
"filesystem": {
"transport": "stdio",
"command": "/usr/local/bin/fs-mcp-server",
"args": ["--root", "${WORKSPACE}/data"],
"env_mode": "clean",
"env_passthrough": ["PATH", "HOME"],
"env": {
"FS_MCP_TOKEN": "${FS_MCP_TOKEN}"
}
}
}
}
FieldTypeNotes
versionintRequired. Must be 1 — the only schema version this build accepts.
command_allowlistlist of stringsOptional, catalog-level. When non-empty, every stdio server’s resolved command must appear here or the catalog fails to load. Both sides are ${VAR}-expanded before comparison. Empty (the default) imposes no restriction.
serversmapServer name → definition. The map key is the name workloads reference; it must be non-empty.
servers.<name>.transportstringRequired. http or stdio.
servers.<name>.urlstringRequired for http. The streamable-HTTP endpoint.
servers.<name>.auth.google_oauth.scopeslist of stringshttp only. When present, requests carry an Application Default Credentials (ADC) bearer token with these scopes. Omit for an unauthenticated endpoint. Empty scopes default to cloud-platform.
servers.<name>.commandstringRequired for stdio. Executable to launch — a bare name resolved on PATH or an absolute path.
servers.<name>.argslist of stringsstdio only. Command arguments.
servers.<name>.env_modestringstdio only. inherit (default) — the child inherits the full daemon environment. clean — the child starts from an empty environment and receives only env_passthrough variables plus env.
servers.<name>.env_passthroughlist of stringsstdio only, and only under env_mode: "clean". Names of daemon environment variables to copy through to the child (each copied only if set). Rejected under inherit, where the child already sees everything.
servers.<name>.envmapstdio only. Environment variables layered on top (they override an inherited or passed-through variable of the same name).
servers.<name>.no_digestboolOptional. true opts this server out of response digesting — its tool responses reach the model byte-for-byte however large they are. See digesting large tool responses.

Unknown fields are tolerated (forward-compatibility with richer catalogs); the loader validates the version, each server name, and the per-transport required fields, reporting the first problem it finds.

Speaks MCP over a streamable-HTTP endpoint. When the entry declares auth.google_oauth, mast attaches an ADC bearer token and fails fast at startup if credentials cannot be loaded — surfacing a misconfiguration as a clear load error rather than a mid-run tool failure. With MAST_GOOGLE_AUTH=injected, it sends a placeholder bearer for an egress gateway to replace instead (Credentials an egress gateway adds). Without an auth block the endpoint is called unauthenticated.

mast launches command (with args and env) as a local child process and speaks MCP over its stdin/stdout. This is the path for local or sidecar MCP servers that authenticate through their own environment rather than a bearer token.

  • Variable expansion. ${VAR} references in command, each args entry, and each env value are expanded against the daemon environment. Expansion follows Go’s os.ExpandEnv, so a bare $name expands too and there is no escape for a literal $ — a value that must contain a literal dollar (for example a secret) should be passed through the inherited daemon environment rather than written into the catalog.
  • Environment. Under the default env_mode: "inherit" the child inherits the daemon’s environment and the configured env entries are layered on top (they override, applied in a deterministic order). Under env_mode: "clean" the child starts from an empty environment and sees only the env_passthrough daemon variables that are set, plus env — so a local tool server never receives the daemon’s provider API keys or cloud credentials unless you name them explicitly.
  • Command allowlist. The catalog-level command_allowlist, when non-empty, restricts which executables stdio servers may launch: an out-of-allowlist command is a fatal load error. This bounds the blast radius of an edited catalog even where the file itself is not gate-protected. The match is a literal string comparison after ${VAR} expansion — it does not resolve PATH or canonicalize symlinks, so list a command exactly as it is written in the server entry (a bare node and an absolute /usr/bin/node are distinct entries).
  • Lifecycle. The process is launched lazily on first tool use, not at startup. It then lives for the duration of the daemon (mast holds the toolset for the process lifetime and does not tear individual toolsets down); the child exits when it closes its own stdio or the daemon exits.

A single get_k8s_resource against a busy namespace can return tens of thousands of tokens of JSON, most of it managedFields and status history the model will never read. In an unattended loop that payload is paid for on every subsequent turn, because it stays in the context.

So mast routes MCP tool responses through a structural digest before the model sees them. This is on by default; --mcp-digest=false turns it off daemon-wide.

  • Responses under 8000 bytes are untouched — verbatim, not merely unpruned: mast adds no field of its own, not even a timing one. Most tool calls are small, and compressing a three-field answer costs more than it saves. Verbatim is also a correctness requirement: mast compares two reads of the same tool for equality when it re-checks a change-set precondition, and a wall clock in an otherwise unchanged response would void an approval the operator already gave.
  • Larger responses are pruned structurally — long arrays are sampled, deep objects collapsed — and arrive as a digest string with raw_bytes, method, latency_ms, and a savings breakdown alongside it. Nothing is sent to another model to do it: the pruner is deterministic code, so digesting adds no tokens, no spend, and no second failure mode to a tool call.
  • The original is kept. Every digested response carries a call_id, and the model gets a retrieve_raw tool that exchanges that id for the full payload. A digest that dropped a load-bearing field is a recoverable mistake rather than a silent one.

retrieve_raw is registered only when digesting is on and at least one wired server is being digested, and it is handed to every Task-mode specialist regardless of that specialist’s tools.mcp: allowlist — it returns bytes the specialist already received, so it grants no reach the allowlist was withholding.

Raw payloads are scratch state. They live under the system temp directory for the life of the process and are never written next to --session-db; if the store cannot be created, mast logs a warning, keeps digesting, and leaves retrieve_raw unregistered.

Some servers return payloads that must reach the model verbatim — a server whose whole job is to return a file’s contents, say. Set no_digest on that entry:

{
"version": 1,
"servers": {
"gke": {"transport": "http", "url": "https://container.googleapis.com/mcp"},
"filesystem": {
"transport": "stdio",
"command": "/usr/local/bin/fs-mcp-server",
"no_digest": true
}
}
}

The opt-out is per server: gke above is still digested. Nothing validates no_digest against anything else in the catalog — declining a size optimization cannot be a misconfiguration.

GET /usage on the attach surface grows a digest_methods block once something has been digested — calls per method and cumulative bytes saved:

"digest_methods": {
"counts": {"structural_json": 14, "passthrough": 2},
"bytes_saved": {"structural_json": 481203, "passthrough": 0}
}

The counters are process-wide, not per session, and they count routed calls: a daemon whose tool responses are all under the threshold reports no block at all, and neither does one running with --mcp-digest=false.

An MCP server that answers 4xx or 5xx usually says why in the response body, and that sentence is normally the whole fix — the IAM permission to grant, the quota metric that ran out. mast reads it and puts it in the error, so a denial reaches the log, the model, and the operator as

403 Forbidden: Permission 'mcp.googleapis.com/tools.call' denied on
resource '//container.googleapis.com/mcp/projects/example' (or it may
not exist).

rather than the bare Forbidden the status line alone gives you. This is automatic for every http server; there is nothing to configure.

Two limits worth knowing. The body is only read when the response declares a JSON content type and stays under 32 KiB — anything else (an HTML error page from a proxy in front of the server, an oversized response) passes through untouched and you get the status line. And an extracted error does not tear down the MCP session: the call fails, the model sees the reason, and the next call reuses the same connection.

The MCP protocol lets a server turn a call around and ask the client for something mid-flight: a question for the operator (elicitation/create), a model completion on the client’s account (sampling/createMessage), or the list of directories the client considers in scope (roots/list). On the 2026-07-28 protocol these arrive folded into the tool result as SEP-2322 input requests; on earlier versions the server sends them as requests of their own. The two shapes travel different routes, so they are refused at different points and the error reads differently — but they are refused.

mast refuses all of them, on both protocol versions. On the older protocol the server sends mast a request, and mast declines to answer it:

mcp: refusing server-initiated roots/list: mast's approval gate covers tool
dispatch, not an input request inside a call already in flight

On the 2026-07-28 protocol there is no request to decline — the server answers the call with a result that asks for input instead — so the call ends when mast declines to act on it:

mcp: tools/call returned an input-required result (roots/list): mast does
not answer input requests, so the call cannot proceed

Either way the tool runs exactly once and the model is told what happened. That second case is worth naming explicitly, because the alternative is not an error: a tool result holding an input request holds no content, and a tool result holding no content is easily rendered to the model as the tool returned nothing. “The server asked a question mast declines to answer” and “the tool had nothing to say” are different facts, and only the first one tells an operator what to change.

This is deliberate and there is no flag to turn it off. mast’s approval gate sits on tool dispatch — an operator approves a specific call, and that call runs. A server-initiated input request happens inside a call the gate has already cleared, so nothing the operator approved covers it. Worse, the SDK’s default behaviour is to answer the request and then retry the original call, so a single approved dispatch can run a server’s tool up to twenty times.

Practically, this means an MCP server that requires elicitation to complete a tool will fail against mast rather than hang or silently proceed. That is the intended trade for an unattended deployment, where there is no operator to answer the question anyway. Supporting elicitation with the gate wired through it is a separate piece of work, not a configuration change.

MCP is not wired under the default echo model, which never emits tool calls — wiring it there would be pure startup cost and would surface credential problems as workload-load failures. The scripted model and real providers do wire MCP. Because a stdio server needs no cloud credentials, you can drive real tool calls fully offline with --model scripted.

Per-workload and per-specialist allowlists narrow which of a server’s tools an agent may call; see tool_catalog. For the recorded-effect outbox, an MCP tool is read-only when a tool_catalog.tools[] override says so, or — failing that — when the server publishes readOnlyHint: true for it in its tools/list response. The override is read first and wins either way. Anything neither has classified is mutating; see the mutation predicate.

A specialist’s allowlist names servers by the key they are declared under in mcp.json:

tools:
mcp:
- server: gke # the key in mcp.json's "servers" map
tools: [get_k8s_resource, get_k8s_logs]
- server: prometheus # no tools: — the whole server

Presence is significant, per axis. No mcp: key inherits every server the workload catalogs; mcp: [] denies them all. They are one character apart and mean opposite things, so write the empty list deliberately — it is how a specialist that needs no cluster access (a synthesizer, a classifier) says so, and since specialists are read-only by default, it is also how such a specialist avoids inheriting a catalog that contains write tools.