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.
- A reachable, running Fuzzball cluster.
- A
fuzzballCLI that is logged in to that cluster. The MCP server inherits authentication from your active context – runfuzzball loginfirst. 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).
The fuzzball mcp command group holds the MCP tooling; serve runs the server:
$ fuzzball mcp serveStarted 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.
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 loginfirst. The server inherits that logged-in context; the client needs no tokens. fuzzballmust be on the client’sPATH, 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).
Register the server, granting whichever tiers you need:
$ claude mcp add fuzzball -- fuzzball mcp serve --allow-write --allow-execclaude 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.
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-execAdd 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 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).
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.
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"]
}
}
}
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:
| Flag | Tier | What it unlocks |
|---|---|---|
| (none) | Read | Observe workflows, nodes, volumes, objects, secrets (metadata only), catalog entries, and identity; search and fetch docs; validate a Fuzzfile without running it. |
--allow-write | Write | State 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-exec | Exec | Run arbitrary cluster compute: start a workflow, run a one-off command, exec into a running job, or start a catalog workflow. |
--allow-destructive | Destructive | Cancel 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 serveAllow the agent to run workflows and stage or retrieve artifacts:
$ fuzzball mcp serve --allow-write --allow-execFull access, including cancel and delete:
$ fuzzball mcp serve --allow-write --allow-exec --allow-destructiveEach 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.
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.
| Area | Tools |
|---|---|
| Workflows | workflow_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 |
| Endpoints | endpoint_list (filter by persistent, name and cluster_id), endpoint_get |
| Authoring pre-flight | workflow_validate (check a Fuzzfile without spending compute – see below) |
| Compute & clusters | node_list, node_show, cluster_resources, cluster_list, cluster_get |
| Scheduler | queue_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 & data | volume_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 & config | context_show, organization_get, organization_member_list, group_list, group_get |
| Catalog | catalog_list, catalog_get, catalog_render |
| Documentation | docs_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.comWithout 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 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: falsemeans the Fuzzfile did not parse or the cluster rejected it, for example because you lack access to a storage provisioner the workflow uses.errorsgives the reason.valid: truemeans the cluster accepted it – unlesswarningshas an entry starting withserver 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 andworkflow_startmay 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.
| Tool | Purpose |
|---|---|
object_put | Upload a local artifact to the object cache. |
object_download | Write an object-cache artifact to a local file (for large or binary objects, or anything past object_get’s inline limit). |
endpoint_create | Create a named persistent endpoint. |
endpoint_update | Change an endpoint: make it persistent, or change a persistent endpoint’s name, type, scope or update strategy. |
| Tool | Purpose |
|---|---|
workflow_start | Submit a Fuzzfile (as a string or a path). |
run | Run 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_exec | Run a command inside an existing job’s container. |
catalog_start | Run 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.
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.
| Tool | Purpose |
|---|---|
workflow_stop | Cancel a running workflow. |
object_delete | Delete an object-cache reference and all of its versions. |
endpoint_delete | Delete 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.
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, whereobject_getcan fetch them. This guidance is also baked into the relevant tool descriptions and prompts so the agent follows it automatically.
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.
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_timeandcreateTimeselect the same key – and the reply always uses thelowerCamelCaseform. Three tools build their rows by hand and accept thelowerCamelCasespelling only:workflow_list,workflow_events, andworkflow_endpoints. (docs_searchtakes nofieldsargument.)Omitting
fieldsreturns every field on most tools.node_listis the exception: it returns a documented summary by default, because a node’s fullresourcereport – 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_listremoveskeyArt, 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 atruncationNotesuggesting 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).
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.
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.
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:
completeis true — stop, you have everything the tool can give.completeis false andnextOffsetis present — read again from it.completeis false andnextOffsetis absent — stop. There is nothing at a higher offset, and the reason is in the response: forworkflow_logthis is the truncated-fetch case, wheresourceTruncatedsays 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_getanddocs_getserve the tail with a note,workflow_logmoves past it. workflow_logmeasures offsets over the log as it returns it – aftergrep,lines,headortailhave narrowed it, and with a trailing newline added.totalBytesdescribes the whole log that was read. So the two are not on the same scale and should not be compared or subtracted: with agrepthat matches little,nextOffsetends far belowtotalBytes; 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.
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.
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.
workflow_log defaults to the last 200 lines. When that is not the right slice:
| Argument | Use |
|---|---|
probe | Return 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 |
grep | Keep only lines matching a regular expression (RE2). Usually the right first move: `error |
head | Read the START of the log — the arguments a job was given, the image it pulled — which the default tail cannot reach |
offset / length | Page 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 |
lines | Keep 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_bytes | Set 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.
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.
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.
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.
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.
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-fileorFUZZBALL_CA_FILEfor 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_FILEenvironment 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.
- For the CLI, store the CA on your context with
- 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.