Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

MCP Server for LLM Agents

The Fuzzball CLI can run a Model Context Protocol (MCP) server that exposes cluster operations as tools an LLM agent can call. This lets an assistant such as Claude Desktop or an agent runtime observe your workflows, author and run new ones, transfer artifacts through the object cache, and search the cluster’s own documentation – all through the same authenticated connection you already use.

Model Context Protocol is an open standard for connecting LLM applications to external tools and data. fuzzball mcp serve speaks MCP over standard input/output (stdio), so it is launched as a subprocess by an MCP client rather than run interactively.

Prerequisites

  • A reachable, running Fuzzball cluster.
  • A fuzzball CLI that is logged in to that cluster. The MCP server inherits authentication from your active context – run fuzzball login first. No credentials are ever passed on the command line.
  • A selected group in that context. The workflow catalog tools refuse to run without one and tell the agent to ask you to select a group with fuzzball group use <name>. The server picks up the selection on the next call, so it does not need restarting.
The MCP server acts as you. Any tool the agent calls runs with your identity and permissions on the cluster. Grant only the capability tiers the agent actually needs (see Capability tiers below).

Starting the server

The fuzzball mcp command group holds the MCP tooling; serve runs the server:

$ fuzzball mcp serve

Started with no flags, the server registers read-only tools only – the safe default. It reads MCP JSON-RPC messages on stdin, writes them on stdout, and sends all diagnostic logging to stderr, so you normally do not run it by hand. Instead, you configure an MCP client to launch it. Most clients accept a command plus arguments; point them at your fuzzball binary with the mcp serve arguments and whichever capability flags you want to grant:

{
  "command": "fuzzball",
  "args": ["mcp", "serve", "--allow-write", "--allow-exec"]
}

Because authentication is inherited from the active context, the client does not need any tokens or secrets in its configuration.

Connecting a client

Every client launches the same stdio subprocess – your fuzzball binary with the mcp serve arguments – so setup has the same shape everywhere: a command (fuzzball) and its arguments (mcp serve plus any capability flags). Two things apply to all of them:

  • Run fuzzball login first. The server inherits that logged-in context; the client needs no tokens.
  • fuzzball must be on the client’s PATH, or give the absolute path to the binary as the command.

Add the --allow-write / --allow-exec / --allow-destructive flags to the arguments only for the tiers you want to grant (see Capability tiers).

Claude Code

Register the server, granting whichever tiers you need:

$ claude mcp add fuzzball -- fuzzball mcp serve --allow-write --allow-exec

claude mcp list shows connection status, and /mcp inside a session reconnects after a rebuild. Add -s user (before --) to make it available in all your projects, or -s project to share it via a committed .mcp.json.

Codex

Add a server to ~/.codex/config.toml (or a project .codex/config.toml):

[mcp_servers.fuzzball]
command = "fuzzball"
args = ["mcp", "serve", "--allow-write", "--allow-exec"]

Or register it non-interactively:

$ codex mcp add fuzzball -- fuzzball mcp serve --allow-write --allow-exec

OpenCode

Add a local server under the mcp object in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fuzzball": {
      "type": "local",
      "command": ["fuzzball", "mcp", "serve", "--allow-write", "--allow-exec"],
      "enabled": true
    }
  }
}

Pi

Pi does not support MCP natively, so an MCP extension for Pi is a prerequisite – install one before continuing. Once the extension is in place, configure the Fuzzball server through it as a stdio server with the command fuzzball and the arguments mcp serve (plus any --allow-* flags).

Claude Desktop

Edit claude_desktop_config.json (Settings -> Developer -> Edit Config) and add the server under mcpServers:

{
  "mcpServers": {
    "fuzzball": {
      "command": "fuzzball",
      "args": ["mcp", "serve", "--allow-write", "--allow-exec"]
    }
  }
}

Restart Claude Desktop after editing.

Cursor

Add the server under mcpServers in ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "fuzzball": {
      "command": "fuzzball",
      "args": ["mcp", "serve", "--allow-write", "--allow-exec"]
    }
  }
}

Capability tiers

Tools are grouped into tiers by how much power they hand the agent. Read-only tools are always available; the more powerful tiers are opted in with launch flags, in ascending order of risk:

FlagTierWhat it unlocks
(none)ReadObserve workflows, nodes, volumes, objects, secrets (metadata only), catalog entries, and identity; search and fetch docs; validate a Fuzzfile without running it.
--allow-writeWriteState changes that are not arbitrary compute: upload artifacts to the object cache (object_put), download them to a local file (object_download), and create or change persistent endpoints (endpoint_create, endpoint_update). Reading object content inline (object_get) stays in the read tier.
--allow-execExecRun arbitrary cluster compute: start a workflow, run a one-off command, exec into a running job, or start a catalog workflow.
--allow-destructiveDestructiveCancel a workflow (workflow_stop), delete object-cache entries (object_delete), and delete persistent endpoints (endpoint_delete).

Flags are additive, so grant exactly the tiers you need. FUZZBALL_ALLOW_WRITE, FUZZBALL_ALLOW_EXEC and FUZZBALL_ALLOW_DESTRUCTIVE grant those tiers to the server as the flags do, which is how an MCP client’s configuration often sets them:

A read-only server, which is the safe default:

$ fuzzball mcp serve

Allow the agent to run workflows and stage or retrieve artifacts:

$ fuzzball mcp serve --allow-write --allow-exec

Full access, including cancel and delete:

$ fuzzball mcp serve --allow-write --allow-exec --allow-destructive

Each tool also advertises the standard MCP annotations (readOnlyHint, destructiveHint, and so on) so a well-behaved client can warn you before invoking a mutating tool.

What the agent can do

The tool set is built around a compose -> run -> examine -> iterate loop. Rather than listing every tool, the tables below group them by tier so you can see what each launch flag grants.

Read (always available)

AreaTools
Workflowsworkflow_list, workflow_describe (pass include_spec to get the workflow’s specification as JSON; omitted by default because it is large and costs an extra call; stage_name describes one stage), workflow_log, workflow_log_reduce (a digest of a log too large to read — see below), workflow_events, workflow_endpoints, workflow_score, workflow_wait
Endpointsendpoint_list (filter by persistent, name and cluster_id), endpoint_get
Authoring pre-flightworkflow_validate (check a Fuzzfile without spending compute – see below)
Compute & clustersnode_list, node_show, cluster_resources, cluster_list, cluster_get
Schedulerqueue_show (your queued allocations), workflow_why (typed reason a workflow is pending; stage_name and max_results narrow a wide one, and only the allocations asked for are sent to the scheduler)
Storage & datavolume_list, volume_info, volume_provisioner_list, volume_provisioner_get (see below), object_list, object_describe, object_get (retrieve content inline, bounded — see below), secret_list, secret_get (metadata only – secret values are never exposed)
Identity & configcontext_show, organization_get, organization_member_list, group_list, group_get
Catalogcatalog_list, catalog_get, catalog_render
Documentationdocs_search (returns {"results": [...], "total": N}; no matches is an empty array, not a sentence), docs_get (also returns a worked example Fuzzfile verbatim when given its .fz href, and takes offset/length to window a long page)

context_show reports the context the tools act in. Under fuzzball mcp serve that is your local CLI context. On Fuzzball’s hosted agent, which runs these tools on the server for each user, it is the calling user’s identity and the ID of their conversation’s group.

catalog_get, catalog_render and catalog_start accept an entry’s name or its UUID. A name is looked up with the same listing call catalog_list uses; a UUID is not. If that listing fails, the tools given a name say that only the lookup by name failed and that the entry may still be reachable by its UUID.

catalog_list and catalog_get also link each entry to the web UI: viewUrl opens the entry, and editUrl opens it in the editor. Provider-owned entries have no editUrl, because the web UI does not let them be edited. The links are built from the ui. host that matches your cluster’s api. address, under your active account. If the web UI is not at that host, for example because the UI or API ingress uses a custom hostname, set the UI’s scheme and host with the --ui-url flag or the FUZZBALL_UI_URL environment variable:

$ fuzzball mcp serve --ui-url https://fuzzball.example.com

Without an override, the links are left out when the cluster address does not have the api.<domain> form. They are always left out when no account is active.

volume_provisioner_list shows the storage provisioners a workflow’s volumes: can use, and volume_provisioner_get describes one by name or UUID. Their descriptions explain how to write a use: binding for each. A provisioner is reported with its name, description, status, driver type, whether it is node-local, annotations, cost, segment and its access, create and ephemeral policies. The rest of the driver configuration (server addresses, paths, cloud resource identifiers) is never returned. A lookup by name reads at most 100 pages of provisioners; if it stops before the end of the list, the error says how many pages it read, and passing the provisioner’s UUID always works.

The list is not filtered by access policy: every provisioner in the organization appears, and access is enforced when a workflow uses a volume. Each record also carries callerAccess, the tool’s reading of the policies for you and your selected group. It is advisory, and is null when your email or group could not be determined.

workflow_validate

workflow_validate renders the Fuzzfile template and parses it locally, then asks the cluster to run the checks a real submission gets: schema, permissions such as storage provisioner access, and schedulability. It returns valid, plus errors and warnings arrays when they have entries (an absent key means none):

  • valid: false means the Fuzzfile did not parse or the cluster rejected it, for example because you lack access to a storage provisioner the workflow uses. errors gives the reason.
  • valid: true means the cluster accepted it – unless warnings has an entry starting with server validation unavailable. In that case the cluster gave no verdict on the workflow (for example, it was unreachable, a proxy in front of it answered instead, or your login has expired), so only the local parse counts and workflow_start may still reject the workflow.

On a federated cluster, validation scores the workflow the way a submission would. If the workflow attaches to persistent endpoints, only the member cluster that owns them is scored; otherwise validation passes if any member cluster would accept the workflow. Pass cluster_id to validate against a specific cluster, as workflow_start with the same cluster_id would target it; validation rejects the workflow if its persistent endpoints belong to a different cluster. On a cluster that is not federated, omit cluster_id: validation ignores it, but workflow_start rejects it.

On a federated cluster, a server validation unavailable entry can also mean that every member cluster that was scored returned an error. That may be a rejection rather than an outage; the warning says so when it is.

Write (--allow-write)

ToolPurpose
object_putUpload a local artifact to the object cache.
object_downloadWrite an object-cache artifact to a local file (for large or binary objects, or anything past object_get’s inline limit).
endpoint_createCreate a named persistent endpoint.
endpoint_updateChange an endpoint: make it persistent, or change a persistent endpoint’s name, type, scope or update strategy.

Exec (--allow-exec)

ToolPurpose
workflow_startSubmit a Fuzzfile (as a string or a path).
runRun a structured one-off command (image, command, resources, environment, mounts). Pass dry_run to get the generated Fuzzfile back validated instead of started — see below.
workflow_execRun a command inside an existing job’s container.
catalog_startRun a workflow catalog entry directly with parameter values.

A workflow whose service endpoint is marked persistent: true attaches to your persistent endpoint of the same name and cancels the workflow currently attached. When workflow_start or catalog_start would do that, nothing is submitted: the tool returns the affected endpoints and workflows instead, and must be called again with confirm_endpoint_takeover=true once you have confirmed. A workflow the check rejects is reported with the reason and not submitted. If the check cannot run at all, the tool returns an error and submits nothing; calling it again with confirm_endpoint_takeover=true submits without the check.

run with dry_run

dry_run returns the Fuzzfile run would have submitted, having validated it, and starts nothing. It replies with {"workflow": "<yaml>"} — the YAML as a string so it stays paste-able — plus a warnings array only when the validator actually returned warnings. A clean dry run carries no warnings key at all, so treat its absence as “none” rather than waiting for an empty list.

Validation is done by the server, using the same call workflow_validate makes, so a dry run rejects anything a real start would reject rather than only what parses. A value like memory: "not-a-size" is a validation failure, not a preview. That means dry_run needs a reachable cluster; it is not an offline formatter.

When cluster_id is set, the schedulability half is evaluated against that cluster, matching what starting the workflow would do — so a dry run cannot bless a workflow the target federate would refuse, or refuse one it would accept.

Destructive (--allow-destructive)

ToolPurpose
workflow_stopCancel a running workflow.
object_deleteDelete an object-cache reference and all of its versions.
endpoint_deleteDelete a persistent endpoint, cancelling the workflow attached to it.

All destructive tools additionally require confirm: true. Granting the flag makes the tool available; confirming states the intent for a specific call, so an agent cannot reach an irreversible operation through a malformed or half-built argument list. workflow_stop’s separate force parameter escalates a graceful cancel to an immediate stop — it is not a confirmation and does not substitute for one.

Prompts

Beyond tools, the server publishes guided prompts for common tasks (write_workflow, inspect_workflow, research_loop, and – when the server is started with --allow-exec – run_command) that a client surfaces as ready-made starting points. research_loop drives an iterative experiment loop: it frames a measurable goal with you, then authors a workflow and runs it repeatedly, improving toward that goal.

Workflow outputs must egress to the object cache. The agent has no tool for reading files out of a storage volume, so a workflow that writes results only to a volume produces nothing the agent can retrieve. Any workflow authored for an agent should egress its results to the object cache, where object_get can fetch them. This guidance is also baked into the relevant tool descriptions and prompts so the agent follows it automatically.

Response and query semantics

These apply across every tier: what a tool hands back, how to narrow a listing, and the two places where the answer is not the literal value you asked for.

Response shape

List tools return a JSON object, never a bare array:

{
  "clusters": [ { "id": "...", "name": "..." } ],
  "total": 1
}

total is the number of items in the array, so a query that matches nothing returns {"clusters": [], "total": 0} rather than an empty object. That distinction matters to an agent: “no results” and “the request was rejected” must not look the same.

Two controls keep replies inside a model’s context budget:

  • fields – an optional array naming the top-level keys to keep on each item, for example ["id", "name"]. Naming a field that does not exist returns an error listing the valid names. Either spelling works on the proto-backed list tools – create_time and createTime select the same key – and the reply always uses the lowerCamelCase form. Three tools build their rows by hand and accept the lowerCamelCase spelling only: workflow_list, workflow_events, and workflow_endpoints. (docs_search takes no fields argument.)

    Omitting fields returns every field on most tools. node_list is the exception: it returns a documented summary by default, because a node’s full resource report – NUMA topology, socket maps and per-device plugin inventory – runs to kilobytes per node and is rarely what you asked the question for. Name it explicitly (fields: ["id", "resource"]) to get it. Anything a default omits is still reachable this way.

    Separately, a few tools drop a field entirely before replying (catalog_list removes keyArt, which is thumbnail image data). That is a different thing from a default: asking for one of those is an error saying so, rather than a page of empty objects.

  • A size cap. If a reply would exceed the limit, the tool returns as many items as fit and adds "truncated": true, "matched": <count> (how many matched in total), "omitted": <count>, and a truncationNote suggesting how to narrow the request. Responses are never silently cut short.

Output keys are lowerCamelCase (createTime, workflowId). Tool arguments stay snake_case (max_results, order_by).

Filtering

Most list tools accept an AIP-160 filter. Use = for an exact match and : for a substring, so name = "prod" and name:"pro" differ. A bare word with no comparator is rejected: the server’s parser accepts it but produces no condition, so the call would return the whole collection and look like a successful filter.

Filter field names are snake_case (display_name, create_time) even though the response keys are lowerCamelCase. Each tool’s filter description lists the fields it accepts, because the accepted set is per-tool and narrower than what the tool returns – volume_list, for instance, filters only on name, display_name and description.

cluster_list takes no filter or order_by: the control plane returns every registered cluster and ignores both, so match on the returned name yourself.

Results too big for the context window

A workflow log or an output artifact can be larger than any context window. The agent chooses how to read it; the server enforces a ceiling that no argument can raise.

Nothing is ever silently truncated. A result over the limit comes back as a refusal carrying "tooLarge": true, the size, the capBytes that applied and a strategies list. That is deliberate: a truncated result reads exactly like a complete one, so a model answers from the fragment with full confidence and nobody finds out the part that mattered was cut off.

Three outputs are bounded rather than refused, and all say so: the log tails workflow_wait attaches with tail_lines, which ride on a status result whose status must not be lost; workflow_describe, whose status has no smaller call to come back through; and workflow_exec’s output, because by the time it would be refused the command has already run. All are described below.

A refusal is also marked outside its text, in the result’s _meta as "fuzzball.ciq.com/tooLarge": true, so an MCP client can tell a real refusal from a log that happens to contain one. Where only the text is seen, as in a hosted agent session, the strategy line below makes the same distinction: a real refusal never has one, and a result that does was not refused.

Per-call arguments (max_inline_bytes, max_bytes) can only lower the read ceiling of 256 KB: a value above it is lowered to it and the response says so. Either may still raise a tool’s own smaller default — object_get starts at 64 KB, and its own tool description tells you to raise max_inline_bytes when the object is only slightly over.

There is a second, larger ceiling on what the result becomes once it is encoded, and it is the one a refusal from that encoded check reports as capBytes; a tool’s own refusal, made before encoding, reports the read limit that applied to it instead (64 KB for an object_get at its default, for example). The two measure different things: the read ceiling bounds the bytes taken from the source, while a JSON envelope escapes them on the way out, and escaping expands. A control character becomes a six-byte \u0000; a quote or a newline doubles. So a log of ANSI escape sequences, or an object that turns out to be binary, can pass the read ceiling and still be far too large by the time it reaches you — which is what the encoded ceiling catches. Ordinary text is unaffected: a read at the full 256 KB of plain text is returned, not refused. Sizes are counted as the client decodes them, so each byte that is not valid UTF-8 counts as the three bytes of the replacement character it arrives as. Every part of a result counts toward the ceiling, not only its text: structured content, an image, an embedded resource or metadata is counted at its JSON size, and a part that cannot be measured counts as over the ceiling.

In a hosted agent session the encoded ceiling is lower, 120 KiB, so that every result fits whole in what the session hands the model. A read that fits the 256 KB read ceiling but encodes past 120 KiB is refused there, with capBytes saying 122880, and the same strategies apply: narrow it, or read it in windows.

A refusal’s strategies are the arguments that tool accepts, taken from its own input schema rather than a fixed list. workflow_log is offered grep, probe, head, lines and a byte range; object_get its byte range; node_list only fields, which is its one lever; docs_search top_k and workflow_events max_events, each with its smallest useful value, since 0 means the default or all. A tool that takes nothing able to narrow its result says so plainly, rather than suggesting an argument it does not have — a retry of the same call would only be refused again. A tool that writes, runs or deletes is offered no strategy at all: its result is measured after the call has run, so the refusal says the call may already have taken effect and to check what it did with a read tool, not to call it again. A run with dry_run starts nothing, and its refusal says so.

Reading a large object

object_get is bounded by max_inline_bytes, 64 KB by default. Over that, either read it in windows with offset and length — the response returns nextOffset so you can walk through it, and complete once you have reached the end — or use object_download to write it to a local file. For a binary object pass encoding: "base64": content is then the window’s bytes in base64 and encoding says so, the window is never moved to a character boundary, and every byte is returned, which matters in a hosted agent session where object_download is not available. docs_get takes the same two arguments for the handful of documentation pages that are long, though its keys differ: text and totalBytes where object_get uses content and contentLength. A negative offset or length is refused rather than interpreted. Where you pass an explicit max_inline_bytes, a larger length does not override it — and when length is above the 256 KB ceiling the window is shortened to it and the response says so in limitLowered, so a short page can be told from a clamped one.

An offset that lands in the middle of a multi-byte character is moved forward to the next character boundary; the response reports the offset it actually served, and offsetAdjusted says it was moved. A window narrower than the character that starts it still returns that whole character rather than nothing, so paging always advances.

Usually this only arises from an offset chosen by hand, because a window over text ends on a boundary. It is not guaranteed, though: content that is not valid UTF-8 has no boundaries to find, so a window over it need not end on one and the next nextOffset can land inside a character that follows. A log holding a binary blob or Latin-1 text with a multi-byte tail will do it. The response always tells you what it served, so a loop that believes the offset it is given rather than assuming it got what it asked for is correct either way.

Over content that is not UTF-8, a small length can be served a byte at a time: where the alignment cannot find a boundary inside the window it returns a single byte rather than risk splitting a character. How often that happens depends on the bytes, not only on the length — 500 bytes of one repeated invalid lead byte took 497 calls at length: 4, while 500 uniformly random bytes took 134 and Latin-1 text took 134, because any ASCII byte at the end of the window lets the full length through. Ask for 5 or more and the worst case goes away (100 calls at length: 5).

One caveat on binary specifically: bytes that an offset has to skip to reach a boundary are not returned, and are not reachable by asking again — requesting the same offset skips them again. So a walk over content that is not UTF-8 can report complete having returned fewer bytes than the content holds. Measured on uniformly random bytes at length: 1, 403 of 500 came back. Use encoding: "base64" (or object_download) for binary you need intact.

An offset falling inside the content’s last character is the one case with no boundary to move forward to. For object_get and docs_get those bytes are served rather than refused, and returnedBytes tells you how many came back. Those bytes cannot arrive intact, though, because the payload is a JSON string and an incomplete character is replaced with U+FFFD on the way out. offsetAdjusted says so. Lower the offset to read that character whole.

The two tools differ in how much of the fragment they hand over: object_get serves the whole remainder in one go, while docs_get honours a smaller length and so may need one more call to finish. Follow complete rather than assuming a fragment ends the read.

workflow_log cannot reach that shape: the log it returns is always newline-terminated, so there is a boundary to move forward to at every offset, and such an offset is reported as moved rather than as a fragment. The two bytes inside a final multi-byte character are therefore not retrievable on their own from a log — but they are not lost either, since the offset that starts that character returns it whole.

All three windowed reads — object_get, docs_get and workflow_log with offset/length — report the offset actually served, so one paging loop works for all three. The rule has three cases and a loop needs all of them:

  • complete is true — stop, you have everything the tool can give.
  • complete is false and nextOffset is present — read again from it.
  • complete is false and nextOffset is absent — stop. There is nothing at a higher offset, and the reason is in the response: for workflow_log this is the truncated-fetch case, where sourceTruncated says the log itself continues past what could be read and that paging further will not reach it.

That third case is the one worth coding for. Continuing on complete alone never terminates there, and treating a missing nextOffset as zero restarts the walk from the beginning.

Two further differences are worth knowing rather than discovering:

  • At an offset inside the content’s final character, described above, they answer differently: object_get and docs_get serve the tail with a note, workflow_log moves past it.
  • workflow_log measures offsets over the log as it returns it – after grep, lines, head or tail have narrowed it, and with a trailing newline added. totalBytes describes the whole log that was read. So the two are not on the same scale and should not be compared or subtracted: with a grep that matches little, nextOffset ends far below totalBytes; with no filter and a log that does not end in a newline, it ends one byte above it. Drive the loop with the three-case rule above, not by comparing those two numbers.

Past the end of the content the three differ too: object_get and docs_get refuse the read and name the size, workflow_log returns zero bytes. A loop following the rule above never reaches either, because it stops at the last offset that returned something.

object_download is write-tier and only present when the operator passed --allow-write; it is never present in a hosted agent session, which has no local filesystem, so windowed reads are the route there.

Logs attached to other results

workflow_wait can attach a log tail to its result with tail_lines. Those logs are a convenience on a status document, not a read, so they are bounded to the same 96 KB as a log read. Failed jobs are read first, then the rest by name; stages still pending (which have no log yet) are skipped. Each job gets its tail_lines until the room runs out: the job that does not fit is cut to what is left, and the jobs after it are not read. A wait reads at most one job per 512 bytes of the bound, whatever the jobs logged. A cut tail carries a note that says so, and the result ends with a strategy: bounded line naming the job that was cut and the jobs not read (up to 20, then how many more), and why they were not read: the room ran out, a job before them was cut, or the read cap was reached; when any tail was kept, the logs end with a note that also says jobs were not read. A job whose log cannot be opened, or that has printed nothing, adds nothing and is not named. A tail that does not fit the room left keeps its END — the part you asked for — in whole lines where a line fits, and drops the earlier lines, keeping the header of the first stage it keeps; the note distinguishes a byte limit from a stage whose log stream failed part-way, and names both when both happened — for a wide workflow the note is the signal to read properly with workflow_log. The status itself is never refused: the workflow’s error text is cut to 8 KiB with a note, the tails get what the result limit leaves after it, and if they still do not fit they are left out, with a strategy line saying so. A workflow id over 1 KiB is refused before the wait starts, since the result echoes it.

A wide workflow’s status

workflow_describe is never refused for size: the status is what was asked for, and no smaller call returns it. When the whole description does not fit the result limit, it leaves parts out in this order until it fits – the specification asked for with include_spec, then every stage row that did not fail, then the remaining rows’ details and dependency edges (error text is cut then too: the workflow’s to 8 KiB, each stage’s to 1 KiB), and finally failed rows past the first 64, 32, and so on. Once rows are left out, every row is counted by status under stageCounts, and the stages not listed are named under unlistedStages (up to 64, with unlistedStagesNotNamed counting the rest). The workflow’s own fields always come back, its error text cut to 8 KiB once details are dropped. A strategy: trimmed line names what was left out; describe one stage with stage_name – every rank of it, finished ones included, up to the same row caps – read its timeline with workflow_events and its output with workflow_log. A specification that could not be read, or is not valid JSON, keeps its own note rather than being reported as too large.

Reading a large log

workflow_log defaults to the last 200 lines. When that is not the right slice:

ArgumentUse
probeReturn the size and line count only, no content, so the strategy is chosen from a number rather than a guess. It also names the largest read this server’s result limit allows
grepKeep only lines matching a regular expression (RE2). Usually the right first move: `error
headRead the START of the log — the arguments a job was given, the image it pulled — which the default tail cannot reach
offset / lengthPage through whatever the above leave. On their own they window the WHOLE log, not the default tail – which is what makes them a usable follow-up to a refused read. Without name the window applies to each stage, so page one stage at a time
linesKeep only the last N — of the matches, when combined with grep. The 200 default applies here too, so a grep with no lines returns the last 200 matches; pass lines: -1 for every match
max_bytesSet the limit for this call. On a read of ONE named stage it may raise this tool’s 96 KB default up to the 256 KB server ceiling, or lower it. On an all-stages read it can only lower: the combined view is fixed at 96 KB and a larger value is ignored, so a read refused there is not retried with a bigger number — name a stage, or narrow with grep, lines or head. A stage that does not fit is named in a closing note rather than dropped silently

grep runs before head or lines, so “the last 50 lines” means the last 50 that matched, not the matches among the last 50 lines.

A grep that matched nothing is an answer, not an absence, and comes back with the same accounting as any other narrowed read — so “0 of 400,000 lines matched” can be told apart from “this job has not logged anything”, which are very different facts to act on.

probe on a workflow with a very large number of stages lists the first of them and reports how many it left out, rather than returning a stage list that is itself over the result ceiling. Name a stage to probe the rest.

When you name a single stage AND narrow it here — with grep, head or a byte window — the result reports totalLines and returnedBytes (plus matchedLines when a grep ran), so an answer drawn from twelve lines out of four hundred thousand can be read as such.

lines on its own is the exception, and deliberately: it is served by the cluster, which returns only that many lines, so there is no whole-log count to report — totalLines would be the number you asked for, a constant dressed up as a measurement. It comes back as plain text. Combine it with grep and you get the envelope, because the pattern has to search the whole log to find the matches lines then bounds.

Those counts describe what was READ, and a read is bounded: when the log was larger than the read budget the result carries sourceTruncated, and when it had more lines than one read can index it carries lineLimitReached. Either one makes every count beside it a floor, and complete is then false even if the window itself reached the end of what was read — a byte range cannot page past the part that was never read, so narrow instead, or reduce the log with workflow_log_reduce, which reads every line. A tail read that hit the budget kept the log’s end; every other read kept its start, and the note says which.

A plain read of one stage returns the log as text with no envelope, which keeps existing callers’ parsing intact. Without name the tool reads every stage and returns them under === stage === headers; that shape carries no per-read counts, so narrow to one stage when you want them. A stage too large for that combined view is never cut: it is left out and named in the closing note, and if no stage fits the call is refused with the arguments that would read it.

Reducing a log instead of reading it

A very large log is read up to a fixed budget and no further. When that happens the result says so — truncated on a probe, sourceTruncated on a narrowed read, a closing note on an all-stages read — and a grep that found nothing over a truncated log says plainly that the remainder was not searched, rather than reporting an absence it cannot vouch for.

That budget is 64 MiB, and it applies to the whole call rather than to each stage: an all-stages read of a wide array job spends it across the ranks, and a stage it cannot reach within the budget is reported as unread rather than silently omitted. It bounds what the server holds while reading, which is a different limit from the 256 KiB ceiling on what comes back (lower in a hosted session) — a grep legitimately reads far more than it returns.

workflow_exec keeps at most 48 KB of each of stdout and stderr (less on a server whose result ceiling is lower), counted as they are encoded, so the result always fits even in a hosted session and is never refused after the command has run. A command that writes more — cat on a large file — has its output cut and says so in truncated and in a strategy: bounded line; the exit code is always complete.

For “why did this 12-hour job fail?”, workflow_log_reduce reads the log and returns a digest: total size, a tally of error, warning, panic and out-of-memory lines, and the distinct messages that dominate the log, each with an id, a count, a skeleton and firstSeen, where its first occurrence is. A source block names what produced the digest: the workflow, the stages and ranks reduced, grep and top_n.

No free text the workload wrote enters the conversation. A skeleton is a sequence of tokens from a closed set, one space apart (a workload can print a placeholder such as <n> itself, so it chooses among the tokens, never its own text): placeholders for the parts that vary (<n>, <hex>, <uuid>, <time>, "<str>"), a fixed vocabulary of severity and log-level words written in lower case (error, failed, panic, warn, info, …), and <w>, which stands for any run of anything else – other words, punctuation, non-ASCII characters, control bytes. So ERROR worker 3f2b… lost after 12 retries reports as error <w> <uuid> <w> <n> <w>. The order of those tokens still comes from the log – a low-rate channel a workload could use to spell out bits – so the tool stays untrusted. Two messages with the same skeleton stay two rows, told apart by id and firstSeen. A firstSeen past the first 4,194,304 lines of a stage carries pastReadLimit, because a workflow_log offset read cannot reach that far.

Severity words are counted in the first 1,600 bytes of each line, which longLines reports when it matters, and scanning stops after 20 seconds for the call – time spent fetching the log is not counted; a digest that stopped says so in scanStopped, and its counts are floors.

It reads the log in full whenever the call’s read budget allows, which covers essentially every real job. A log large enough to exhaust that budget is described from the prefix that was read, and the digest says so in sourceTruncated, naming the stages affected. When that field is present every number beside it — totalLines, totalBytes, the severity tallies and the message counts — is a floor, not a total: the pattern in the prefix is the real finding, and a count read as exact will be too low. A stage that could not be read at all is accounted for rather than quietly missing: one that failed — no container, a reset stream — is named in unreadable with its reason, and stages skipped because the call’s budget was already spent are counted in unreadStages with a single unreadReason. They are separated because the reasons are different and only one of them is worth retrying: a narrower call, or one naming fewer stages, will reach the skipped ones.

Messages are counted by their normalised form — numbers (with or without a unit), hex, UUIDs, timestamps and quoted strings are normalised away before counting — so one error raised forty thousand times with a different id each time is one row with a count of forty thousand.

The digest is computed deterministically, not written by a model. A summarising pass would be a second place a prompt buried in the log could steer, and a tally cannot be talked into saying the job succeeded.

The usual pattern is to reduce first, then read the messages that matter with workflow_log: pass firstSeen’s name (and rank), with its offset and bytes as offset and length, to read exactly that line. That read is an ordinary, visible workflow_log call, so the line’s text enters the conversation only when the agent asks for it, with its own strategy line.

A grep pattern is limited to 512 bytes and to a modest compiled size, which refuses only pathological constructions such as (x?){1000}. It searches the first 64 KiB of each line, and stops after 20 seconds of searching for the whole call; linesClipped and searchStopped say when either applied, and the counts are then floors.

Which strategy answered

workflow_log, workflow_log_reduce, workflow_exec, object_get, docs_get, and workflow_wait when it attaches log tails, follow their result with one more line, beginning strategy:, that says how it was produced:

strategy: grep: the last 200 lines matching "panic|fatal" of the log of stage train; the rest of the source is not in this result

The words after strategy: are all, tail, head, grep, range or probe for a log, reduction for a digest, whole or range for a page or object, whole or bounded for a command’s output, bounded for a wait’s log tails, and trimmed for a workflow_describe that left parts out to fit. A read known to cover the whole log – a tail or head that asked for more lines than the log has – says “that is the whole log”. Anything short of the whole source says so, and why: the read budget (and which end of the log was kept), the line limit (a tail read with lines keeps the log’s last lines; any other read, a grep with lines included, its first), or a search that reached its time limit. The line is a separate text block after the result, so a client that reads the first block sees the result unchanged. In a hosted agent session it is recorded in the conversation with the result, so whoever reads it later can tell an answer drawn from a tail or a digest from one drawn from the full log. A refused read carries no strategy line; its refusal lists the strategies that would fit. The strategy line is always the last line of the result, after everything the workload wrote, so a line that merely looks like one inside a log is not it.

Workflow status words

Every tool that reports a workflow’s status – workflow_list, workflow_describe, workflow_endpoints, workflow_wait, workflow_stop – uses the same six words, and they match what fuzzball workflow list prints:

pending · started · finished · errored · canceled · down

The underlying API enum is stage-oriented (STAGE_STATUS_*) and never reaches the agent. Two of those spellings are worth noting: a failed workflow is errored, not failed (failed is job-level vocabulary), and a running one is started. down is an autoscaled service scaled to zero — not terminal, but nothing is listening.

When filtering, workflow_list additionally accepts running as an alias for started and failed as an alias for errored, plus the shorthand active for “pending or started” — so “what is running right now?” is a single call.

One tool reports a different vocabulary, deliberately. workflow_why explains queued allocations, whose status is a separate and larger set (CREATING, RUNNING, FINISHED, CANCELLED, PREEMPTED and others) — note CANCELLED, with two Ls, against a workflow’s canceled. Those values are passed through as the scheduler reports them rather than mapped onto the six words above, because they are not the same thing and flattening them would lose the distinction. When workflow_why says a job is waiting for a dependency to reach a status, that status is an allocation status.

Every tool that starts a workflow — run, workflow_start, catalog_start — returns the new workflow’s id under workflowId, so the value can be handed to workflow_describe, workflow_log or workflow_wait without checking which tool produced it. Note that workflow_stop is asynchronous: the status it reads back is usually still started, and the workflow settles to canceled shortly after.

Documentation source

The documentation tools (docs_search, docs_get) serve the connected cluster’s own documentation site. The base URL is derived from your active context automatically. If your cluster publishes its docs at a different location, override it with the --docs-url flag or the FUZZBALL_DOCS_URL environment variable:

$ fuzzball mcp serve --docs-url https://docs.example.com/

The worked example Fuzzfiles are part of that site, so they need no separate tool: pass an example’s .fz href to docs_get and it comes back verbatim, ready to adapt and validate.

docs_get reads the rendered page, so the text an agent sees matches what you see. Where a page presents alternatives in tabs – Kubernetes Operator or Docker Compose, for instance – each tab is returned under its own ### Tab: <name> heading, so the agent follows one set of instructions rather than a blend of both.

The CLI checks the docs site’s certificate against your system trust store only: --ca-file, FUZZBALL_CA_FILE and a CA stored with fuzzball context create --ca-cert do not apply to it. If the site’s certificate is signed by a private CA, add that CA to the system trust store, or point --docs-url at a copy whose certificate the store already trusts. Fuzzball’s hosted agent trusts CONVERSE_TOOL_CA_FILE in addition to the system store.

Certificate errors

When a tool call fails because the cluster’s TLS certificate does not verify, the error the agent receives says that retrying will not help, names the settings to check, and includes the certificate check’s own message, which tells the cases apart:

  • x509: certificate signed by unknown authority: the CA that signed the cluster’s certificate is not trusted.
    • For the CLI, store the CA on your context with fuzzball context create --ca-cert, which the CLI then trusts alongside the system store (it does not install the CA system-wide, so it does not reach the documentation tools), or pass --ca-file or FUZZBALL_CA_FILE for one run, which the CLI trusts instead of the system store and in preference to a stored CA.
    • For Fuzzball’s hosted agent, set the CONVERSE_TOOL_CA_FILE environment variable on the orchestrate service to the path of the CA’s PEM file. It is trusted alongside the system store and covers tool calls, object transfers and the documentation tools, and a replaced file is picked up without a restart. Docker Compose deployments set it already, to the CA the stack generates; Kubernetes deployments trust the cluster’s own CA through the operator’s trust bundle.
  • A certificate for another host, or an expired one: no CA setting fixes this. The cluster’s administrator has to reissue the certificate.

The documentation tools report the same failure for their own fetches, worded for their trust as described in Documentation source.