Skip to content
AggregaAggrega
Select language: English

aggrega mcp

Run a Model Context Protocol server over standard input and output, or over HTTP, for AI-assistant integration

Synopsis

aggrega mcp [flags]

Description

Run Aggrega as a Model Context Protocol (MCP) server, so an AI
assistant can discover and drive Aggrega operations through a structured
protocol instead of scraping command output.
Two transports reach the same server, and --transport chooses between
them, with mcp.transport in the workspace configuration as the key it
overrides. The default, stdio, speaks newline-delimited JSON-RPC 2.0 over
the process's standard input and output, which is how an MCP-capable
client runs it: spawned as a subprocess, not typed by hand. http serves
the protocol over HTTP instead — one long-running process on a host,
reached by callers who are not at its keyboard — on the address --listen
names, or mcp.listen when the flag is absent.
An address chooses no transport. --listen given with the stdio transport
is refused, whether stdio was typed, configured or left as the default,
because it names where to listen for a transport that does not listen.
An address mcp.listen names is left unused by a server on standard input
and output, which says so in one line on stderr, so a client can launch
this command in a directory whose configuration is written for a
listener. And the http transport with no address from either is refused
before anything binds.
It speaks two MCP protocol revisions on both transports, 2026-07-28 and
2025-06-18, so a client of either connects. In 2026-07-28 nothing is
settled for the connection as a whole: every request states the protocol
version it speaks and the capabilities its sender offers, and the server
reads both from the request it is answering rather than holding anything
between messages. In 2025-06-18 a client settles those same facts once,
by opening the connection with an initialize handshake.
Both revisions reach the same server, and a client learns the same
things about it either way. A client on 2026-07-28 calls server/discover
for the revisions the server speaks, the capabilities it advertises —
tools, resources, and prompts — and the guidance it offers a model
before the first call. A client on 2025-06-18 receives those same
capabilities, and that same guidance, in the reply to its handshake.
From there the client discovers the server's surface through the list
methods (tools, resources, resource templates, and prompts) and invokes
it through tools/call and resources/read. The server exposes Aggrega
operations — compiling and inspecting a Release, reading catalog
entities — as tools and resources an assistant can call directly.
On standard input and output, stream discipline is strict: stdout carries
only protocol messages, one JSON object per line, so the client can parse
the stream without heuristics. Every log, warning, and diagnostic is
written to stderr instead. The server reads one message per line and
exits cleanly when stdin reaches end of stream, so a client that closes
the connection shuts the server down. A client ends one call by naming
its id, and every other call carries on.
Over HTTP there is one endpoint, /mcp, accepting POST. Every message is
its own request and no session of any kind is kept, so nothing a client
sends first decides how a later request is answered. Closing the
connection ends the call it carried. A request carrying an Origin header
is checked against mcp.allowed_origins, and mcp.limits bounds how large
one request body may be, how many requests are answered at once, and how
many one caller may send in a minute. A caller sending faster than
mcp.limits.requests_per_minute is answered 429, counted against that
caller alone.
Every request to /mcp carries a credential, and which one depends on
whether a proxy in front has already checked it. By default it is a
bearer token the server verifies itself, against the keys
mcp.authorization.issuer publishes: it must come from that issuer, name
mcp.authorization.resource among its audiences, be inside its validity
window, and be signed with an asymmetric algorithm. A request carrying no
token is answered 401 with a challenge, and so is one whose token fails
any of those. A token is never accepted from the address, never forwarded
anywhere, never exchanged, and never written to any log; the subject it
names is recorded and compared to nothing.
Set mcp.authorization.trusted_proxy instead and the caller is read from a
header the proxy sets rather than from a token, with its scopes from a
second header; no token is read at all in that mode, and a request
without the principal header is answered 401. Because that header is then
the whole credential, it is trustworthy only where nothing else can set
it: the process is refused before it binds unless mcp.listen is loopback
or a Unix socket.
The challenge names where to obtain a token. A listener publishes an
OAuth protected-resource metadata document, with no credential asked for,
naming the authorization server, this deployment's own address and the
scopes that exist; it is served at /.well-known/oauth-protected-resource
and at that path followed by the endpoint path, which are the two places
a client looks. A client reads it before it can hold a token, which is
why it is the one answer given without one. What that document publishes
comes from mcp.authorization.issuer and mcp.authorization.resource, and a
listener is refused before it binds unless both are set.
The issuer is an https address unless the authorization server runs on
this machine (localhost, 127.0.0.1 or ::1), and that holds in every
mode: with the keys read from the issuer, with a key file, and with a
proxy in front. Every client is sent to the issuer to obtain its token,
so a plain http issuer on another host would carry each client's
authorization code and token across the network unprotected, and a
listener naming one is refused before it binds.
The verification keys are read from the issuer itself, by asking it where
it publishes them and fetching them from the address it names, and read
again once when a token arrives signed by a key identifier the held set
does not carry. That address is held to the same rule as the issuer, and
so is every redirect either read is answered with: a plain http address
on another host is never asked, and a token needing those keys is
answered 503 until the authorization server publishes its metadata and
keys over https. A workspace that is offline makes no such request, so
there mcp.authorization.jwks_file names a file holding those keys and a
listener is refused before it binds without it.
Liveness and readiness are answered on a second address, and only there.
Set mcp.health.listen and a GET of /healthz reports that the process is
running while a GET of /readyz reports whether it can answer a call yet,
each a status code with an empty body and no credential asked for. The
address opens before the workspace is resolved, so a supervisor sees the
process alive while it is still deciding whether it can serve at all.
Leave the key unset and no second listener exists. The endpoint itself
answers both paths the same not-found it gives every path it does not
serve, with a token and without one, so reaching this process over the
network is never a way to probe it.
The workspace this process serves is fixed when it starts, on either
transport: --workspace-root names it, and AGGREGA_WORKSPACE_ROOT supplies
it when the flag is absent. The folder named is the workspace root
itself, as it is for every command: a call naming no workspace of its
own is answered there, and nothing above it is searched for a workspace,
so name the folder that holds the workspace's .aggrega-config.yaml. A
named folder that does not exist is refused, naming the flag or the
variable that supplied it and the value as it was given: a listener is
refused before it binds, while a server on standard input and output
writes the refusal to stderr and starts all the same, answering every
call that acts in that workspace with it, so a client that shows
nothing of stderr still shows the refusal. An empty
AGGREGA_WORKSPACE_ROOT is read as unset, but for one launch: a server
on standard input and output given no --workspace-root, whose
environment carries the AGGREGA_BUNDLE_VERSION the desktop bundle sets,
was started with the desktop application's Workspace folder setting
empty. It is served the same way, the refusal naming that setting, so
no call naming no workspace of its own is answered in the directory it
was started in. In every other case where neither names a root, a
server on standard input and output resolves the workspace from the
directory it was started in, while a listener is refused before it
binds unless a workspace resolves there: one reached
over HTTP serves a workspace an operator chose rather than
whichever directory it happened to be started in. Where that directory
anchors no workspace, a call naming no workspace of its own that names
its Release or document by an absolute path is answered in the workspace
that file's folder resolves, as the same command typed at a terminal in
that directory would be.
For the same reason a call arriving over HTTP cannot name a workspace of
its own. Sending workspace_root or catalog_dirs is refused, naming the
argument, and the directories searched for catalog entities beside the
served workspace are the ones that workspace itself resolves: its own
workspace.catalog_dirs setting — or, for a Release it gives directories
of its own under workspace.releases, that Release's — then its catalog
directory. Over
standard input and output both arguments are honoured: the client that
launched the server is running on this machine.
A workspace_root such a call sends is read the same way by every tool,
the tools that run a command included. An absolute one is used as
given. A relative one is read from the root a call naming no workspace
of its own is answered in — the folder --workspace-root or
AGGREGA_WORKSPACE_ROOT names, which the desktop application sets from
its Workspace folder, or, where neither names one, the workspace root
the directory the server was started in resolves to — so a client that
cannot see where that folder sits on the machine still names a folder
inside it, as quickstart-ai/1. Where there is no such root to read it
from, a relative one is refused as a call naming none is refused, and
an absolute one is answered as it always is.
Asking the process itself to stop — an interrupt from the terminal, or a
termination request from a supervisor or container runtime — shuts the
server down on the first request, whether or not a client is sending
anything: it stops accepting messages, ends the work a call in progress
is doing, and exits cleanly. A listener stops accepting and lets a call
already being answered finish, within a bounded budget, before the
process exits. A second request ends the process at once.

Flags

FlagDefaultDescription
--listen—The address the HTTP transport listens on, in one of two forms: host:port, or unix: followed by a filesystem path. It names where to listen and chooses no transport: it is read with —transport http, or mcp.transport: http in the workspace configuration, and given with the stdio transport it is refused. A listener with no certificate serves plaintext and is permitted only on loopback (127.0.0.1, ::1, localhost) or on a Unix socket, which is the shape a server behind a terminating proxy takes; any other address needs mcp.tls.cert_file and mcp.tls.key_file, which this process then uses to terminate TLS itself. When set, overrides the mcp.listen config key.
--transport—How the server is reached: stdio speaks the protocol over standard input and output, which is how a client that launches this command as a subprocess reaches it; http serves it over HTTP on the address —listen or mcp.listen names, and over HTTPS where mcp.tls names a certificate and key. When set, overrides the mcp.transport config key, whose default is stdio.

What it does

aggrega mcp runs a Model Context Protocol server. Two transports reach it, and --transport chooses between them: stdio or http, with mcp.transport in the workspace configuration as the key the flag overrides, and stdio as the default.

Over stdio, the default, it speaks over the process’s standard input and output. In that shape it is not a command you run interactively — an MCP-capable client launches it as a subprocess and speaks the protocol over stdio; Connect the MCP server lists where each client keeps the entry that launches it. Running it turns the CLI into an Aggrega-aware authoring assistant inside your editor or chat client.

Over http it serves the protocol over HTTP instead: one long-running process on a host, reached by callers who are not at its keyboard, listening on the address --listen names, or mcp.listen when the flag is absent. See Reaching the server over HTTPS for how that listener is configured and what it accepts.

It speaks two revisions of the protocol, 2026-07-28 and 2025-06-18, so a client of either connects and reaches the same surfaces. Which one a call speaks is stated on that call rather than agreed once for the connection. A client on 2026-07-28 sends the protocol version it speaks and its own capabilities with every request, and asks server/discover what the server supports; a client on 2025-06-18 settles those same things once, by opening the connection with an initialize handshake. Either way the server holds nothing between messages, so what you send first decides nothing about how a later call is answered. A request naming a revision the server does not speak is refused and told which two it can ask for, rather than being answered as if it had asked for one of them.

The server exposes three surfaces to the connected assistant:

  • Prompts — two families, and the difference is what each one answers. Authoring prompts answer “what am I writing”: one persona per role (developer, architect, operations), plus a focused per-entity template. Each frames the role and points the assistant at the right schema, reference page, and authoring guide, so its suggestions stay inside the pillars that role owns. Workflow prompts answer “which calls, in what order”: each lays out the ordered sequence of tool calls that reaches a goal spanning several operations, with the decision points between them — composing a new Aggregate and its Release from scratch, bringing an existing chart, infrastructure module or container-compose file into Aggrega, working out why a build does not compile or renders the wrong artifacts. prompts/list enumerates both families and prompts/get renders one, so the set is read from the server rather than from this page.

    A workflow prompt names the calls and you make them, one at a time, reading each result before the next. There is no call that performs a whole goal: each tool wraps one operation you can check, so the sequence is the thing that gets you there. The authoring personas take an optional kind to focus on, the per-entity template requires one, and a kind no schema answers to is refused with the accepted set listed rather than quietly ignored.

  • Resources — read-only reference material served inline: schema://<kind> for an entity’s JSON Schema, langref://<path> for any language-reference page, authoring://<topic> for the authoring guide, catalog://<kind>/<name> for a catalog entity’s authored YAML, and cli://<command> for a command’s own help, with cli:// alone as its entry point — that help is answered from the commands the server itself carries, so reading one starts no process and returns the same text the command prints for --help. A catalog:// read of an entity the catalog does not hold is answered as not found; where that is because exactly one catalog file declaring the entity was skipped at load, the answer’s message names that file, the constraint it breaks and the condition’s short code instead of only the URI — the refusal aggrega build leads with for the same file. resources/list enumerates the ones addressable without a parameter and resources/templates/list advertises every family’s URI shape.

  • Tools — actions against your workspace, and tools/list answers with all of them.

    The tools an assistant meets first are shaped for the authoring loop: list-entities and list-releases to find out what the workspace holds, scaffold a skeleton carrying the fields its kind requires, with a placeholder wherever a value is owed — or, sent example, write one of the documentation’s runnable examples into a new directory, answering with where that directory is, the files written and the commands to build it, and sent list: true, list the examples — get-schema for an entity’s JSON Schema, validate a draft (it names every placeholder the draft still carries, and what each takes), describe a catalog entity — or an entity read from its registry by reference — pull to resolve a Release’s dependencies into the local cache and write its lockfile, build a Release into its rendered artifacts — in memory by default, with no artifact written to disk, or written to dist/ at the workspace root, where aggrega build writes them, when you send write (and the dependencies are resolved first only if you send auto_pull), gen-catalog to generate Plugin entities from Wasm guests, and explain-error to expand a compiler diagnostic into actionable guidance — including, where the diagnostic opens with a halting condition’s short code, that condition and the published walk-through of the authoring fix, the same expansion aggrega explain gives the same code at a terminal.

    The rest of the surface is in the same answer rather than behind it: further tools that run inside the server — lint, the tool that names the connection written at a place in a document, the two candidacy tools, the attachment-container and insertion-point tools, the tool that applies one bounded edit to a document, pin, which records the content pins for an entity’s inputs as Pinning an entity’s own inputs sets out, and the four publication tools described below, plus inventories of the caches and the configured registries — and, for a client that launched this server over its standard input and output, a tool for each command you could otherwise type, named after its invocation path. Those command tools exist on that transport alone: a server reached over HTTP offers none of them, for the reason given under Reaching the server over HTTPS. Nothing is held back for a later call. How much of a tool list to put in front of a model is the client’s decision to make — it fetches the definitions and chooses what to load — and a definition a client never received is an operation a model can never call, however reachable that tool’s name is on the wire. Where the whole list is more than your client will take, Narrowing what the server announces is how you shorten it. describe-capabilities narrows that surface to the entity kind you are authoring. Sent a kind, it answers with the tools that serve that kind, read from the kinds each tool declares rather than from the words in a description; sent no arguments, it answers with that same index over every tool this server offers you — each one’s name, a one-line purpose, the kinds it serves and whether it writes, and no argument schemas, so the whole surface arrives in one readable answer. For a cli- tool, whether it writes is whether the command it runs writes: cli-build is reported as writing, because the command saves the rendered artifacts beneath the workspace root, and so is cli-scaffold, because sent example the command writes one of the documentation’s runnable examples into a new directory, while a command that only reads is reported as reading only, even where it fills a cache every project on the machine shares on the way, as the tool that runs the same operation inside the server is; sent tools naming one or more, it answers with exactly those tools’ full definitions and argument schemas. The cli- tools are never narrowed by kind, because nothing records which entity kind a command serves, so a kind-scoped answer leaves them out and the argumentless index is where you read them. Arguments on a command tool are named after the command’s own flags, so --output-dir is sent as output_dir, and an unrecognised name is refused with the accepted spellings listed rather than being quietly dropped.

    Some capabilities are carried twice on standard input and output: a tool shaped for the authoring loop runs the operation inside the server, and the tool named after the command that carries the same capability runs that command. The two do not behave alike, so on that transport each names the other and states the difference; over HTTP the command tools are absent, and the pairing sentence is withheld rather than pointing at a tool the caller cannot reach. The one that runs inside the server is the one to reach for — it answers with a machine-readable result alongside the readable text, so an assistant gets a verdict, a file list or a diagnostic as fields rather than as a transcript to parse. The command tool starts the real command in a separate process, so it does whatever that command does on the machine it runs on, including writing to disk where the command writes — cli-build writes the rendered artifacts to dist/ at the workspace root, and a traced build’s files to .trace/ beside it, and the closing line it hands back names that directory in full — and hands back only the command line it ran and the text that command printed. Reach for it when you need a flag the command declares that the other tool does not accept.

    That command line opens with the global flags this server was started with that decide configuration — --config and --offline, where you gave them — ahead of the command and the call’s own flags. So the command reads the configuration every other tool here reads: a server started with --offline runs its commands offline, and one started with --config runs them over that global file. A flag the call sends for itself comes after them and wins, so offline: false on one call reaches the network for that call alone, and the command line handed back shows both. Where the server was started with a workspace root — by --workspace-root, or by AGGREGA_WORKSPACE_ROOT — the command line opens with that root as --workspace-root, ahead of those two, so the command takes that directory as its workspace root, as it would typed with the same flag and as every tool that runs inside the server takes it, rather than finding its workspace from the directory the server was started in. A call that sends workspace_root names its own, and the command line carries that one alone — an empty value included, which the command reads as --workspace-root "" reads at a terminal: find the workspace from the directory the server was started in. A server started with neither hands no root, so its commands find their workspace from that directory, by the rule Which workspace a call is answered in sets out for every tool — save the desktop bundle’s launch with its Workspace folder setting empty, on which a call naming no workspace of its own starts no command and is answered with that setting’s refusal. The command starts in the workspace root the call or the launch names: the call’s own workspace_root, read as every tool reads it — an absolute one as sent, a relative one from the root a call naming none is answered in — and handed to the command in its absolute form, else the root the server was started with. So a relative path a call passes as a file to read — a document to validate, a --release or a --catalog — is read inside that workspace, as at a terminal opened there, and a build the command runs writes dist/ beneath that root. Where nothing names a root — no launch root, and no workspace_root or an empty one — the command starts in the directory the server was started in and reads a relative path from there; a workspace_root naming no existing folder is handed on as it was read — an absolute one as sent, a relative one in its full form — and the command refuses it in its own words. A command a command-extension plugin registers is handed none of them, because it passes every argument to the plugin unread rather than parsing a global flag, at a terminal as here; it starts in the same folder as every other command.

    A few commands are deliberately absent even on standard input and output, where the command tools exist at all — over HTTP every one of them is absent, and that is a property of the transport rather than of any command. On standard input and output, each of these is left out for a stated reason: the daemon and this server itself would never return a result; a command that reads a password from the terminal has nothing to read it from; one that writes a shell completion script has no shell to install it into; removing a stored credential acts on the machine-wide store rather than on any workspace you named; and acquiring an identity token interactively has no non-interactive form to offer. Absent on that same machine-wide ground is aggrega plugin run-local, which loads a .wasm guest from a path you give it: what the command is for is reading a file wherever you put it, so there is no workspace it could be confined to, and the read happens in the process itself before the guest exists. The guest is granted nothing when it does run — no directories, no sockets, no environment — but that is a limit on the module rather than on the read, so it is not what decides this. Run it at your terminal, where you are the one naming the path. Signing and publishing are a different case entirely, and the difference is what keeps them off that list. Each of them resolves an identity from a supplied or ambient input and refuses out loud when none is available, so each has a form that completes with nobody watching — whereas acquiring a token interactively is a verb no input can satisfy even in principle. So they are present twice: as the commands, and as the four in-process tools described under Publishing, signing and withdrawing. Where the command line would open a browser, they refuse and name what to supply instead, rather than waiting on a person who is not there.

Which workspace a call is answered in

A call names its workspace with workspace_root; otherwise it is answered in the workspace the server was started over. Where the launch named a root, with --workspace-root or AGGREGA_WORKSPACE_ROOT, that root is the workspace root itself, as the flag is on every command: nothing above it is searched for an enclosing workspace, so a launch names the folder that holds the workspace’s .aggrega-config.yaml, and a call is answered there by the tools that run inside the server and by the command tools alike. Where the launch named none, the workspace is found from the directory the server was started in, exactly as a command typed at a terminal there discovers it — the order is set out under The other ways a project root is recognised — except on the desktop bundle’s launch with its Workspace folder setting empty, which refuses such a call instead, as set out below. A relative workspace_root is read from the root a call naming none is answered in — the root the launch named, or, where it named none, the workspace root the directory the server was started in resolves to — so a call names a folder inside the workspace, such as quickstart-ai/1, without knowing where the workspace sits on the machine; an absolute one is used as given. Every tool reads it so, the command tools included. Where there is no root to read a relative one from — a launch root that is not an existing folder, or the desktop launch with an empty Workspace folder — a relative one is refused as a call naming none is. A workspace_root that names no existing folder, or names a file, is refused before the tool does anything else, naming the argument and quoting the value — an absolute one as it was sent, a relative one in the full form it was read as — as a command refuses --workspace-root.

A launch root that is not an existing folder is served as a refusal over standard input and output. Where --workspace-root or AGGREGA_WORKSPACE_ROOT names a folder that does not exist, or names a file, the server writes the refusal to its error stream and starts all the same, so a client that shows its user nothing of that stream still shows why. It answers initialize and its tool, resource and prompt lists, and every call that would act in that workspace is answered with the refusal: a tool call as a failing result, a read of a catalog:// entity or of a documentation page as an error. The refusal names the flag, or the variable together with the desktop application’s Workspace folder setting that sets it — the setting Claude Desktop describes — and quotes the value exactly as it was given; a value the client sent without filling it in is quoted as it arrived, and nothing in it is recognised. A tool that runs a command starts none for a call naming no workspace of its own, since the folder that command would start in is not there, and answers with the same refusal. A call that names a workspace of its own by an absolute path is answered there; one naming it by a relative path has no folder to read it from, and is answered with the same refusal. What acts in no workspace — a schema, a prompt, a command’s help — is answered as on any server. A listener is refused at startup instead, before anything binds, with the same refusal, so whoever supervises it reads the failure where they look for one.

A desktop launch with its Workspace folder setting empty is served as a refusal the same way. The desktop bundle always hands the server AGGREGA_WORKSPACE_ROOT, carrying whatever Workspace folder holds, and sets AGGREGA_BUNDLE_VERSION beside it, while the application starts the server in a folder of its own choosing — often a system folder — rather than in your project. So a server over standard input and output started with no --workspace-root, whose environment carries AGGREGA_BUNDLE_VERSION and an empty or absent AGGREGA_WORKSPACE_ROOT, does not look for a workspace from the folder it was started in. It writes the refusal to its error stream and starts all the same, answering as it does a launch root that is not there: every call that would act in a workspace and names none of its own is answered with a refusal saying that the desktop application launched the server with its Workspace folder setting empty, so AGGREGA_WORKSPACE_ROOT names no workspace root, telling you to set Workspace folder to the folder that holds your workspace’s .aggrega-config.yaml, and saying that a folder set after the server started takes effect once the extension is turned off and on again or the application is restarted, because the application hands the setting to the server only when it starts it. A tool that runs a command starts none for such a call. A call that names a workspace of its own by an absolute path is answered there, and one naming it by a relative path is answered with the same refusal, since there is no Workspace folder to read it from; what acts in no workspace is answered as on any server. The server recognises the launch by AGGREGA_BUNDLE_VERSION alone: a bundle that sets no such variable has an empty setting read as no root, and a launch that sets the variable by hand and names no root is refused as the bundle’s is. Every other empty value still names no root — an empty AGGREGA_WORKSPACE_ROOT on a launch carrying no AGGREGA_BUNDLE_VERSION, a --workspace-root typed empty, a listener, aggrega serve and every other command each read it as unset.

Where no workspace was found and none was named, an answer about the workspace says which folder it used. With no launch root, no workspace_root on the call, and nothing anchoring a workspace from the folder the call was answered in, the call is answered in that folder. Where the tool’s result depends on the workspace — the same tools whose commands warn on the command line — its text ends with the command line’s warning, <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace, and a line telling you to send workspace_root naming the folder that holds your workspace’s .aggrega-config.yaml; an answer the workspace does not decide, such as the configuration reading or the plugin listing, says nothing about workspaces. The sentence adds no field of its own to the structured result; the structured result carries it in text_answer, which holds the text, as The two parts of an answer sets out. A tool that runs a command in a separate process carries the command’s own line saying the same, as the command printed it. Nothing is written into an artifact cache in such a folder: a pull, or a build asked to resolve its dependencies first, there is refused before anything is fetched, naming the folder and the two ways out — send workspace_root, or give the folder a .aggrega-config.yaml carrying a workspace: block. A pin, or a publication of a Recipe or FeatureRecipe, is refused the same way where it would fetch a remote source the entity writes out in full — to pin it, or to compare its pin — before that source is fetched; where it fetches none, because the entity has no source, a local one or one whose coordinates each Release fills in, it is answered as anywhere else. A build there that resolves nothing first still renders, but an external input its lockfile pins and the cache no longer holds is not fetched again: the render is told that same sentence in place of the input, as it is told an offline posture’s. No answer over HTTP carries the sentence: a listener always serves a workspace it was given or found. Nor does the desktop bundle’s launch with an empty Workspace folder setting, which refuses a call naming no workspace of its own rather than answering it in the folder it was started in.

A call about a Release or a document it names by an absolute path is answered in that file’s own workspace when nothing else settled one. Where the launch named no root, the call sends no workspace_root, and the directory the server was started in anchors no workspace, the workspace is discovered again from the folder that file sits in, and whatever that finds — the project the file belongs to, or, failing everything, that folder — is the one the call is answered in. That is the rule a command typed at a terminal follows, so it holds for every tool whose call is about a Release or an entity document it names: a build, a pull, a validation, a lint, a description, a listing in a Release’s terms, a question about a node of a Release’s graph, a pin, the publication of an entity, an edit, and a position read in a document. Where a call names both a Release and a document, the Release decides. So a client that launched the server outside your project still has a Release in it built from the project’s own configuration. The other paths the call names are read as they always are — a relative one from the directory the server was started in — and a tool that runs a command in a separate process is answered from the same workspace, because the command follows the same rule in that same directory. A root the launch named, a workspace_root the call sends, a starting directory that is itself inside a workspace, and a Release or document named by a relative path are used as they are. Over HTTP none of this arises: a listener always serves a workspace it was given or found, and every path a call names is relative to it. Nor does it on the desktop bundle’s launch with an empty Workspace folder setting, which refuses a call naming no workspace of its own whatever file it names.

Narrowing what the server announces

mcp.announce_tools names the tools this server announces, spelled exactly as the tool list reports them. Leave the key out and every tool this server carries is announced, which is the default and the shape a client following the protocol expects. Write a list and exactly those tools are announced: one left out is absent from the tool list, absent from what describe-capabilities answers, and refused if it is called by name anyway, with the refusal naming this setting. Write an empty list and nothing is announced at all — so leaving the key out and writing [] are different statements, and the setting has no default filled in for you.

Set it where the client at the other end caps how many tools it will register, sometimes across every server it is connected to at once, and name the tools that client needs. That cap is the case the setting exists for, and the client it applies to is usually the one that launched this server over its own standard input and output — so unlike the rest of the mcp block, which configures the listener the http transport starts, this key is read whichever transport the server speaks.

It narrows what is announced and nothing more. Naming a tool here widens nothing. It does not lift mcp.deny_reach, which withdraws a capability outright, so a tool named here of a kind that setting withdraws stays out of the list and is refused naming that setting. Nor does it lift the scopes a caller’s token carries: a tool named here is listed whatever those scopes are, and a call they do not admit is still refused, naming the scope that would. Either way the refusal a caller meets is that other bound’s rather than this one’s. A refusal from this setting carries no challenge and names no scope, because no credential changes what a server chose to offer — what it names instead is the setting, which is the only thing anyone reading the refusal can act on.

Every name has to be one this binary carries. A name no tool answers to stops the server before it serves anything, and the refusal lists the tools it does have — so a misspelling is met at startup rather than by a surface quietly narrower than the one you asked for. A name in the cli- family, which runs an aggrega command in a separate process, is accepted on both transports and announces nothing over HTTP, where no such tool is offered to any caller in the first place.

The announced set is fixed when the process starts, so changing it takes a restart and nothing grows the list under a client that has already connected.

Which release the server comes from

describe-capabilities sent no arguments says which release this server comes from. Its structured answer carries server_version, the version the aggrega executable reports for itself — the one aggrega version prints for the same file — and its text opens with one line naming it, ahead of the index. The structured answer carries that same line as version_summary, word for word, so a client that hands a model only the structured answer hands it the line too.

Where the desktop bundle launched the server, the same answer names the bundle’s version beside it. The bundle carries no program: it launches whichever aggrega executable its Path to the aggrega executable setting names — by default the command name aggrega, which the application looks up on its PATH — so the bundle and the executable are installed separately and can come from different releases, and the application listing the bundle shows the bundle’s own version only. The bundle hands the server its version as AGGREGA_BUNDLE_VERSION in its environment; the server reads it once, when it starts, and the answer carries it as bundle_version. The two are compared exactly as written, which is a fair comparison because the bundle and the executable of one release are stamped with that release’s version in the same form, while a development build reads differently from every release. Where the two are equal, the line names both and says nothing more. Where they differ, the line says, naming both, that the executable and the bundle come from different releases, and the guidance the server offers a model when it connects opens with that same sentence, so the difference is in front of the model before it asks.

A server no bundle launched reports its own version alone. Started from a terminal, from an editor’s configuration or as a listener, it carries no bundle_version, unless something sets the variable in its environment. A server over standard input and output carrying the variable is taken for the bundle’s launch in one respect more: named no root, it refuses the empty Workspace folder setting, as Which workspace a call is answered in sets out. A describe-capabilities call sent kind or tools carries no server_version, bundle_version or version_summary and no such line, because it answers about tools rather than about the server.

A difference is reported and never refused. The server starts and answers every call exactly as it would with the two in step. What a difference means for a desktop installation, and how to bring the two together, is in Connect the MCP server.

Reaching the server over HTTPS

aggrega mcp --transport http serves the protocol over HTTP instead of over standard input and output. mcp.transport in the workspace configuration is the key that flag overrides, and its default, stdio, is what a client that spawns the command expects — so a server other people reach carries transport: http in its configuration, and a client launched from a directory that configuration covers still reaches the server over its own streams. It is the same server either way — the same workspace and the same protocol surfaces — and what changes is how a message reaches it, how a call ends, and what whoever runs it has to hold. This section is what an operator configures; the entry a client needs in order to reach a running one is in Connect the MCP server.

An address chooses no transport. --listen <address>, or mcp.listen when the flag is absent, names where the listener binds once http is chosen, and nothing more. So http with no address from either is refused before anything binds, and the refusal names both. --listen typed while the transport is stdio — typed as --transport stdio, configured as mcp.transport: stdio, or left as the default — is refused as well, naming --transport http as the flag that would serve on that address; a --listen given an empty value is refused as naming no address, whatever the transport. And an address only the configuration names is left unused by a server speaking over its own streams, which says so in one line on its error stream, naming the file that set it and mcp.transport: http. That last case is refused nowhere on purpose: it is the launch a client makes when it starts the command in a directory whose configuration carries a listener’s settings, and a listener’s configuration that forgets transport: http starts no listener at all, which is where it is seen.

A server reached over HTTP offers no tool that runs an aggrega command in a separate process. Those tools exist only for a client that launched this server over its standard input and output, on that client’s own machine, where naming a folder or a flag grants the caller nothing they did not already have. A caller reaching the server over HTTP does not own the host it runs on, so a command that would act on that host’s filesystem with the server’s own authority is run at a terminal on the host instead. The tools are absent from the list and from describe-capabilities rather than being offered and refused, and a call naming one is answered with an error saying so. That is a property of the transport, not a setting: there is no configuration that puts them back.

Read Nothing is served without a credential before you deploy one. Every request to the endpoint carries a credential, and there is no setting that serves a request without one — what a setting chooses is whether this server checks a bearer token itself or reads a caller a proxy in front has already checked.

The two deployment shapes

The process terminates TLS itself. Set mcp.tls.cert_file to a PEM certificate chain and mcp.tls.key_file to its private key, and the listener serves HTTPS directly on whatever address you gave it. Both files are read when the process starts, so a replaced certificate is picked up by restarting the process. Setting one without the other is refused at startup rather than falling back: a certificate with no key cannot be presented and a key with no certificate names nothing, and a typo in one path is not a reason to start serving unencrypted traffic.

A proxy in front terminates TLS and forwards to a confined listener. Leave both keys unset and the listener serves plaintext, which is accepted only on loopback or on a Unix socket — so nothing that is not already on that host can reach it. That is the shape a reverse proxy, a sidecar, or a service mesh uses, and it is the one where the certificate lives in front of this process rather than in it.

A plaintext listener on any other address is refused before anything binds, and the refusal names both TLS keys. There is no setting that lifts this and no address that is an exception: a listener accepting from the network with no certificate of its own is never safe, so the process declines to start rather than starting in that shape.

The address forms

--listen and mcp.listen take one of two forms:

  • host:port — a TCP address, such as 127.0.0.1:7777 or 0.0.0.0:8443. Loopback means 127.0.0.1, ::1, or localhost when every address that name resolves to is a loopback address. Anything else is a network address and needs a certificate: an empty host, which is every interface the machine has; a specific interface address; and any other name, even one that resolves to a loopback address at this moment, because where a listener may bind should not depend on a resolution that can change under it.
  • unix: followed by a filesystem path — a Unix-domain socket, such as unix:/run/aggrega/mcp.sock. A socket is reachable only from the host it sits on, so it needs no certificate.

A socket path is taken exactly as written, a relative one included. It is deliberately not resolved against the configuration file that declared it, because the same address also arrives from --listen, which has no declaring file — see where a relative path points.

What the listener accepts

One endpoint, /mcp, accepting POST. Every JSON-RPC message is its own request and no session of any kind is kept: nothing a client sends first decides how a later request is answered, no session identifier is ever minted, and a session or stream-resumption header a client sends is ignored. Any other method on that endpoint is answered 405 with Allow: POST, and any other path 404 — both settled before the credential check, so probing learns nothing from a challenge on a path or a method that would serve nothing anyway.

A request is answered with one JSON object and a status code — or, where the call reported progress on its way to that object, with a stream of events ending in it, which Being told how a long call is going sets out. A notification — a message carrying no id — is answered 202 with an empty body. A message that is neither, including a JSON-RPC response, is answered 400, because a client sends this server requests and notifications and nothing else.

Both protocol revisions are served here exactly as they are over standard input and output. A 2026-07-28 request mirrors its body in transport headers so an intermediary can route it without parsing the body: MCP-Protocol-Version carries the revision the body states, Mcp-Method the method it names, and Mcp-Name the target, for the methods that address one by name. A header that disagrees with the body is answered 400. A 2025-06-18 client opens with an initialize handshake, which is answered statelessly; it may carry the version header naming that revision or omit it. A request naming a revision the server does not speak is answered 400 listing the two it does, and one naming a method it does not serve is answered 404.

mcp.allowed_origins is consulted only when a request carries an Origin header, which in practice means a browser sent it: a request naming an origin the list does not carry is answered 403, and one carrying no such header is served. A client that is not a browser sends no such header and needs no entry. A browser-based one always needs an entry: the list is empty until an operator writes it, so until then no origin at all is carried and every browser request is answered 403 — including one from a page served at the endpoint’s own address. The entry is compared to the header exactly, so it is written as a browser sends an origin — a lowercase scheme, ://, a lowercase host and, where it is not the scheme’s default, : and the port, such as https://app.example.com — and an entry with a path, a trailing /, no scheme or a capital letter is refused when the configuration loads, naming the entry, because it could never match.

mcp.limits bounds the traffic that is accepted. A body past max_body_bytes is answered 413 and is not read past the cap. A request arriving while max_concurrent_requests are already in flight is answered 503 rather than being queued behind work it cannot see. A caller sending more than requests_per_minute inside a minute is answered 429, counted against that caller alone, so one caller sending hard does not cost another anything. Each cap’s default is stated beside its key in the configuration reference, and none of them has a value that turns it off.

One process, one workspace

The workspace a serving process answers for is fixed when it starts. --workspace-root names it; the AGGREGA_WORKSPACE_ROOT variable supplies it when the flag is absent. The folder named is the workspace root itself, with nothing above it searched, and a folder that does not exist is refused, naming whichever of the two supplied it and quoting the value as given — by a listener before it binds, and by a server on standard input and output in its answer to every call that acts in that workspace, as Which workspace a call is answered in sets out — so a launch composed by a client rather than typed still says what it was handed. With neither, a server on standard input and output resolves the workspace from the directory it was started in — where nothing anchors one there, each answer about the workspace says which folder it used, and the desktop bundle’s launch with an empty Workspace folder setting refuses a call naming no workspace of its own instead, as Which workspace a call is answered in sets out — and a listener is refused before it binds unless a workspace resolves there — a process reached over HTTP answers callers who cannot see the machine, so it serves a workspace an operator chose rather than whichever directory it happened to be started in. Serve several projects by running one process per project root.

A call arriving over HTTP cannot name a workspace of its own. workspace_root and catalog_dirs are refused, naming the argument that was sent, rather than being quietly dropped: an argument silently ignored reads to its sender exactly like one that was honoured. Catalog directories searched beside the served workspace are that workspace’s own workspace.catalog_dirs setting — or, for a Release it gives directories of its own under workspace.releases, that Release’s — which the operator writes. Over standard input and output both arguments are honoured, because the client that launched the server is running on the caller’s own machine. There a catalog_dirs entry is absolute, or relative to the workspace root a relative release is read from — the root the call’s own workspace_root, the launch, or the directory the server was started in settled first, and the one it stays read from where a Release named absolutely moves the call into that Release’s own workspace — and not to the directory the server runs in, where that is somewhere else.

A path a call names stays inside that workspace too. Over HTTP a path argument is resolved against the workspace root and refused if it reaches outside it — a relative path that climbs out of the workspace, an absolute path naming somewhere else, and a relative path leading out of the workspace through a link to a file or a directory that is there, each come back as a failure naming the argument, and naming neither the workspace root nor the place the path would have reached; a relative path is quoted back as you sent it. Every path argument is judged by where it leads, by the definition of inside The workspace boundary states, whether the tool reads it or writes it — the directory gen-catalog writes its output into, the document edit-document writes back and the entity pin writes its lock beside as much as a document a tool reads — so a path not made yet beneath a link leading out of the workspace is refused as that link is, with nothing read or written. A release naming a Release the served workspace’s configuration names, as build.authoring_release or as a key of workspace.releases, is reached through that configuration and is accepted through a link wherever its file sits; no other argument has that exception. Where the path you meant is inside that workspace but was spelled absolutely, the refusal gives you the root-relative spelling to send instead, so a caller that guessed the wrong form is told the right one rather than only that it was wrong. That holds for the paths a call names as its subject — the document to validate, the Release to build, the directory a generation writes its output into — and for the ones a tool writes to no less than the ones it reads: a caller reaching a server over the network is asking a machine it cannot see to read and write files, and the workspace the operator chose is where that reading and writing is kept. Over standard input and output each tool’s path arguments keep the contract described under that tool below, where a path may be absolute and may point outside the workspace — the person calling owns the machine the server is running on, so confining them to a directory they chose themselves would buy nothing. The two tools whose operation itself answers only about a document the workspace carries, insertion-point and edit-document, keep that on both transports, and refuse a document outside the workspace whether it is written that way or reached through a link leading out of it. What is honoured over standard input and output is the path a call names and nothing beyond it. What the operation then reads and writes on its own account is held on both transports exactly as it is when the same command is typed at a terminal: a walk or a lookup does not read through a link leading out of the workspace, a file a Release in the workspace or its Manifest names by a path is not read from outside the workspace — and one a Release the call named outside the workspace names is not read from outside the directory holding that Release — and a file written beneath a directory — the workspace, or one the call named — stays inside that directory. The workspace boundary sets the two transports beside the command line and the editor, and states what remains open over standard input and output: a document in a workspace you cloned can steer an assistant into naming a path outside the workspace, and that path is honoured as named.

What an answer says about the server’s filesystem

Over HTTP an answer names a place in the server’s filesystem relative to the workspace root, or keeps it back. A client that launched the server runs where the server runs, so over standard input and output every answer names each place as the operation holds it — absolute, where that is how it is held — and each is a place that caller already owns. A caller reaching a listener chose none of those places and cannot open them, and a server that has published them to it cannot publish them back. So over HTTP an answer tells that caller one of two things about a place:

  • A place inside the workspace is named relative to the workspace root — the same form a path you send takes, so a name read from one answer can be sent back unchanged in the next call. A Release at the root is release.yaml, and its lockfile is release.lock.
  • A place outside the workspace is kept back, and so is the workspace root itself. The field carries no value — it is null or left out, and on attachment-container, whose answer keeps the shape every surface reports it in, file is left empty — and a mark beside it, named after the field with _withheld appended, says it was kept back rather than unset: workspace_root_withheld beside workspace_root, file_withheld beside file. A mark is present only where something was kept back. The root is kept back because a listener serves exactly one workspace, so where that workspace sits names nothing you need in order to name what is inside it.

Whether a place is inside is judged on how it is spelled, not on the file it reaches. A path written through the target of a symbolic link rather than through the root the server was started over, and a path that climbs out of the root and back in, each read as outside the workspace and are kept back. The judgement errs toward telling you less, never toward naming a place outside the workspace.

Over HTTP an answer’s readable text follows the same rule. Where the text, a diagnostic line or a failure’s message names a place the workspace holds — its root or anything under it, a config file its configuration was read from, a directory its catalog is read from — that place is written relative to the root, or reads (location withheld) where it lies outside the workspace or is the root. Text an answer composes about its own workspace calls it the workspace this server serves. A place outside all of those that an operation writes into a message is not recognised as one, and reaches you as it was written.

The answers this reaches, over HTTP:

  • list-entities, list-releases, cache-status, registry-list, search, attach-candidates, connection-candidates, insertion-point, attachment-container, connection-at-position and edit-document keep back workspace_root. The paths they already give relative to the root — an entity’s source file, a Release’s path and its lockfile under lockfiles, the document an insertion point or an edit is about, the files an edit wrote — read the same on both transports.
  • cache-status also keeps back what names a plugin the server loaded from a file on its host. Such an identity is null in its place in provenance[].identities, every other identity keeps its position, and the entry is marked identities_withheld. A compiled module’s note is one sentence naming the identities the module was built for, so where any of them names such a file the note is left out whole and marked note_withheld; the module’s digest is still there. An identity naming a registry reference or a Plugin entity is answered whole, and so is a note naming only those. A source artifact’s label is its place in the cache, spelled from the host and path of the URL it was resolved from, so for a repository read from the server’s own filesystem — through a file:// URL or a path — the label is left out and marked label_withheld, its size and digest are still there, and a label naming a network host is answered whole. The listing’s text reads (location withheld) where it would have named one.
  • validate names target, and release for a Release, relative to the root; for the whole catalog, target is the root and is kept back. A place in diagnostics or notices follows the rule for text.
  • build names release relative to the root, and a build that resolved its dependencies first carries dependency_resolution as pull answers it. A build sent write names the directory it wrote as output_dir, which reads dist — relative to the root — and each path in files is relative to that directory. A refusal, and each entry of its findings, names its file relative to the root, or keeps it back where the document lies outside the workspace. advisories, deprecations, declined_external_inputs and each message of the refusal follow the rule for text.
  • pull names release and lockfile relative to the root. diagnostics and incomplete_external_inputs follow the rule for text. Each resolved entry’s source is answered whole on both transports: it names what the run did, never a place on the host.
  • describe names a Release’s release relative to the root, and an entity’s file relative to the root where its document lies inside the workspace; an entity read from a catalog directory outside the workspace has its file kept back. mapping_diagnostics and deprecations follow the rule for text.
  • lint names each finding’s location.file relative to the root, or keeps it back where the entity lies outside the workspace. A finding’s message and suggest follow the rule for text.
  • pin names entity and lock relative to the root, and so does the pin a publication carries.
  • gen-catalog names each file listed in output relative to the root.
  • import keeps back workspace_root, and output_dir where the drafts went to that root; a directory you named in output_dir is told by its name relative to the root. Every drafted path in written and drafts is relative to output_dir, so where the drafts went is in the answer either way. A diagnostic’s message, and a decision’s params_summary, rationale and swap_hint, are prose the importer composed and follow the rule for text.
  • config-show and plugin-list keep back more than the root, because most of what they report is configuration naming places, as What a listener does not tell you about its host sets out.
  • scaffold writing an example names dir as you sent it, relative to the root, and each path in files relative to that directory; drafting and listing name no place.
  • The publication tools, sign-artifacts, deprecate-artifact, get-schema, explain-error and describe-capabilities name no place on the host of their own. A failure’s message from any of them follows the rule for text: the refusal an offline workspace raises names its .aggrega-config.yaml relative to the root.
  • A path argument refused for reaching outside the workspace is refused without naming the root or the place it would have reached, as above.

How a call ends

Closing the connection cancels the call it carried. That is this transport’s cancellation signal: the server treats a caller’s disconnect as cancellation of that request, ends the work it was doing, and writes nothing further for it. No cancellation message is needed or expected here — which is the opposite of standard input and output, where there is no per-request stream to close and a client ends one call by naming its id instead. A cancellation message that does arrive over HTTP is accepted and ends nothing.

Stopping the process drains the listener. An interrupt, or a termination request from a supervisor or a container runtime, stops the listener accepting and lets a call already being answered finish, within a bounded budget, so a caller that asked for something before the stop still receives its answer. A call that has not finished inside that budget loses its connection. A second stop request ends the process at once.

Liveness and readiness, on an address of their own

mcp.health.listen is where a supervisor asks whether this process is up and whether it can answer a call. Give it an address in either of the forms above and a second listener answers GET /healthz and GET /readyz there. Leave it out — which is the default — and no second listener is started and neither check is answered anywhere.

The two answers say different things, and that difference is why there are two. /healthz is answered 200 from the moment the process is running, which is the whole of what liveness claims: it is up, and a supervisor that gets no answer at all should restart it. /readyz is answered 503 until the workspace this process serves has resolved and the endpoint has bound, and 200 from then on — so a balancer holds traffic back until the process can actually answer a call, rather than sending the first request into one that is still starting. Every answer is a status code with an empty body; no credential is asked for, and nothing the caller sent is read.

The endpoint never answers those two paths. GET /healthz and GET /readyz on the address mcp.listen names are answered 404, exactly as every other path that endpoint does not serve, with a token and without one alike. Answering a probe there would hand anything that reaches the endpoint a free reading of whether the process is up, together with a free way to make it do work — on a listener that otherwise refuses every request carrying no credential.

Where the health address sits is yours to choose, and it is not confined the way mcp.listen is. No address is refused for it. Point it at loopback or at a Unix socket, which is what it is for: a supervisor, a balancer or a container runtime running beside this process on the same host. Whatever can reach the address you choose can read those two answers, so an address the open network reaches publishes them to the open network.

Nothing is served without a credential

Every request to the endpoint carries a credential, and which one depends on whether a proxy in front has already checked it. By default it is a bearer token this server verifies itself, described in the rest of this section. Set mcp.authorization.trusted_proxy and it is instead a header that proxy sets, described under Reading the caller from a proxy in front — where no token is read at all. Neither shape serves a request that presents nothing.

By default the server checks a bearer token itself. It reads the token off the Authorization header and accepts it only where the signature verifies against a key the authorization server publishes, the token names mcp.authorization.issuer as its issuer, it names this deployment’s own mcp.authorization.resource among its audiences, it is inside its validity window, and it says who presented it. A token failing any of those is answered 401, with error="invalid_token" added to the same challenge a caller carrying nothing receives — and the answer is identical whichever check turned it away, so a caller learns that it needs a different token rather than which part of the one it sent was wrong. Only asymmetric signature algorithms are accepted: an unsigned token, and one naming a symmetric algorithm, are refused before anything is read from it.

A token may say what kind of token it is, and four forms are accepted. A JWT can carry a typ header naming its own type. This server accepts at+jwt and application/at+jwt, the two spellings registered for an access token; JWT, which says only that the token is a JWT; and a token that declares no type at all. Anything else is answered 401 exactly as every other refused token is. The set is fixed and no setting widens or narrows it, because which form appears there is decided by the authorization server that minted the token rather than by the deployment receiving it. Accepting JWT does mean the declared type alone no longer tells an access token from an identity token — the audience check is what tells them apart, and it is why that check is the load-bearing one: an identity token’s audience is the client it was issued to, never this deployment’s own mcp.authorization.resource, so a token issued for anything but this deployment is refused whatever it calls itself.

Which authorization servers that admits. Microsoft Entra ID issues access tokens typed JWT. Keycloak issues at+jwt, and JWT where its OpenID Connect compatibility mode is on. Auth0 issues JWT under its own token profile and at+jwt under its RFC 9068 profile. A token from any of those satisfies this check whichever of the two forms it carries. Okta is not supported: its access tokens declare a type of their own that is none of the four above, so this server refuses them.

A refused token leaves the reason on the server’s own error stream. The caller is told only that what it presented was not accepted; the serving process writes one line naming the check that turned the token away — the audience, the issuer, the validity window, the signature, the key identifier, the declared type, and each of the others. That line is how a deployment refusing every request is diagnosable by whoever runs it rather than only by whoever is calling it. It carries no part of the token. A request presenting no credential at all writes no line, because being challenged is how a client finds out where to obtain a token in the first place, so it is the first thing every well-behaved client does.

A token belongs on the header and nowhere else. One sent as an access_token query parameter is answered 400 and is never read, because an address is recorded by every proxy log, browser history and referrer header the request passes through, so a token that arrived that way has already been exposed. The server never writes a token to a log, never sends one anywhere, and never obtains or exchanges one on a caller’s behalf: it reads what was presented, decides, and keeps none of it. The subject the token names is recorded and compared to nothing.

The verification keys come from the authorization server, or from a file you name. With mcp.authorization.jwks_file unset, the server reads the authorization server’s metadata at its well-known address, follows the jwks_uri published there, and holds the keys it finds; a token signed by a key identifier those keys do not carry prompts one re-read, and no more than one inside a short interval, so a caller sending invented key identifiers cannot drive an outbound request per request. Reading them from the authorization server needs an https key address, or a plain http one on this machine: a jwks_uri that is plain http on another host is never asked, and a redirect that would send either read to plain http on another host is not followed, because whoever sits on an unprotected path to the keys could answer with keys of their own. A token needing those keys is then answered 503, exactly as for keys that cannot be read, and the line the server writes for that request says the read was refused for plain http rather than that the authorization server could not be reached — the fix is on the authorization server’s side, which has to publish its metadata and keys over https. With jwks_file set, the keys are read from that file and the authorization server is never contacted — which is what a workspace declaring offline: true needs, and such a workspace is refused before its listener binds unless the file is named. Where the keys cannot be read at all, requests are answered 503 with no challenge: nothing a caller presented was found wanting, so sending it after another token would not help.

The one answer given with no credential asked for is the protected-resource metadata document. A client has to read it before it can hold a token, so requiring one there would close the only door in. It is answered at /.well-known/oauth-protected-resource, and — where the address mcp.authorization.resource names has a path of its own — at that well-known path with that path appended as well. Those are the two places a client looks, and the appended form is the address the challenge names. The document carries that address as the resource this deployment is called, mcp.authorization.issuer as the authorization server to obtain a token from, header as the only way to present a token, and the three scope names below.

The issuer is an https address, unless the authorization server runs on this machine. Plain http is accepted for an issuer at localhost, 127.0.0.1 or ::1, which is the shape a local test with a local authorization server takes; a plain http issuer on any other host is refused before the listener binds, and the refusal names mcp.authorization.issuer and asks for an https address. That holds in every mode — with the keys read from the issuer, with mcp.authorization.jwks_file, and with a proxy in front — because every mode publishes the issuer in this document: a client following it runs its authorization flow against that address, so over plain http the authorization code and the token it obtains would cross the network unprotected, whether or not this server ever reads a key from there. Where it does read its keys from there, whoever sits on that path could also answer with keys of their own, and every token signed with them would be admitted.

The scope names this deployment publishes are aggrega:read, aggrega:workspace-write and aggrega:registry-write. Those are the names to register at the authorization server and the names a client asks it for, and the challenge a refused caller receives names aggrega:read as the one to obtain first. What each of them admits — and the second bound, the one this deployment sets on itself — is under What a caller may reach below.

Reading the caller from a proxy in front

Where a proxy in front already validates tokens, mcp.authorization.trusted_proxy tells this server to read the caller from it instead of checking a token a second time. Give it principal_header, the header that proxy sets to say who the caller is, and optionally scopes_header, a second header carrying that caller’s scopes separated by spaces. Each is an HTTP header name such as X-Forwarded-User, with no space or colon; a name in any other shape is refused when the configuration loads, naming the key, and so is an empty principal_header — leave the block out to leave this mode off. Those two headers are the only ones read: no forwarded-address header and no other header participates. A request arriving without the principal header is answered 401, and no token is read in this mode at all — a request carrying a token this server would otherwise have refused is served when its principal header is present, and one carrying a token this server would have accepted is still refused when that header is absent.

That mode is accepted only on loopback or a Unix socket, and the process is refused before it binds anywhere else. A header is trustworthy exactly when nothing but the proxy can set it. On an address the network reaches, anything can set it — so a listener in this mode on such an address would let every caller name itself whatever it liked. The refusal names both settings that conflict, so you can lift it by moving the address or by removing the block.

What the proxy asserts is what this server believes, and that is the bargain. This server checks no signature in this mode and compares the asserted caller to nothing, exactly as it compares a token’s subject to nothing. Whether the proxy validated what it forwarded, and whether anything can reach that listener without passing through the proxy, are the deployment’s to get right; the confinement above is what makes them possible to get right, not a guarantee that they were.

Setting mcp.authorization.trusted_proxy does not remove the other requirements. issuer and resource are still needed, because the metadata document is still published and the challenge still names it — a client behind the proxy still has to learn where to obtain the token the proxy will check. For the same reason the issuer is still an https address unless it runs on this machine: that client obtains its token from the issuer, so a plain http issuer on another host is refused before the listener binds in this mode exactly as in every other, even though this server reads nothing from it.

What a caller may reach

Two bounds decide what a caller reaches over HTTP, and they are set by different people. The caller’s own credential is the first; what this server carries at all is the second. Both are read before anything runs, from a declaration each operation makes about itself, and they reach a client in different places: the tool list shows what this server carries and announces, and the answer each call receives shows what the credential admits.

Every operation declares how far its own effects travel, and there are four kinds, widest last:

  • Reaches nothing — reads a definition, inspects what a Release pins, renders artifacts in memory and hands them back. It leaves nothing behind: nothing is written, and the answer is the whole of what it produces.
  • Reaches the workspace — writes inside the workspace this process serves: a Release’s lockfile, the artifact cache, generated entities, an edited document.
  • Reaches a registry — publishes, signs, or attaches a withdrawal marker to something already published. What it changes is what every consumer of that registry resolves, and none of it can be recalled from anyone who has already fetched it.
  • Reaches the machine — changes what every workspace on the host shares, among them the compiled-module store, the configuration file common to all of them, and the credential store. A cache a single project keeps under its own cache directory is not this kind, and cache-status reports which of these kinds each cache it lists carries.

The kind is a property of the operation rather than of the tool that offers it, and it covers what the operation leaves behind — not where a surface puts the answer it hands back. Rendering a Release produces artifacts as its answer, so it reaches nothing; a command line that then saves those artifacts into a directory you named is delivering that answer rather than reaching further. Read the other way, every operation that answers with content would take the kind of whichever surface happened to save it, and the kind would stop being a property of the operation at all. For the same reason describe reading an entity by its registry reference reaches nothing: it contacts that registry to fetch its answer and leaves nothing behind, in the registry or on this machine, and which registries it may contact is set out under Which credentials a call spends. One call can still reach further than its operation’s kind, where the call itself asks for a write: a build sent write saves its artifacts in the workspace this server serves, so that call reaches the workspace, as a build that resolves its dependencies first does.

A scope admits a kind, and each write scope implies the read scope. aggrega:read admits an operation that reaches nothing. aggrega:workspace-write admits one that reaches the workspace, and implies the read scope. aggrega:registry-write admits one that reaches a registry, and implies the read scope too. So a client asks its authorization server for the write scope it needs and does not also have to ask for the read scope.

No scope admits the machine kind, and no setting adds one. The operations of that kind are carried only by the tools that run an aggrega command in a separate process, and a server reached over HTTP offers none of those at all, for the reason given under Reaching the server over HTTPS above. Run them at a terminal on the host.

The tool list shows every tool this server carries and announces, whatever scopes the calling credential holds, and the credential decides which of them a call may run. describe-capabilities indexes and defines that same set. A call the credential does not admit is answered 403 with error="insufficient_scope" on the challenge, naming the one scope that would admit it, and nothing the call asked for has run. That refusal is the one the protocol’s step-up answers: a client that implements step-up asks you to sign in again for the scope the challenge names. The list does not change with the credential, so a client that has signed in again already holds the right one. A credential carrying none of the three scopes receives the same tool list and can call none of the tools on it, describe-capabilities included.

A build is the case worth knowing. It changes nothing by itself and so needs only aggrega:read, but a build that writes needs aggrega:workspace-write: one sent write saves its artifacts to dist/ at the workspace root, and one that resolves its dependencies first writes the lockfile — whether the call asked for that with auto_pull or the workspace’s own auto_pull setting did. The tool is listed to a read-scoped caller as every tool is, and the builds that stay in memory are genuinely available to it; what is refused, naming aggrega:workspace-write, is the call that writes.

A client that does not step up can still be given the write scopes, and that is settled at the authorization server. Whoever runs the authorization server makes the write scopes default scopes for that client — scopes it puts in every token it issues to that client, whether or not the client asked for them — so the token its first sign-in obtains already carries them. A client that registers itself with the authorization server anew each time it connects is a new client there each time, and a setting made on an earlier registration does not carry over; for such a client, the setting that takes effect is the default scopes the authorization server gives every client it registers. The cost is that every sign-in through that client then carries write reach, whether or not the work in hand needs it — and where the defaults are the ones given at registration, every client registered that way carries that reach too. Make only the write scope that work needs a default: aggrega:workspace-write and aggrega:registry-write admit different kinds, and neither implies the other.

mcp.deny_reach is where whoever runs this server withdraws a kind from it, and it is one of the two settings that shorten the tool list. List the kinds — none, workspace, registry, machine — this server does not carry, and every tool that reaches one of them is absent from every caller’s tool list and from describe-capabilities whatever that caller’s token says, and refused if called anyway with an error naming this setting. It is the server’s own bound rather than the caller’s, so no credential lifts it and the refusal carries no challenge: a server meant to serve reads and nothing else lists workspace, registry and machine here, and then cannot publish even for a caller whose token carries all three scopes. Leave it out, which is the default, and this server withdraws no kind, so which kinds a call reaches is decided by the caller’s own scopes. Naming machine is accepted and changes nothing, since nothing of that kind is offered here in the first place. A value that is not one of the four is refused when the configuration loads, rather than being passed over — an operator who misspells a kind has asked for a bound, and being served without one silently is the wrong way to answer that.

mcp.announce_tools is the other setting that shortens the tool list, and the two are not the same bound. deny_reach withdraws a capability: an operation of a kind named there is not carried here at all, for anyone. announce_tools withdraws only an announcement: the tools it leaves out are capabilities this server still has, and what it answers is a client’s own cap on how many tools it will register. Where both are set the withdrawal wins, so a tool of a withdrawn kind stays absent however announce_tools names it, and the refusal a caller meets names the withdrawal. Nothing that shortens the list reads the caller’s scopes: a scope the caller lacks refuses a call and never removes a tool from the list. Narrowing what the server announces sets out the rest.

Which credentials a call spends

Keyless signing over a listener takes its identity from the identity_token the call carries, and from nothing else. A token sent in the call is a credential the caller holds: they had to obtain it, it is bound to them, and the signature it makes is attributable to them. Every other place an identity could come from belongs to whoever started this process, so on this transport the resolution is handed an environment that answers nothing. AGGREGA_IDENTITY_TOKEN and SIGSTORE_ID_TOKEN in the server’s environment are not read, and the ambient GitHub Actions OIDC endpoint is not reached. They are out of reach rather than discouraged — there is nothing for the resolution to find. A call sending no identity_token is refused, and the refusal names identity_token as what to send and names no variable and no endpoint: a caller who is not at this machine’s keyboard cannot export anything here, so naming one would be telling them to arrange something that cannot change the answer.

A signing key held on this machine cannot be selected, by either route. key_path is refused before anything is resolved, and it is absent from the argument schemas publish-entity, sign-artifacts and deprecate-artifact advertise here, so a caller is never offered an argument that could not succeed. The signing key the served workspace’s own configuration names is not reached either — signing.key_path, whether it is set for the workspace as a whole, set against one registry, or supplied from the environment. One reason covers both: a key path is not a credential, it is a name for a secret this server holds. A caller supplying one proves nothing, anyone who reached this address could supply the same name, and the signature that followed would say the operator vouched for the artifact rather than the caller. Closing the argument while leaving the configuration open would be one door shut onto a room the other still opens. So keyed signing is unreachable over a listener: only a token sent in the call signs.

fulcio_url, rekor_url and timestamp_url are unaffected and stay on both transports. They name services to contact rather than anything this machine holds, so a caller that cannot select a key still signs against the endpoints this deployment configures.

A listener started over a workspace that names a signing key says so once, as it starts. The process writes one line on its own error stream naming the setting and saying that a caller reaching this listener cannot spend that key — so an operator learns it from the process they started rather than from a signature they did not expect. A workspace naming no key produces no such line, because there is nothing about it to say. The line carries the setting’s name and neither the key nor anything about the file it points at.

Over standard input and output none of the above applies. There the environment is read and key_path selects a key held on this machine, because the client that launched this server is running on the caller’s own machine and what that process can reach is that caller’s own to spend.

Reading an entity by its registry reference contacts one registry, with this host’s own login, and over a listener only a registry the served workspace is configured with. describe sent an oci:// reference as its name reads the entity published at that coordinate — the same read aggrega inspect performs — from the one registry the reference names, using the login this host already holds for that registry. The call carries no credential, and describe takes none. Over HTTP the registry must be one the served workspace is configured with: the host its default_registry names, or a host listed under registries, compared exactly and with the port. A reference to any other host — an address on this machine included — is refused before that host is contacted, and the refusal names the host, so a caller cannot point this server at a destination of its choosing. What stays reachable is deliberate: a caller holding aggrega:read can read whatever this host’s login can read on a registry the workspace is configured with, which is what a person at this host’s terminal can read too. Over standard input and output a reference to any registry is read, as it is at the command line. Describing an entity by its catalog name is unaffected.

A registry call uses the credential store of the operating-system user this process runs as, exactly as the same call does at a terminal on this host. There is no per-workspace credential source and no setting that adds one, which is why registry-list reports a host’s credential state the same way in every workspace on this machine. A deployment that wants different workspaces to hold different registry credentials runs them as different operating-system users — one process per workspace, each started as its own user. That is where the separation comes from, and arranging it is the operator’s.

What the server records

Every request this endpoint answers leaves one line on the process’s error stream, and that line is a single JSON object. It carries the time it was written and a request_id this process minted for the call and does not send back to the caller; subject and issuer as the presented credential asserted them, with client_id where it named one; workspace_root, the workspace this process serves; method, and target where the method addresses something by name; reach, the kind the operation declares, and reach_escalated_to where the call reached further than that; outcome; duration_ms; and transport. A field with nothing to say is left out rather than written empty, so an absent client_id is a credential that named no client, and an absent reach_escalated_to is a call that reached exactly what its operation declares.

outcome says what became of the call, and the values are distinct so you can count them apart. ok ran and succeeded. tool-failure ran and came back flagged as a failure the caller can correct — a call this server served rather than one it refused, so it does not belong among your refusals. error is a refusal carried back as a protocol error envelope. unauthenticated, forbidden and rate-capped are the credential, the origin-or-scope bound, and the per-caller rate cap turning a request away. cancelled is a caller that closed its connection before it was answered.

The reason a refused credential was turned away is a field of that same line rather than a line of its own. A refused request leaves one record like every other, with refusal naming the check that turned it away. No credential, and no part of one, reaches any line — not on a refusal, and not on a call that was served.

A caller that presented nothing at all leaves no line. Being challenged is how a client finds out where to obtain a token, so it is the first thing every well-behaved client does, and a line for each of those would bury the refusals that mean something. A request naming a path or a method this endpoint does not serve leaves none either: both are settled before anything about a caller is read, so scanning the address writes nothing into whatever collects the stream.

Trace context a client sends is copied onto the line verbatim. traceparent, and tracestate and baggage beside it where those are sent too, are carried through exactly as received, so whatever collects this stream can join it to the caller’s own records. A request that sends none, or sends one that is not well-formed W3C trace context, produces a line without those keys: nothing is invented, and nothing is altered on the way through.

The process records its own life in the same shape and on the same stream, each of those lines naming an event where a request line names a method and a caller: startup as it begins, listening with the address it bound, startup-refused with the reason a launch was declined before it served, signing-key-ignored where the workspace it serves names a signing key no caller reaching this listener can spend, docs-bundle with the outcome of acquiring the documentation bundle, and shutdown as the run ends. Reading for the presence of event is how the two kinds of line are told apart.

You collect all of it from the process’s error stream, and that is the whole of the delivery. There is no exporter to configure, no file to name, and no setting that turns any of it on, off, or elsewhere: whatever supervises this process — a container runtime, a service manager, a log shipper — is what collects that stream, and where you query it afterwards. Over standard input and output the same stream carries readable prose instead, because the client reading it launched the process and sits on the same machine.

None of it is sent to the caller. The server publishes no log stream over the protocol on either transport, and a request carrying the protocol’s per-request log-level field is answered exactly as one that carries none: what is recorded here is the operator’s, and it goes to the operator’s stream alone.

What the server tells the model when it connects

The server offers a block of guidance for the model, which your client may surface to it before the first call. A client on 2026-07-28 reads it from the server/discover answer; a client on 2025-06-18 reads it from the reply to its initialize handshake. It is the same text on both paths, byte for byte, and the same text for every client reaching one process: nothing in it is negotiated, and nothing is derived from what the client sent or from the credential it presented, so what a model is told on connect does not vary between sessions or between clients.

Two things vary, and neither is the client. The closing paragraph is composed for the transport a process serves, so a server speaking over standard input and output and a listener hand a model different closing text. And where the desktop bundle that launched a server comes from a different release than the aggrega executable it launched, the guidance opens with the one sentence saying so, naming both versions — the sentence the argumentless describe-capabilities answer opens with, as Which release the server comes from sets out; a launch no bundle made, and one whose bundle comes from the executable’s own release, hand the guidance without it. Both are fixed when the process starts, and within either process the two revisions still serve that process’s own text identically.

It teaches the mental model a tool’s argument schema cannot convey on its own:

  • What the compiler does, and what it deliberately does not do — that it routes text and evaluates label matches rather than interpreting what a value means, that it is unopinionated about the content you put in your documents, and that while compiling it never authenticates with a provider, never reads a cluster’s state, and never turns a secret into plaintext. A value that exists only once infrastructure is running travels through as a pointer string the target environment fills in later.
  • The authoring vocabulary, and how the kinds relate — what each kind is for and which one a build is actually run against, so an assistant does not have to infer the shape of a deployment from the tool list.
  • The order the authoring loop runs in — read the contract, scaffold from it, inspect what you are wiring to, then check before rendering.
  • When to reach for a prompt rather than a tool — a tool to act, a prompt to frame a task.
  • That the tool list is the whole surface — every tool this server offers is in it, and which tools a server offers depends on how it was set up, so an assistant reads what is here from that list and from describe-capabilities rather than going looking for a second one. Where the connection presented a credential, it says that the credential decides which of those tools a call may run and never which of them are listed: a call it does not admit is refused naming the scope that would admit it, and the client can sign in again for that scope.
  • What an empty workspace means, and what the model may do about it — the paragraph that differs by transport, below.

It names the surfaces rather than restating them. Each tool already carries its own description and argument schema in tools/list, and each kind’s contract already lives in its schema and its reference page, so the guidance points at those and stops — one home per statement. A tool it names is a tool the server serves, and it points at every resource family the read surface resolves, so nothing it sends an assistant after is a dead end.

It carries no index of the tools themselves, and that is the same rule rather than an omission from it. A client holds every tool’s definition from tools/list before it reads a word of this text, so a line per tool here would be a second copy of purposes it already has — paid for in every session, by every client, and free to disagree with the tool list the moment either of them was edited.

It also states what it does not enumerate, and why: the render targets available and the library kinds installed are properties of your plugins and your schema set, so the resource surfaces report them directly rather than the guidance carrying a copy that could disagree.

What a model is told about an empty workspace

The closing paragraph answers the question a model meets first on a workspace holding nothing: what an empty list-entities means, and what it may do about it. Its opening is the same on both transports — an empty listing means the workspace this process resolved holds no Aggrega documents it can read and the catalog directories configured beside it declare none either — and what follows it depends on which transport this process serves, because the honest answer is not the same on the two.

Over standard input and output the model is told the workspace is its to inspect and to repair. It is told where a call naming no workspace is answered — in the folder the server was launched with, where it was launched with one, and otherwise in the workspace found from the folder it was started in, which may be that folder itself — and that workspace_root on a call names another. It is pointed at config-show for the configuration in force and which layer decided each setting, and at cli-config-init for seeding a working one; both are in the tool list on that transport. The client running the server is on the caller’s own machine, so what that process can reach is that caller’s own to spend — and where you set the boundary is where it is set for every other tool, in your MCP client, as What an assistant can do without asking you first sets out.

Over HTTP the model is told to report rather than to configure. The workspace is the one you started the process over and is fixed for its life; a call naming workspace_root or catalog_dirs is refused, naming the argument; and no tool that writes configuration is offered to any caller here, whatever scopes its credential carries. Those operations are carried only by the tools that run an aggrega command in a separate process, and a session reached over HTTP is composed without them — so the bound is the composition rather than a scope, and no token widens it. A model reaching your deployment over a listener therefore cannot seed a registry or rewrite a trust policy on your host, and the paragraph tells it so instead of letting it try and read the refusal.

What an assistant can do without asking you first

An assistant connected to this server over standard input and output can call every tool the server exposes, without asking you, unless your client is configured to deny it. On that transport the server offers the tools and does not decide which of them any particular call is allowed to use: that decision is your client’s, and it is yours to make there. Over HTTP it is not the same: the server lists every tool it carries and announces, and refuses a call the calling token’s scopes do not admit, so the bound is the server’s as well as the client’s.

This matters because the tool surface is the command line. Anything you can type, an assistant can call — including the operations that change your machine.

Some of those operations reach further than the workspace you are working in, and cannot be undone by running something else. These are the ones worth knowing by name, widest reach first:

  • publish-entity, publish-artifact, sign-artifacts and deprecate-artifact reach past the machine entirely. They put bytes, a signature or a withdrawal marker in a registry, so what they change is what every consumer of that registry resolves — not only what this machine does. Re-publishing different content over a tag is refused rather than offered, so nothing here takes a publication back; the answer is to publish a new version. A signature and a withdrawal marker leave the artifact’s bytes untouched, but anyone who fetches that artifact afterwards fetches them too, and neither can be recalled from anyone who already has it. On standard input and output the same four capabilities are also reachable as cli-push, cli-push-artifact, cli-sign and cli-deprecate, which run the commands; over HTTP those four tools do not exist.
  • Signing uses credentials. Over standard input and output, keyless signing takes an identity token from the call’s identity_token argument, from AGGREGA_IDENTITY_TOKEN or SIGSTORE_ID_TOKEN in the server’s environment, or from the ambient GitHub Actions OIDC endpoint where one is reachable; key_path selects an offline held key instead. An assistant that can call these tools can therefore sign as you, with whatever identity the machine running the server already carries — and a signature is a statement about who vouches for an artifact, which is why this is the operation to think hardest about before allowing it. Over a listener only a token sent in the call signs: nothing in the server’s environment is read, and no key held on the host can be selected by an argument or by the served workspace’s configuration, as Which credentials a call spends sets out.
  • aggrega cache evict trims the compiled-module store, and aggrega cache clear wipes it. That store is shared by every Aggrega project on the machine. Modules removed from it are recompiled on demand, so nothing is lost permanently — but the next build of any project pays that cost. aggrega cache clear also removes the documentation bundle every project on the machine reads, which is fetched again the next time one of them acquires it.
  • aggrega cache prune reclaims artifact-cache entries no lockfile references. Where a project’s lockfile is not present to be read, its pinned artifacts are not protected by it, and reclaiming them means fetching them again.
  • aggrega registry add and aggrega registry remove write to the configuration shared across every workspace by default, so they change what resolves everywhere on the machine, not only here. aggrega registry add also asks the registry it names for the trust policy that registry advertises and pins what it is given, exactly as it does at a terminal. In an offline workspace that fetch is refused before anything is dialled, so adding a registry other than the official hub is refused — short code E0310, in the same words — unless the call supplies identity or key; aggrega config init, which takes neither, can seed only the hub offline. On standard input and output they are reachable as cli-registry-add and cli-registry-remove, and seeding as cli-config-init, which run the commands; over HTTP those tools do not exist.
  • pull reads from a registry and writes inside the workspace it is pointed at. It writes that Release’s lockfile, fills the artifact cache with what it resolved, and records the identity of each verdict-returning plugin your workspace attaches beside the lockfile. Sent pin_sources — or in a workspace whose pin_sources_at_pull is on and a call that does not send it as false — it also runs the entity author’s pin step over the Recipes and FeatureRecipes the Release builds from your catalog directories, writing the entity.lock beside each; without it, a pull over such an entity whose lock records no pin for an input it reads is refused, naming the step. The entity files themselves are never written. None of it leaves the machine, and resolving again is how you change what it recorded, so this is the mildest of the operations here that write. It is one of the tools shaped for the authoring loop that write inside the workspace: pin writes the entity.lock beside the Recipe or FeatureRecipe you name, as Pinning an entity’s own inputs sets out; gen-catalog writes generated Plugin entities under the directory you name; edit-document applies one bounded structured edit to a document you already have and writes it back, preserving every byte the edit does not touch, as Applying one bounded edit to a document sets out; and import turns a description another tool produced into draft authoring files and writes them into the workspace, as Turning a foreign description into draft entities sets out; and scaffold sent example writes one of the documentation’s runnable examples into a new or empty directory, dir, as aggrega scaffold --example does, which over HTTP the workspace-write scope admits. That output directory, the guest gen-catalog reads and any overlay you give it are each relative to the workspace root, or absolute over standard input and output, the same contract every other path argument on this surface uses. On standard input and output the same capability is also reachable as cli-pull, which runs the command; over HTTP that tool does not exist.
  • build reads the same registry and performs the same write when you send it auto_pull, and only then. Resolving a Release’s dependencies is one operation wherever it is asked for, so a build told to resolve first does exactly what pull does and then renders against what it wrote — which is why it carries the same reach rather than a lesser one. Sent write, it also writes the rendered artifacts to dist/ at the workspace root, where aggrega build writes them and through the same write, so it reaches the workspace for that call; it writes nowhere else, and a dist that is a link leading out of the workspace is refused before anything in it is removed or written. With neither argument, which is the default, build renders from the pins the workspace already holds and reaches nothing. Read Building against the content a Release already pins for what the argument changes and what it leaves alone.

The inventory tools say so in their own answers. cache-status marks each cache class with its reach — workspace for the artifact cache under this project’s own cache directory, machine for the stores every project shares — and names the machine-wide ones outright, so an assistant reading the inventory before proposing a reclamation is told which parts of it are not yours alone. The maintenance operations report the same reach for each element they removed. Each of the four publication results carries a reach of its own, holding registries — every registry host the call addressed, each named once, in the order it first addressed them — and beyond_this_machine, which is read off what the call actually attached rather than what it asked for: true once it has uploaded content or attached a signature, a publication date or a deprecation marker, and false for a dry run and for a call that found all of it already there, such as a publication run again over a complete version or a signing batch whose references were all already signed.

Where you set the boundary. The protocol itself defines no per-tool permission — its authentication is about whether a client may connect at all, not about which tools it may then call. The permission decision lives in your MCP client. Widely used clients can generally allow and deny individual tools by name from a single server, and disable a server entirely for a given project; the setting’s name and location differ per client, so consult your client’s own documentation for tool permissions. If you want the reads and not the writes, allow the tools you want and deny the rest there. A permissive configuration, or a client with no such setting, leaves every exposed tool callable.

Finding out what a workspace holds

Most tools take a subject: an entity name, or the path of a Release. The two below take none, and they are how an assistant that has just arrived gets one.

list-entities answers what the workspace holds and list-releases answers the narrower question the rest of the surface keeps asking: which Releases are there. Neither takes a subject, because what a workspace contains is a property of the workspace rather than of anything the caller has to know first.

Each answers in one of two shapes, and a call that names no shape gets the summary. That default belongs to these two alone, and it is the opposite of the one build, describe and validate take. Those are asked about a subject the caller already named, so the fuller answer is the one that was asked for and the terse one is the opt-in. These two are asked what is here, by a caller that has nothing to name yet and no way to know what the answer will cost before it arrives — so they report the size and shape of the workspace first and hand over records only once asked.

The summary says what is here and how much of it. list-entities reports the workspace root — kept back over HTTP, as What an answer says about the server’s filesystem sets out — the total number of entities, and a count per kind; list-releases reports the total and a count per top-level directory, so you learn how many Releases there are and which part of the tree they sit in. Both breakdowns are read out of the documents themselves, so a workspace laid out in a way nobody anticipated is summarised as accurately as one that is not. Both carry one row per kind, or per top-level directory, so their size follows how many kinds a workspace declares and how many directories its Releases sit in rather than how many documents it holds: multiply the documents in a workspace by a hundred, leaving its kinds unchanged, and the summary grows only by the few bytes the larger numbers take to write. Declaring more kinds is what makes it longer. Neither is a first page of records, and the difference is the point: “here are some of the entities” is a different answer from “this is what the workspace is made of”, and only the second tells you whether you want any records at all, and which.

Send response_format: detailed for the records, and they arrive a page at a time. list-entities then reports each entity’s kind, name, apiVersion, description, labels and source file, read straight from the document that declares it. It also reports the Features your configured catalog directories declare, so that a Feature offered to you as attachable is one you can also look up; those carry no source file, because the only path they have is one on the machine the server runs on, and each says where it came from so an empty file reads as “resolved from the catalog” rather than as a missing value. list-releases reports each Release’s path, and lockfiles maps each path it returned to the path of that Release’s lockfile, in the same coordinate: the file pull writes for it and build reads, the same file the language server’s Release answers name. The map describes the paths this answer carries, so it follows the page, and the summary carries it empty.

detailed and concise are the only values response_format takes, and they are matched exactly. Any other spelling — a different word, a different case, or whitespace around one of them — is refused, and the refusal names what was sent alongside the values the argument accepts. Leaving response_format out is how you ask for the default, which for these two tools is the summary. The same holds wherever the argument appears: build, describe and validate take the same two values on the same terms, and their default is the fuller shape rather than the terse one.

The records are bounded whether or not you bound them. limit is how many one answer carries, between 1 and 500, and it defaults to 50 — so a call that asks for records and names no page size is still bounded, and no invocation of either tool returns an answer the workspace’s own size decides. offset is where in the listing to start, counting from 0. Both bound the records, so neither has any effect on the summary, which carries none. A limit outside that range is refused and names the bound; an offset past the end of the listing comes back empty, because there is nothing there rather than anything wrong with the question.

Continue a listing by reading three fields off the answer. count is how many records the workspace holds, offset and returned say where this answer starts and how many it carries, and more_remaining says whether any are left. While more_remaining is true, call again with offset plus returned. That signal is computed from the page against the total rather than written onto the answer, so it cannot report that nothing remains while records do.

That all matters because the tools that do take a name refuse one they cannot resolve rather than answering with an empty result. The refusal is deliberate — an empty answer would report a mistyped name as a subject with nothing to offer — but it means a caller holding no name cannot get one by guessing. Enumerating is the way to get one.

The two compose, and with the rest of the surface:

  • Call list-entities for the summary to see which kinds the workspace holds and how many of each, then call it again with response_format: detailed for the records, take a name out of the result, and hand it to describe to see that entity’s fully-resolved definition. It is the definition the language server’s aggrega/entityDefinition answers with, carried as JSON: each key under the name its author writes, in the order the definition holds it, a schema as the schema the author wrote, and a schema the entity does not declare left out — a Component’s sockets each with the slots their connections may fill.
  • Do the same with list-releases, take a path out of the detailed result, and hand it to describe or build as the Release to work on.
  • The path list-releases returns is relative to the workspace root, which is the same coordinate list-entities reports a file under, so the two answers line up on the file and can be read together. Its lockfile, under lockfiles, is relative to the same root, so you can read or compare that file without working out where it lives.

Both decide what counts by reading each document’s own kind, never its filename. A Release named without a conventional prefix is listed; a file merely named like one is not, and appears under whatever kind it actually declares. YAML that declares no kind at all — a chart’s values file, a configuration file that happens to sit in the tree — is not an entity and is not reported, and neither is a document belonging to another project, such as a rendered Kubernetes manifest. A document counts as an entity when it declares both a kind and a name, because those two together are what makes it addressable afterwards, and declares no apiVersion outside Aggrega’s own group. One declaring no apiVersion at all is reported, being an Aggrega document with a field missing rather than another project’s file. list-releases searches no directory outside the workspace root, so a Release your editor shows under a link leading to one is not listed; unread_linked_dirs names each link that stands where the listing would read a directory and leads outside the root — by the link’s own path relative to the root, never by where it leads — in both shapes and on both transports, and is empty where there is none. Nor does it read a file outside the root through a link: unread_linked_files names, the same way, each link whose own name ends in .yaml or .yml and that leads to a file outside the root, whatever that file holds, so a Release reached only through one is not listed — unless the workspace configuration names that Release, as build.authoring_release or as a key of workspace.releases, in which case it is read and listed at the link’s own place and not named. list-entities reads no document behind a link leading out of the workspace either — it searches no directory outside the root, and reads no file outside it whatever that file declares — and names each such link the same way, in its own unread_linked_dirs and unread_linked_files, in both shapes and on both transports. That holds whatever the document declares, with the one exception list-releases makes: a Release the workspace configuration names, as build.authoring_release or as a key of workspace.releases, is read and listed at the link’s own place and not named, while a file one of those settings names that declares anything other than a Release is not listed, and its link is named. The configured catalog directories are how a workspace reads other entities kept elsewhere, so a link to a directory the configuration lists under catalog_dirs, or to a directory beneath one, is not named by either listing: the configuration has reached it. The Features list-entities takes from the catalog directories never include one behind a link leading out of the directory a catalog directory’s reads must stay inside — the workspace, for a catalog directory inside it, or the directory itself, for one the configuration names outside it — so an entity named as behind a link that was not read is never listed beside that name. A link the listing leaves out — by its name, by where it sits or by a .gitignore — is not named, and with release neither is one under a catalog directory only other Releases read; a .gitignore that is itself a link leading out of the workspace is not read. Where any of these lists names a link, the text answer closes with a line of its own saying so.

A workspace whose configuration file leads out of it is still listed, and nothing else is answered for it. Where the workspace’s own .aggrega-config.yaml, or the CI-owned overlay beside it, is a link leading out of the workspace, its configuration is not read, as at a terminal, and nothing it would have configured is read in its place. The server still starts over standard input and output, and says so in one line on its error stream. list-entities and list-releases answer with the workspace’s own documents, read with nothing configured, so no catalog directory’s Features are listed. Each names the held file in unread_linked_files, and in the line closing its text, whether or not the listing met it — that name is how you tell that the workspace’s configuration leads outside it. A listing sent release or catalog_dirs, and every other tool naming that workspace, is decided by the configuration that was not read, so each is refused with E0321, naming the link and where it leads. A server told on its command line to listen — --transport http, or --listen — does not start over such a workspace, because the address it would bind, its certificate and who may call it are what that configuration decides. Remove the link, or make it lead to a file inside the workspace, and the next call reads the configuration. See the workspace boundary.

Asking in one Release’s terms

A workspace may give each Release catalog directories of its own — see Giving a Release its own catalog directories — and so keep a variant of one entity per Release side by side. Three tools that otherwise answer over the workspace’s own catalog directories take an optional release, the path of a Release file, and then answer in that Release’s terms:

  • list-entities with release lists the entities that Release sees. The Features listed are the ones its catalog directories declare, and a workspace document under a catalog directory only other Releases read is left out, so each variant is listed for the Release that builds with it and for no other. A document under no catalog directory at all — a Release, its Aggregate and its Manifest written beside the catalogs — is listed for every Release.
  • describe with a name and a release resolves the name through that Release’s catalog directories, so a name several variants declare resolves to the one that Release builds with. A name those directories do not resolve is refused with an account naming that Release’s entry under workspace.releases. A registry reference is read from its registry whichever Release is named, so it is refused beside a release. A release sent with no name is still the Release describe summarises.
  • validate with an entity and a release runs the single-entity checks in that Release’s terms: the entity’s references — the Component a Recipe implements, a SchemaLibrary a pillar refers to — resolve through that Release’s catalog directories, and the answer names the Release beside the entity. No closure is validated; a release sent with no entity is still the Release scope. catalog_dirs is prepended to the Release’s directories here as everywhere. A directory the workspace configuration lists that is not a directory — nothing exists there, say — for that Release, or for the workspace when no release is sent, refuses the call before anything is checked, its text carrying the refusal every command gives it, naming the entry and the configuration file and line listing it (Where local entities are read from), as aggrega validate refuses it.

A release naming a file that does not exist, or naming a directory, is refused on all three rather than answered in the workspace’s terms. Sending none answers over the workspace’s own catalog directories.

describe looking a name up refuses a catalog directory it would resolve the name through that cannot be walked, as aggrega inspect refuses it — that Release’s directories where a release is sent, the workspace’s own where none is, and any the call names in catalog_dirs. A directory the call names that does not exist, or one that is there and cannot be read, is refused before the name is looked up, and the text names the directory as the command line reports it, on one line — the directory, catalog load, and the reason the filesystem gave — rather than resolving the name from the directories that remain. A directory the workspace configuration lists that is not a directory is refused at the same moment, the text carrying the refusal every command gives it (Where local entities are read from). A release naming a file that does not exist is refused ahead of that, as above. A catalog directory holding a link that leads out of the directory its reads must stay inside is refused the same way, the text naming the link and where it leads, because a name resolved without it could resolve another entity of the same name in its place. Describing a Release’s dependency closure is unaffected by a directory that cannot be walked, and answers over the directories that can be, as aggrega inspect --closure does — except a directory the workspace configuration lists for that Release that is not a directory, which it refuses as aggrega inspect --closure refuses it; a link leading out of a catalog directory’s reads, or out of the documents beside the Release, halts it, as it halts a build.

validate with an entity reports a render it cannot judge as not attempted, in a Release’s terms or in none. It places a Recipe’s Component in a synthesized build that wires no connection and attaches no Feature, so a Recipe whose render stops while its templates — the files and library entries they import included — read anything under .context.inject, .context.uses or .features answers valid: true with nothing in diagnostics; its text carries Render: not attempted (this Recipe reads values a build of one cannot supply), the reads it was set aside for, and the sentence the render stopped on. What decides it is what the Recipe reads, so a fault of the Recipe’s own beside such a read is set aside with it, while a template that does not parse and a reference the render refuses still answer valid: false. aggrega validate gives the same verdict on the same inputs.

validate with an entity reports a failed assertion as a warning, in a Release’s terms or in none. An assertion that calls fail — the Recipe’s own, or one the Component it implements declares — answers valid: true with nothing in diagnostics. The synthesized build carries placeholders and schema defaults in place of the values a real Release sets, so an assertion over such a value fails there whether or not the Recipe is sound, and the check cannot tell an assertion waiting on a Release from one that is broken. The failure follows the other notices, in the assertion’s full message closed by the sentence A Release must satisfy this assertion before a build of it can pass., and the text carries it on a line opened by warning:, beside the report line saying where the run stopped. An assertion that stops on a key it reads but does not find is a fault in its own text rather than a failed assertion, and is judged as any other stop is; a build of a Release that does not satisfy an assertion is still refused on it. aggrega validate gives the same verdict on the same inputs.

Reading the configuration in force and the plugins this server resolves

config-show reports the configuration in force and which layer decided each setting. plugin-list reports the plugins this server can resolve and what each of them says about itself. Both read and write nothing, so each reaches nothing and aggrega:read admits it — and neither asks you to name a subject, because what is configured and what resolves are properties of this server rather than of anything you have to know first. Each takes an optional workspace_root on standard input and output; over HTTP that argument is refused, as One process, one workspace sets out.

Together they answer one question in two halves: whether a capability is absent or merely not configured here. The configuration says whether a provider, an importer or a governance check is attached at all; the plugin reading says whether an attachment reaches a guest that resolves, describes itself, and serves what it claims to. From everywhere else on this surface those two look alike, and they call for opposite next steps.

config-show reports one entry per setting: its field, its effective value, and the source that decided it — a config file, an environment variable, a command-line flag, or the built-in defaults. Beside them, layers carries the layers that contributed in precedence order, lowest first. A setting’s source is spelled exactly as the matching entry in layers, so the two join directly, and a setting the defaults decided names no layer at all, because the defaults are not a layer that contributed. The global layer is the file the server’s own command line selects — the one --config named when it was started, otherwise the one the AGGREGA_CONFIG environment variable names, otherwise the default location — so a setting that file decides is attributed to that file, exactly as aggrega config show --origin attributes it, and a flag such as --offline given to the server is reported as that flag. It takes no response_format and no page size: the settings are the fixed set this binary accounts for and every resolution reports every one of them, so the size of the answer follows the binary rather than what you configure.

plugin-list answers in the two shapes the workspace listings use, and a call that names no shape gets the summary. The summary is a count per group, and there are two groups — embedded, the guests compiled into this binary, which resolve with no filesystem, cache or network access, and configured, the workspace’s own bindings. Send response_format: detailed for the records: each plugin’s group, the reference it was found under, where that reference was bound, its self-reported type, version, commit, served capabilities, rendered input kinds, boundary assembly and exports, its readiness where it has one, and whether it resolved. The records are bounded by limit and offset on the same terms the entity listing uses, with count, returned and more_remaining to continue by. This answer does grow with what you configure — the built-ins are fixed, the bindings are yours — which is why it is paged and the configuration reading is not.

A plugin that fails is reported with its failure rather than dropped from the listing. resolved says whether the reference reached module bytes at all, and a plugin that resolved but could not describe itself is reported as exactly that — so an attachment that is present and unusable is distinguishable from one that was never made.

What a listener does not tell you about its host

Over HTTP neither reading reports a value that names a place on the server’s filesystem. A client that launched the server runs where the server runs, so every location either answer could name is one that caller already owns and can go and look at. A caller reaching a listener chose none of them, cannot act on knowing them, and a server that has published them to such a caller cannot publish them back. Over that transport those values are absent; over standard input and output all of them are present. It is the rule every answer on this surface follows, as What an answer says about the server’s filesystem sets out, and these two readings are where it reaches furthest, because most of what they report is configuration that names places.

What is kept back. From config-show: a setting’s value where that setting’s own value is a location — a serving or health address, which may be a socket file; a certificate, private-key or key-set file; a catalog directory, and a Release’s own catalog directories under workspace.releases, whose every entry is keyed by a Release file; a plugin reference; an authoring Release. Also a setting’s source where the layer that decided it is a config file, since such a layer is named by that file’s own path — and, in the same spelling and for the same reason, the config-file entries of layers. From plugin-list: a plugin’s uri where that reference is itself a filesystem path, and the text of a resolve-or-describe failure, which is composed from the places that were tried and so names locations the reference itself does not. From both: workspace_root.

What is reported whole, on both transports. A registry reference, a version, a commit, a digest, a served capability, a readiness label, the name of an environment variable or of a flag, and a layer that is not a file. origin on a plugin record is one of these: it is the config key a binding was written at, or the pinned digest an installed command extension carries, and a built-in carries none — so it is the same string wherever the plugin is read from. resolved is another: whether a plugin failed is reported to every caller, even where the reason for it is not.

An absent value always says it was kept back, and that is what makes the answer usable. A value withheld is reported as absent with a mark beside it — value_withheld and source_withheld on a setting, withheld on a layer entry, uri_withheld and error_withheld on a plugin record, and workspace_root_withheld on the answer. A setting nobody set carries the empty value its shape renders as, and carries no mark. “This server is not telling you where the signing key is” and “no signing key is configured” are different answers calling for different next steps, and a reading that reported them identically would tell you nothing you could act on. Each answer also carries host_locations_withheld, always, which says which of the two answers you are holding: an answer carrying no marks is otherwise the same whether this rule shaped it and there was nothing on the host to keep back, or it never applied. The readable text beside the fields says the same thing in words.

The rule is a property rather than a list of field names: a value is kept back when it names a place in the host’s filesystem, whoever set it and whichever layer it came from. A value added to either reading later is held to that same property.

On standard input and output each capability is also reachable as the tool named after its command — cli-config-show and cli-plugin-list — which run that command in a separate process and hand back the text it printed; over HTTP those tools do not exist. The two described here carry the values instead, so you read whether a capability is attached, or pick out a plugin’s version, without parsing a column layout back into what it was rendered from.

Asking what may attach, and what may connect to what

Two tools answer the questions an assistant would otherwise have to guess at: which Features may attach to a node, and what a node may connect to. Both run the same label match the compiler runs, so what the assistant offers you is the set a build would match rather than a set inferred from the schema.

attach-candidates reports the Features whose declared applicability a node’s labels satisfy. Address the node in exactly one of three ways:

  • node — a workspace entity’s metadata.name, as list-entities reports it. The match runs over the labels that document declares.
  • graph_node with release — a node on a compiled graph, keyed as the graph keys it, including the qualified form a node contributed by a sub-aggregate carries. The match runs over that node’s finalised labels, which are the ones a build evaluates.
  • labels — a label set on its own, naming no node. It needs no coordinate at all, so if you already hold a node’s labels this is the form to use; it looks nothing up and rebuilds no graph.

The answer carries the labels the match ran over and which of those three sets they came from, so you can explain any candidate — or the absence of one — from the answer itself rather than working it out again. Reading them back a second way is how your idea of a node’s labels and the compiler’s come apart.

To ask what may attach to one connection a node draws, add connection beside graph_node and release — its socket and its alias, as the author wrote them. A connection carries attachments filling the slots its socket declares on the consuming Component, so the answer then also carries slots: each slot the socket declares, with its selector, required, inject, sensitive and description exactly as the Component declares them, and the candidates that may fill it. Those are the Features whose applicability the node’s labels satisfy and whose own labels the slot’s selector admits — the two rules a build holds such an attachment to — so a slot’s candidates are always among the node’s own. Where nothing may be filled, slots is empty and noSlotReason says why: feature-created-connection (a Feature drew the connection, and nothing is attached to one), ad-hoc-socket (the socket is one the Component does not declare) or no-slot-declared (the socket declares none). Do not read an empty slots as “nothing matched”; that is what the reason is there to rule out, and it is absent wherever a slot exists. candidates beside them keeps its meaning — what may attach to the node itself — and document, if you send one, changes nothing here. connection beside node or labels, or naming no socket or alias, is refused, and so is a connection the node does not draw. These are the same answers the language server gives, on the same terms.

connection-candidates reports the dependency sockets an entity declares and, per socket, the workspace Components whose declared labels satisfy the constraint that socket declares over its targets. It takes the entity’s metadata.name in node. Unlike attach-candidates it has no coordinate-free form: there is no label-set shape here, because the sockets are read from the named entity’s own declaration.

Its two halves are not equally complete, and the answer says which is which — do not present them as one list. The targets are complete: those are the components the same constraint admits during a build. The sockets are not, and cannot be. A consumer may invent a connection but may only consume what a producer declares, so an author may legitimately write a socket the catalog entity never declared, and the declared sockets are a helpful start rather than the set of legal names. Each socket therefore says whether it is declared or ad-hoc, and the answer says whether an undeclared socket is accepted on that entity at all — a Component’s own dependency surface accepts one, because an author owns their application’s topology; a Feature’s attachment surface does not, because an attachment participates in the topology the attached Feature declares rather than authoring one. That openness is a consequence of your authoring freedom, not a gap: pass socket with a name the entity does not declare to ask about it.

Both answer and stop. Neither creates an attachment, creates an edge, writes to any file, or proposes the text of one; composing and applying whatever edit follows is yours.

Both return the same minimal identity every other answer here uses — kind, name and source file — and nothing more. Everything else you would want to display about an entity is already in list-entities for the same three fields, so you join the two answers rather than reading two copies that could disagree. Both refuse a name they cannot resolve rather than answering with an empty list, for the reason the rest of the surface does: an empty answer would report a typo as a subject with nothing to offer. A labels call has no name to mistype, so an empty result there means what it says.

Everything the server reads for reference is served from this machine — the JSON Schemas are built into the binary and the documentation is read from the documentation-bundle cache the machine keeps, as described below. Drafting a starter document, validating, describing, building and linting all run against your workspace and the local caches, and none of them reaches a registry of its own accord: a render serves a pinned external reference from the content-addressed store and declines an unpinned one rather than fetching it, which is what keeps the whole inspecting-and-rendering loop offline. Two registry reads you can ask for: describe given a registry reference, which fetches that one coordinate, writes nothing, and over HTTP reaches only a registry the served workspace is configured with; and scaffold sent example or list, which acquires the documentation bundle from the workspace’s default registry where the machine holds no copy the workspace’s signature policy admits, verified before it is kept, as aggrega scaffold --example does. Publishing and signing are the deliberate other side of that, and they are covered above.

Between the two sits resolving a Release’s dependencies, which is the one thing here that acquires: it reaches a registry because being asked to resolve dependencies is being asked to fetch them. It happens only when you ask for it, and there are exactly two ways to ask — calling pull, whose whole job it is, or sending auto_pull to build, which performs that same resolution as the build’s first step. Nothing pulls on your behalf otherwise, and a build you did not send auto_pull reaches no registry. The one setting that changes this is the workspace’s own auto_pull: a workspace configured that way is asking every build in it to resolve first, wherever that build is run from, which is covered below.

The one exception among those reference reads is acquiring the documentation bundle itself, and it happens away from every read. The bundle is kept once per machine, in the cache every Aggrega project shares, one copy for each registry and version — so a server started in a folder where no workspace cache can be created keeps it all the same (see aggrega cache). When the server starts, before it answers anything you send, it looks there for a copy your workspace’s own signature check admits — the same check a pull of the bundle answers to — and pulls the bundle, through the same egress settings the rest of the CLI uses, only when there is none. The bundle it looks for is the one published for the version of aggrega the server runs, or, where none is published for it, the newest one published for an earlier version — the same choice aggrega explain and aggrega scaffold --example make — and every page it serves, and every explanation, is read from the one it obtained. So the pages are already there by the time anything asks for one, whatever your client happens to send first, and another server, or aggrega explain in another project, finds the same copy rather than downloading it again.

Serving a page is then a read of that copy, and it reaches no registry. Before a page is served, the signatures kept beside the copy are verified again under your workspace’s check, so a copy another project’s looser setting let in is not served to you: where the check pins a key or a trust root that verification runs offline, and where it pins neither — the official hub’s built-in check is one such — it obtains the public Sigstore trust root, as a pull does. An offline workspace cannot fetch that trust root, so offline it verifies against the trust root an earlier online fetch on this machine left in the cache the Sigstore client keeps under .sigstore in your home directory, however long ago that fetch was, and fetches nothing; on a machine that has never fetched it the check cannot run offline, the copy is not served, and the log stream says so. That verification runs once for each copy and each check while the server runs, and the pages read after it are served on what it admitted: a copy fetched since, a workspace whose check differs — a pinned trust root edited in place included — a read made offline, or an offline read finding a different trust root left on the machine is verified for itself. A copy your check refused is checked again on the next read, so a fetch that has since admitted it is not overruled. If the bundle cannot be acquired, or the only copy is one your check refuses and fetching it again under that check fails, the server still starts and every other surface works; documentation requests answer not-found, and the server’s log stream says why.

Building against the content a Release already pins

build renders a Release into its artifacts in memory, and a render can ask for content from a remote URL — a chart’s values schema with a remote reference, for example. External inputs are frozen for the call. A reference the Release’s lockfile already pins is served from the content-addressed store, which is a read of content already on disk rather than a fetch. A reference the lockfile does not pin is declined and named rather than fetched: what you asked for is a render, and acquiring a reference would both reach the network and write a blob into the store as a side effect of producing bytes. That freeze is a property of the render. Resolving is the step that acquires: it renders the Release to find out which remote references that render asks for, fetches them, and records them in the same lockfile write that carries the dependency pins. So what resolving changes is which references are pinned by the time a render runs, never what a render may reach — and a reference no resolution pinned is declined on a call that resolved first exactly as it is on one that did not.

The files come back as the bytes a real build emits, and two things together are what make that true. One is the freezing above: a pinned reference is read from the store rather than fetched. The other is that the lockfile being read from still describes what the Release resolves to — so build checks that, and refuses a lockfile that no longer matches, exactly as aggrega build does at a terminal. Reading pinned bytes says nothing on its own about whether they were the right bytes to read.

All three lockfile states, so the posture is explicit. With no lockfile at all, build renders from whatever the workspace already pins and declines every external reference it cannot serve, naming each one; left to itself it neither requires a lockfile nor writes one, and that is unchanged by the check above — there is no lockfile for it to compare, so nothing is refused. With a lockfile that matches, it renders. With a lockfile that no longer matches, it refuses, and the refusal names how to clear it: call pull with the same release and no upgrade_targets, which reconciles the lockfile against what the Release resolves to today. The refusal also carries the terminal form of that same operation, aggrega pull --release <release>. Either invocation clears it; they are one operation reachable from two places, not two instructions to choose between. Where pull completes and the refusal comes back, the two calls resolved over different inputs — most often catalog_dirs given to one and not the other, or a workspace configuration edited between them — and the refusal says so: call both with the same ones.

validate and describe sent a release alone are held to the same lockfile. Over a lockfile that no longer matches what the Release resolves to, each refuses rather than answering, its text carrying the drift halt build refuses with and the same way to clear it — as aggrega validate --release and aggrega inspect --closure refuse at a terminal. With a lockfile that matches, or with none, each answers as it otherwise does.

Asking a build to resolve its dependencies first

Send auto_pull and the build resolves before it renders. It performs the same resolution pull performs — the operation itself, not a second one written for a build, so a workspace filled by a build and one filled by a pull call are filled identically — writes the Release’s lockfile, and then renders against what it wrote. That step reaches a registry and writes, which nothing else about build does but write, and write reaches no registry — so it is off unless asked for.

It answers the two refusals above without leaving the protocol. A Release nobody has resolved yet renders from whatever pins happen to be there and declines the rest; a lockfile that has drifted stops the build outright. Sending auto_pull resolves first and renders against a lockfile derived from the closure this build is about, so both cases come back as a render rather than as something to go and fix. Where you want the resolution and the render as separate steps — to read what was pinned before rendering it — call pull and then build, which is the same two operations with a look in between.

One call renders the Release once. Finding out which remote references a Release consumes is itself a render, so a resolution has already rendered the Release the build is about — against the very pins it just wrote, with every gate a build runs. The build is answered from that render rather than repeating it, which is why sending auto_pull costs a resolution and not a second render. Only a render that finished is used that way: where a resolution pinned its dependencies but could not finish discovering the external references, the build renders for itself against the pins that did land, and an unpinned reference then halts it by name rather than coming back as a file list stopping short of what a build emits.

What comes back says what was resolved. A build that filled carries dependency_resolution on its answer, in the shape pull answers with: the lockfile it wrote, every reference the resolution reached with the version each resolved to and where this build’s resolution took it from, the counts the lockfile holds afterwards, and the resolution’s own account of itself line by line. A build that did not fill carries no such field at all, so its presence is how you tell the two apart without reading the disk. The rendered files are reported exactly as they are for any other build, and they are still returned in memory unless the call was also sent write — resolving writes the lockfile and the artifact cache, never an artifact.

A workspace can ask for it standingly, and a call cannot turn that off. The workspace’s own auto_pull setting turns the same step on for every build in that workspace, and auto_pull on a call adds to that setting rather than overriding it: either one is enough, and there is no argument that suppresses a resolution the workspace asked for. That is the same way the setting and aggrega build --auto-pull combine at a terminal, so one workspace answers the same way whichever surface a build arrives on.

Declining is reported rather than absorbed, and with the providers this binary carries a decline stops the render: the provider that asked for the reference hands the refusal back, so the call answers with that failure and returns no files. The reference is named where a reader can act on it, alongside the command that pins it: aggrega pull --release <path>. The same pinning is reachable on this surface as the pull tool, described in Resolving what a Release depends on below, so an assistant that meets this refusal can act on it without leaving the protocol. A fully-pinned render says nothing about any of this. See aggrega pull for what pinning fetches and records, and aggrega build, where an unpinned reference is reported and halts the run in the same way.

Writing the artifacts where aggrega build writes them

Send write and the finished render is also written to dist/ at the workspace root, where aggrega build writes it. The directory is the one the command line composes beneath the same workspace root, and the write is the one it performs, so for one Release in one workspace aggrega build, the language server’s aggrega/build naming no outputParent, and this call write one tree, byte for byte, and name that directory alike — the command’s closing line, the language server’s outputDirectory and this answer’s output_dir. A dist that is a link leading out of the workspace is refused before anything in it is removed or written, as it is at a terminal. Left out, which is the default, the artifacts are returned in memory and nothing is written.

The workspace root is the call’s own. Over standard input and output it is the root of the workspace the call resolved, as Which workspace a call is answered in sets out: the root workspace_root names, else the root the server was launched with, else the workspace found from the directory the server was started in — and, where a Release named by an absolute path moves the call into that Release’s own workspace, that workspace’s root. It is the root aggrega build writes beneath for the same Release and the same named root, so the folder the server happens to run in receives a dist only where that folder is the root the call resolved, as it would at a terminal opened there. Over HTTP it is the workspace the server serves, and nothing is written outside it.

Writing reaches the workspace, so over HTTP it needs aggrega:workspace-write. A call sent write reaches the workspace for that call, exactly as a build that resolves its dependencies first does: a credential carrying aggrega:read alone is answered 403 naming aggrega:workspace-write, and nothing is written, and a server whose mcp.deny_reach names workspace refuses the call naming that setting. The tool stays on every caller’s tool list, and a build not sent write stays available to a read-scoped caller.

It writes last. With auto_pull as well, the call resolves, renders and then writes, in that order. A call refused at any earlier point — its Release, its workspace, a catalog directory, the resolution, the render — writes no artifact.

The answer names what was written. output_dir is the directory — in full over standard input and output, dist over HTTP — and files lists each file written, relative to it, with its content under response_format: detailed and its path alone under concise; the text says how many files were written and where. A call not sent write carries no output_dir, so its absence is how you tell that nothing was written. A write that fails once the render has finished — into a workspace root nobody may write in, say — answers as a failure naming the directory and the cause, and lists no file as written: part of the write may be on disk, and naming the rendered files as written would claim more than happened.

No argument names a directory, and none asks for a trace. Where the artifacts go is decided by the workspace the call resolved, never by the call, and a build written from here leaves no .trace directory beside its output; a traced build is aggrega build --trace.

What a build tells you besides its files

A build carries every advisory it raised, on the answer itself. These are the findings aggrega build prints while it works — a name one edit from a declared one, a parameter nothing reads, a target that cannot honor an authored field, a non-halting governance verdict, a boundary directory a Release inherited from the Release it extends that resolves to the same path, a property a Component or Feature the Release reaches declares in both its values and infra pillars. None of them changes the outcome: a build that carries advisories still succeeded, and the files it returns are the files it produced. They arrive in the order a terminal prints them, so a reader comparing the two finds one sequence rather than two: first everything the render raised, in the order it raised it, then the findings about the Release and what it reaches, which aggrega build prints once the render has returned, and last, on a build sent write, the warning naming each file the write found beside its own that it did not write, which it leaves in place — the one aggrega build prints once its files are written (Files the build did not write).

They are on the answer rather than only in the summary text because an assistant driving this surface reads no terminal, and a finding nobody is told about is a finding that was not made. Each carries a severity — warn for something wanting attention, info for an observation recorded — and a message; a code where its class assigns one, so you can react to a specific condition without matching text; and a key_path naming the key in the authored document the finding is about, where it is about one. A finding about the shape of the deployed topology names no key, because its coordinates are the deployment’s rather than a document’s, and says what it concerns in its message instead.

Two kinds of finding a terminal prints reach this answer somewhere other than advisories, because each has a home that says more. A recorded deprecation marker is on deprecations, whether the lockfile recorded it against a pinned reference or the plugin trust record beside it recorded it against a plugin attached in a role that returns an accept-or-reject verdict. describe of a Release names the same set in its own deprecations, and validate of a Release among its notices, each leaving the verdict as it is; a trust record that is there and cannot be read refuses either call rather than passing as one that records nothing. A parent an entity inherits from that could not be resolved stops the build, so it is named in the refusal’s text rather than listed as a finding that changed nothing. One kind is bounded by what this tool loads rather than by what its answer carries: aggrega build loads every configured catalog directory before it resolves a Release, and a notice about a deprecated catalog shape would come from that load, while this tool reads only what the Release reaches and performs no such load, so it reports no such notice. No build raises one at present, so the two report the same findings.

A Release raising nothing says nothing: the key is absent rather than present and empty, so its presence alone tells you there is something to read.

What a refused build hands back

A build that refuses answers in the same fields a build that succeeded answers in, populated as far as the run got. It comes back flagged as a failure with the correction as its text, and the structured payload sits beside that text rather than being replaced by it. A refusal raised while the Release renders reads in the compiler’s words, as A refusal raised while rendering below describes, and adds one field of its own. The advisories are in it: the phases that ran raised what they raised, and those are the findings you have to act on to get past the refusal, so they arrive as entries you can match on rather than as prose you would have to parse. deprecations and declined_external_inputs are in it for the same reason — a recorded marker is reported because a marker was recorded, and a declined reference because a reference was declined, and neither of those facts is a consequence of how the run ended.

files reports nothing on a refusal, and it is not the field to read the outcome from. Nothing was emitted, so there are no artifacts to name. Do not branch on whether the key is there: it is reported either way, and an empty files cannot on its own tell a build that refused from one that ran and emitted nothing. Read the failure flag on the result — that is the protocol’s own discriminator — and read files for what it is, the list of what was rendered, and written as well where the call was sent write.

What bounds the advisories on a refusal is how far the run got, not what the answer is able to carry. A refusal from a check that runs before the Release has resolved — a pinned entry in the cache no longer matches the digest recorded for it and no catalog directory holds the pinned bytes, or what the Release depends on could not be resolved — reports no advisories, because nothing had been raised yet. The findings about how a Release composes with the Release it extends are raised the moment it resolves, ahead of every check that follows, so every later refusal carries them: the Manifest maps a type onto a recipe that does not implement it, an entity the Release reaches does not satisfy its schema, the lockfile no longer matches what the Release resolves to. The render’s own findings are raised as the render runs, so a refusal from one of those earlier checks carries none of them, and a refusal from the render carries everything raised ahead of it. So read advisories on a refusal exactly as you read it on a success: what this run found, in the order a terminal prints it.

A refusal because an entity inherits from a parent that could not be resolved names every such inheritance in its text, in the words aggrega build prints for it, so you know which one to repair. That detail is the reason the build stopped, which is why it is in the text rather than among the findings that changed nothing; the composition findings raised ahead of it are on advisories as for any later refusal.

A catalog directory the Release reads that cannot be walked is refused before anything is written, as aggrega build refuses it. That is a directory the call names in catalog_dirs that does not exist, as aggrega build refuses a --catalog directory that does not exist, or one that is there and cannot be read. aggrega build loads every directory the Release reads before it resolves the Release, and stops at one it cannot walk; build walks the same directories first, reading no document in them, ahead of any dependency resolution and ahead of the render — so a build sent auto_pull writes no lockfile, and nothing is rendered. The text names the directory as the command line reports it, on one line: the directory, catalog load, and the reason the filesystem gave. The payload names the Release, with an empty files and no finding, because nothing had run. A directory the workspace configuration lists that is not a directory — nothing exists there, say — is refused ahead of that walk, in the same shape, the text carrying the refusal aggrega build gives it, naming the entry and the configuration file and line listing it (Where local entities are read from). A catalog directory holding a link that leads out of the directory its reads must stay inside is refused at the same moment, with nothing written, the text naming the link and where it leads — aggrega build refuses it the same way.

A worked shape, so the halves are concrete. A Release declaring a parameter no reference reads, whose render then cannot complete, comes back as a failure whose text carries the render’s refusal and whose payload carries the unread-parameter advisory with its severity, message, code and key_path — the same entry, with the same values, that the same Release reports on the answer when the render does complete — beside the refusal entry for what stopped the render. A Release that extends another and inherits a boundary directory carrying no template variable, whose Manifest maps a type onto a recipe that does not implement it, comes back as that refusal with one advisories entry per inherited directory, each with code inherited-boundary-directory-is-literal. A Release whose dependencies cannot be resolved, in a workspace whose listed catalog directories all exist, comes back as a failure with no advisories key at all, because nothing had been raised when it stopped.

A refusal raised while rendering

A Release the compiler refuses while it renders — a Workload naming a slot its Component does not declare, an assertion that fails, a template that cannot be evaluated — comes back with the refusal in the compiler’s words and with every cause beneath it, the words cli-build hands back for the same Release: the node being rendered, then what in it refused. Where the refusal names a registered condition, the text adds what that condition is called — the short code and the descriptive code to match on — as explain-error would. The text opens by saying which stage refused: The build failed during rendering; nothing was written to disk. for a refusal the render raised, and The build refused before rendering anything; nothing was written to disk. for one the compiler’s run raised before anything rendered — the composition of the graph the render works from refusing, or an assertion a Component or a Feature declares.

The payload carries the same refusal as one entry, refusal, so a caller that has to change a document reads which one, and where, without parsing the sentence:

  • file — the document the refusal points at: a Workload’s Recipe, the Recipe or FeatureRecipe declaring a failing assertion, the Release or the Aggregate that wrote an entry the composition of the graph refuses, or the Release’s Aggregate for a refusal that points at no document.
  • key_path — the key there, where the refusal names one: .spec.workload for a refusal about a Workload, the assertion’s own key under .spec.assertions for a failing assertion, the entry’s own key for a refusal of an entry. A refusal about a Workload is placed on its workload key and no finer, because the Workload a check judges is what its template produced, and a template writes lines its author never wrote; the paths the refusal names inside that rendered Workload stay in its message.
  • line and column — that key’s position, counted from one, the column in UTF-16 units. Absent where the refusal names no key or the document does not hold it: a position is given only where one was found.
  • severity — halt, the severity of the finding that stopped a build.
  • code and short_code — the condition’s two identifiers, where the refusal names a registered condition.
  • message — the refusal’s text, exactly as it appears in the answer’s text.
  • findings — present only where the refusal joins several findings, as the composition of the graph does with every violation it found: one entry per finding, in the order the refusal states them, each in this same shape — its own file, key_path, line, column, severity, code, short_code and message. The refusal’s own fields then name where its first finding points, and its message carries every finding, as the text does; the command line prints each finding as a diagnostic of its own.

The entry is present whenever the compiler’s own run refused — while rendering, or before it renders: at the composition of the graph, or at an assertion a Component or a Feature declares, which names no document, so its entry names the Aggregate. A build that succeeds carries none, and neither does one refused by a check that runs before the compiler starts — the lockfile, the Manifest’s mappings, what the Release depends on — whose refusal is the text alone. A value an author declared sensitive is withheld from the refusal where the compiler raises it, so the entry and the text carry what cli-build and the terminal carry — see what a refusal says about a declared value.

Resolving what a Release depends on

pull resolves a Release’s catalog and source dependencies into the local cache and writes that Release’s lockfile. It is on this surface for a reason worth stating: the two refusals above — a render that declined an unpinned external reference, and a build that stopped because the lockfile no longer matches what the Release resolves to — are both answered by pinning, and an assistant that has to ask you to run a command has no way to answer them itself. Read What an assistant can do without asking you first for what it writes and how far that reaches.

Pass release, the Release path, absolute or relative to the workspace root — the same contract every other path argument here uses. workspace_root and catalog_dirs override workspace and catalog discovery exactly as they do on build. Both hold on a server reached over standard input and output; over HTTPS those two arguments are refused and the path must resolve inside the workspace the process serves, as One process, one workspace sets out.

By default it reconciles rather than re-resolving. A pin the lockfile already records is honoured and fetched at that version, and refused rather than silently re-pinned if the registry no longer serves those bytes. A reference with no pin — newly added, or removed from the lockfile by hand — is resolved fresh and added. A reference no longer among the resolved dependencies is pruned. An unchanged dependency set therefore leaves the file byte-identical, its recorded timestamp included, so a call that changed no pin produces no diff for anyone reviewing the workspace afterwards.

verify compares, and leaves the lockfile as it is. It checks the recorded lockfile against the resolution the reconciling call above would perform now, honouring the recorded pins exactly as that call does, and comes back as a failure on drift, or when there is no lockfile to compare against — so it is how an assistant finds out whether pinning is needed before anything rewrites the lockfile. Nothing that call records is written — not the lockfile, not the plugin identities recorded beside it, not an entity.lock — while the content cache is read and filled exactly as that call reads and fills it. It also reports the toolchain the lockfile records: the compiler version that wrote the file and the version of each core plugin that compiler carried. That is reported for audit and never compared against the running binary, because the toolchain is not part of what the lockfile pins and checking it would pin the compiler by proxy — a toolchain difference is not drift.

upgrade_targets re-resolves the references you name, and nothing else. Give it one or more entity URIs in the bare authored form — core/database, not a versioned form. Each named pin is dropped and re-resolved to the highest available version, while every other pin and the recorded external inputs are held unchanged. A URI that matches neither a recorded pin nor a configured attachment is refused rather than ignored.

There is deliberately no argument that re-resolves everything at once. The command line has that form, and it discards the whole lockfile before re-resolving from current registry state. On this surface the argument does not exist, so the call cannot be composed at all rather than being accepted and then refused: nobody is watching a protocol stream, so a wholesale discard has nobody to confirm it. Where you want it, and on standard input and output only, cli-pull runs the command, which is the surface where a person is present; a caller reaching this server over HTTP runs it at a terminal on the host instead. verify cannot be combined with upgrade_targets — one leaves the lockfile as it is and the other rewrites it — nor with pin_sources, whichever value it carries: that argument decides whether a resolution records the pins an entity.lock is missing or refuses over them, and a comparison writes no entity.lock, so it would do neither. A call sending either pair is refused before anything is resolved, with a sentence naming the pair. The tool’s advertised schema does not state these two exclusions, because a client rendering one can read it as a requirement to send verify; the refusal is where a client learns them. The command line and the daemon refuse the same pairs.

The result names what was resolved, not merely that something was. It carries the lockfile it wrote or compared against; resolved, every reference the resolution reached with the version each resolved to, the kind an author writes where the resolution records one, and its source — where this run took the reference from, in the word aggrega pull --detail prints for the same resolution: fetched-fresh, cache-reuse, local, in-binary or external; counts of the source artifacts, external inputs and trusted plugin identities the lockfile holds afterwards; and diagnostics, the resolution’s own account of itself in the order it raised each line — which pin was reused, which signature was checked, which version was skipped as withdrawn. Those lines reach a terminal when you run the command; here they are in the answer, because a caller reading no terminal has no other way to receive them. verified is present only on a comparison, so its absence is how you tell a run that wrote from one that only compared. A source describes this run on this machine, so the lockfile does not record it, and describe, which reports what a Release depends on, names none.

A refusal answers in the same fields, populated as far as the run got. Once the resolution has been computed, resolved is carried whatever the verdict — a drift verdict most of all, since that is the refusal a caller has to decide what to change about. A refusal from before that point, such as a Release path that does not resolve, carries the correction as its text and no resolution, because there was none to carry.

Where the pins are complete and the external inputs are not, the call still succeeds and says so. Discovering which external inputs a Release consumes is a render, and a render can fail after the dependency pins are already correct and on disk. Reporting the whole call as failed would tell you to redo work that is right, so incomplete_external_inputs is set on the successful result instead, naming what stopped: the dependency pins are complete, the external-input pins may not be.

This is the slowest tool here, and the reconciling no-op is not a fast path. A resolution pays its full cost to establish that a dependency set is unchanged, so a call that rewrites nothing costs what a first resolution costs — on a small Release, seconds rather than milliseconds, and it grows with the size of the dependency set. A verify is the cheaper of the two shapes, because a comparison skips the per-component source descent that a writing run performs. If your client imposes a per-call timeout, this is the tool to check it against. Asking to be told how it is going, below, means something arrives while the call runs rather than nothing until it ends — which answers an idle timeout in your client, or in whatever sits between you and a server reached over HTTP, but not a cap on how long one call may take in total.

An entity whose entity.lock records no pin for an input it reads refuses the pull, and the refusal names the step that records it. A Recipe or FeatureRecipe the Release builds from your catalog directories that reads a remote source written out in full, or imports a file through its artifacts, is expected to carry those pins beside it already — its author records them with pin, below. pin_sources asks this call to run that step on the author’s behalf over every such entity instead of refusing, writing the entity.lock beside each; it is the same step the pin tool runs, and it writes the same bytes. Leave it out and the workspace’s pin_sources_at_pull decides; send it and it decides in either direction, so pin_sources: false refuses even in a workspace configured to pin. An entity the resolution reached in the cache rather than in one of your catalog directories has no writable home here and is never pinned by this call.

Pinning an entity’s own inputs

pin records, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input the entity reads from outside its own document: a remote source whose coordinates are written out in full, and a file an artifacts entry imports. It is the same step aggrega pin runs at a terminal, and the lock it writes is byte-identical to the one that command writes. Pass entity, the entity document, absolute or relative to the workspace root under the same contract every other path argument here carries; over HTTPS it must resolve inside the workspace the process serves.

No Release is named, because none is needed. A source whose coordinates carry no template names one artifact for every Release that uses the entity, so the step resolves and pins it with nothing a Release supplies. A source whose coordinates come from a template is not pinned here: which artifact it names is decided by each Release, and pull pins each identity it resolves to in that Release’s lockfile.

The result says what the step did to the lock. It carries the entity, its kind and name, and pinnable, which is false for a kind that reads nothing a lock records — a Component or a Feature — in which case nothing beside the entity was touched and the other fields are absent. Otherwise it carries the lock it wrote, changed, false when the lock already recorded every pin and was left byte-identical, removed where the entity now reads nothing a lock records and its lock was deleted, and pins, one entry per class of pin with the count the lock holds afterwards. dry_run answers with the lock the step would write as content and writes nothing beside the entity; the content cache still fills, because the inputs are resolved exactly as they would be otherwise.

It writes inside the workspace and reaches the hosts the entity’s sources name — a chart repository, a Git host, a URL — so over HTTP it is admitted to a credential carrying the scope that admits pull, and refused to one that can only read. On standard input and output the same capability is also reachable as cli-pin, which runs the command; over HTTP that tool does not exist.

Being told how a long call is going

A call reports its progress when you ask to be told, and asking is one field. Put progressToken in the call’s _meta — a string or a number, yours to choose. It comes back on every report exactly as you spelled it, and it is the only thing in a report that points back at your call: a report answers nothing, so it carries no id. Send no token, or send it as null, and nothing changes — the call is answered the same way it is answered without one. A token of any other shape is refused, before the call does anything, naming the two forms it may take rather than being passed over: a caller that asked to be told and is then met with silence has nothing to act on.

What arrives is notifications/progress, carrying your token and a count that rises with every one. There is no total and no message, and neither is an omission awaiting work: what the work reports is that it has entered another phase, so a total could only be invented and a sentence could only be composed here rather than passed through. Draw an indeterminate indicator off the rising count; there is no fraction to fill a bar with.

Over HTTP the answer becomes an event stream, and only once something has actually reported. It is served as text/event-stream, marked not to be cached, and carrying X-Accel-Buffering: no for an intermediary that would otherwise hold every event until the work was over and turn the stream into a slow single answer. Each report is one event, and the call’s own answer is the last event before the stream closes. While the work is quiet the stream carries a comment line at intervals, which reaches whatever sits in between as bytes on a live connection and reaches your client as nothing at all. A call that asked for progress and reached work that reports none is still answered with one JSON object, because what opens the stream is the first report rather than the token.

On a stream, read the outcome from that last event rather than from the status code. The status and the headers are written when the stream opens, which is before the work is done, so a call that reports and then refuses carries its refusal as the last event under the status already sent. Closing the connection mid-stream ends the work and nothing further is written for it, exactly as How a call ends describes for every other call.

Over standard input and output the reports are lines ahead of the response line, framed the way every other message on that stream is framed — one JSON object per line, in the order they were written — and the response line follows them. Nothing is reported once a call is over, on either transport.

Resolving a Release’s dependencies is what reports here. pull reports each time the resolution enters a phase. build reports only when it is resolving first — because you sent auto_pull, or because the workspace’s own setting asks every build in it to resolve — since the reporting belongs to that step: a build rendering from the pins it already holds reaches nothing and reports nothing, so a token on that call changes nothing about how it is answered. Any call also reports each step its work enters and waits on — reading a registry, fetching an artifact or a documentation bundle, compiling a plugin for the first time — the steps the command line shows a person beside its spinner. A call whose work waits on none of those reports nothing, which is harmless rather than an error: the answer is the one you would have received without it.

Asking which connection is written at a place in a document

connection-at-position answers the question before the connection half of the two tools above, for when you hold a place in a document rather than a node on a graph — a line you are looking at in an Aggregate or a Release. Pass file, the document, relative to the workspace root or absolute and read from disk the way insertion-point reads one; position, a line and a character both counted from zero, measured in the units position_encoding names exactly as insertion-point reads that argument; and the release whose compiled graph records the connections. The Release is required for a place in the Aggregate too: a graph node and a connection exist only on a compiled graph.

The answer is one of two halves. Where the place is on a connection’s entry, it carries graphNode and connection — its socket, its alias and the document the place was read in — which are exactly what attach-candidates takes beside graph_node and release, and what attachment-container takes to name where an attachment on that connection goes; that container sits inside the very entry the place fell in. Otherwise it carries noConnectionReason, from a closed set: no-connection-entry (the place is on no entry an attachment is written in), feature-created-connection (the place is on the Release’s entry for a connection a Feature drew) or unknown-connection (the place is on an entry the Release writes for a connection the compiled graph does not carry). The readable answer states the reason in words.

A place anywhere inside an entry is inside it — on the alias, on its target, inside its features — and the innermost entry wins where entries nest. A place on a socket’s own key, above the aliases under it, is inside none of them. The entries are the ones the compiled graph records: in the Aggregate, every connection a component draws, at its entry under the connection’s alias in the document the component was authored in, which for a component an imported module contributes is that module’s own document; in the Release, every per-edge entry it writes. A connection written as a list of targets, and one a Feature’s own dependency block draws, carry no entry an attachment is written in. Whether a key is a connection is never worked out from what it is called.

It answers and stops. It writes nothing to any file. A document that is not in the workspace, cannot be read, or is not well-formed YAML comes back as a failed result naming what to change, as it does from insertion-point; so do a place missing its line or its character, and a position_encoding outside the three.

Asking which container an attachment belongs in

attachment-container answers the question between a candidacy answer and an insertion point. You have settled what to attach to a node; before you can ask where in a file to write it, you need to know which file and which container inside it. Pass graph_node — a node id on a compiled graph, as the graph keys it — and the release whose graph it is. Both are required: a node id is a key of one Release’s graph and means nothing without it.

Do not assemble that path yourself. A node’s id and the subsystem path enclosing it are both written with dots between their parts, and a dot is a legal character in a name an author types — so from outside the document there is no way to tell a structural dot from one inside a name. A path you composed would read correctly and address a key nobody wrote, and the edit that followed would create that key rather than being refused. Worse, a node id carries no trace of its enclosing subsystem at all: a component authored inside subsystems.billing.subsystems.payments is keyed as ledger, exactly as a top-level component would be. Ask for the container.

The answer carries node, the node it is about; file, the document that node was authored in; and container, the structural path from that document’s root as a list of segments — ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. It is a list rather than a joined string on purpose: a joined path would have to be split again by whoever received it, which is the ambiguity above reintroduced one call later. Pass file and container to insertion-point unchanged.

file is part of the answer rather than something you already know. A node an imported module contributed was authored in that module’s own document under the name the module gave it, so both the file and the last segment of the container differ from anything you sent.

For an attachment on one connection the node draws, add connection with its socket, its alias and its document, which is required here because either document may hold one. With aggregate the answer is the connection’s own entry in the document the node was authored in, its features block last; a connection the Release drew has no entry there and is refused. With release it is the per-edge entry under the Release’s entry for the node — ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"] — reported whether or not the Release writes that per-edge entry yet, so insertion-point names the keys still to write; a Release writing no entry for the node is refused, since where the node is placed is not this tool’s to decide. A connection a Feature drew is refused in either document.

It answers and stops. It creates no attachment, writes nothing to any file and composes no text. It does not rule on what may attach either — that is attach-candidates. A node the graph does not carry, or one it records no document for, comes back as a failed result naming what to change rather than as an answer with an empty field.

Locating where an entry belongs in a document

insertion-point answers the question that follows a candidacy answer. You have settled what to attach or connect; now you need to know where in the file to write it. It hands back a position and the columns to indent at, so you can apply the edit without parsing the document yourself. Because what it reads is a document’s own structure rather than any one kind’s shape, describe-capabilities indexes it under whatever entity kind you narrow to.

Pass file — the document, relative to the workspace root or absolute, and inside the workspace: one reached through a link leading out of it, to the file or to a directory on the way, is not, and is refused on either transport — and container, the structural path from the document root to the container the entry goes inside, each element a mapping key or a sequence position written in decimal.

The container path is yours to supply. The tool reads the document’s structure and never works out where something belongs from what it is called, what type it carries, or what it appears to mean. You say which key; it says where that key’s entries go in this document — which segments of the path the file already carries, the columns its entries sit at, and the last line its innermost block reaches. For a Feature attachment on a node of a compiled graph you do not have to know that key yourself: attachment-container above reports the document and the container, and both go here unchanged.

The answer is a zero-width position, whose line and character both count from zero; entryIndent and indentStep, the columns to write at; and missingContainerKeys, the container keys this document does not carry yet, outermost first, which you write before the entry. entryShape reports whether the container holds a mapping or a sequence, and reports unknown where the container is not there yet or holds nothing, because the document has not said — the shape is then yours to choose. indentStepMeasured says whether the step was measured from this document’s own nesting or is a fallback for a document that exhibits none. Where precededByLineBreak is set, begin your text with a line break: the position sits at the end of the line the entry follows, which is in range whether or not the file ends in a newline and disturbs no byte already written. Read missingContainerKeys even where you expect the container to be there — a position applied without the keys that have to precede it produces a document that no longer parses.

position_encoding names the units the reported character offset is measured in: utf-8, utf-16 or utf-32. It is an argument here because neither revision of this protocol negotiates one, and it defaults to utf-16, which is what an editor session takes when a client negotiates nothing — so a caller that names nothing is answered identically on both surfaces. A value that is none of the three is refused rather than quietly defaulted, because offsets measured one way and applied into a buffer measured another corrupt the document at the first character outside ASCII.

It answers and stops. It writes nothing to any file, composes no entry text and applies no edit; composing the text and deciding whether to apply it are yours. A request that does not address a place an entry can go comes back as a failed result naming what to change — a document that is not in the workspace, cannot be read, or is not well-formed YAML; a container path carrying no segments or an empty one; a path running through a scalar, which nothing can be appended inside; a path reaching a collection written in flow style, where appending would rewrite bytes the author already wrote rather than add a line; or a path addressing a block sequence with something that is not one of its indices. Where you would rather have the edit applied than apply it yourself, Applying one bounded edit to a document is the tool that does it.

Applying one bounded edit to a document

edit-document applies what the two tools above locate. One call adds one entry under one container, or sets one scalar, and it can do nothing else. It writes the document you name, inside the workspace, so over HTTPS it needs aggrega:workspace-write: a caller holding only aggrega:read finds it in the tool list, and a call it makes is refused naming that scope.

Name the edit in edit, and the set is closed. add-component adds a component instance under a components container; attach-feature attaches a Feature to the node you name; wire-edge wires a connection inside one of that node’s sockets; set-value sets one value on that node. A name outside those four is refused rather than interpreted. There is no edit that deletes, replaces a block you already wrote, reorders anything, or writes bytes you supply verbatim — so this is not a file writer and cannot be used as one.

Pass file, the document — relative to the workspace root or absolute, and inside the workspace: one outside it, as written or through a link leading out of it, is refused on either transport with nothing read or written; node, the structural path from the document root as a list of segments; name, the key the entry is written under; and value, what that entry carries. node is a list for the reason attachment-container answers in one: a dot is legal inside a name an author types, so a joined path could address a key nobody wrote and the entry would be created there rather than refused. For add-component the path names the components container itself, because the entry being added is the node; for the other three it names the node the edit is about, and the container follows from the edit. socket is read for wire-edge and ignored otherwise. What value means follows from edit — the entity the entry requests, the node a connection points at, or the scalar a value is set to — and it is a JSON value of its own type, so a number stays a number, a quoted digit stays text, and leaving it out sets nothing at all. A mapping or a sequence is refused, because writing a block is not one of these edits.

Every byte the edit does not touch survives. The document is parsed only to locate the container and the line its block ends at, so comments, blank lines, quoting style, folded and literal scalars and the trailing-newline shape all carry through, and the nesting step is measured from the document’s own indentation rather than imposed. The same request against the same document produces the same bytes.

The result has to be a document you could have typed, and that is what the write is gated on. The composed document is checked against its own kind’s schema and reaches disk only if that passes. A request that would produce something the schema refuses is refused, naming the property the schema would not admit and where, and the file is left byte-for-byte as it was — so a refused edit is indistinguishable from one never attempted, and you can retry a corrected request against the document you started with. An entry that is already there carrying what you asked for is a no-op; an entry of that name carrying something else is refused rather than replaced.

The answer carries container, the structural path the entry landed in; created_containers, the container levels this edit had to bring into being, outermost first and empty in the ordinary case where the whole path was already there; and written, the document that reached disk, empty where nothing did. Read created_containers: an edit that quietly wrote two nested blocks the document did not carry is otherwise indistinguishable from one that added a single entry to a block you wrote yourself.

dry_run does everything except write. The edited document comes back as content, nothing is created and written is empty — for a client that puts the result in front of the author before it is saved. Every other behaviour is the write’s, the schema gate included, so a request the write would refuse is refused under it too. Without it the document is written and content is absent, because the document is then on disk and written names it.

Whether what you wire is semantically admissible — whether a socket is one the producer declares, or whether a Feature’s applicability is satisfied — is not decided here. That is what validate answers.

On standard input and output the same capability is also reachable as cli-edit-document, which runs the command and hands back the text it printed; over HTTP that tool does not exist, and this one is how the capability is reached there.

Turning a foreign description into draft entities

import converts a description another tool produced — a flow exported from an agent builder, say — into draft Aggrega authoring files. It writes those files into the workspace this server serves, so over HTTPS it needs aggrega:workspace-write: a caller holding only aggrega:read finds it in the tool list, and a call it makes is refused naming that scope.

Pass source, the file or the directory to convert. It is absolute or relative to the workspace root, the same contract every other path argument on this surface uses, and on a server reached over HTTPS it resolves inside the workspace that server serves.

A directory is read into exactly the files its importer’s file patterns select. A chart or a project is a directory, and source may name one. The importer is then handed the files of it, at any depth, that one of the file patterns its signatures declare selects, each named by its path inside the directory written with forward slashes, in sorted order, together with the files its plugins.importer attachment names under with.sources, under their base names; a directory file and a with.sources file of one name are refused rather than one hiding the other. An importer that declares no file patterns reads one file and refuses a directory, under the condition An importer that declares no file patterns is handed a directory, and a directory holding no file its patterns select is refused too. The directory is held to itself wherever it lies: a link among the files the import would read, or to a directory, that leads out of it is refused before anything is read, and a link to a directory is never entered — as A directory you import sets out. On a server reached over HTTPS the directory itself resolves inside the workspace, so every file read from it does too.

The importer is one your workspace’s catalog holds, or one of the compiler’s core importers. The translation is the work of the importer plugin that advertises the source’s format: one your workspace’s catalog holds, or one of the compiler’s core importers, which serve their formats in every workspace with no catalog entry. This tool selects it, runs it, and writes what it produced. A plugins.importer attachment whose uri names an importer by its identity and version — importer/<name>:<version>, as aggrega plugin add importer writes it — attaches that importer: where it advertises the source’s format it is the one that runs, at that version, whatever other importer advertises the format too, and it is handed that attachment’s with sources and settings, which no other importer is. Where several importers advertise the format and no single one of them is attached — a core importer and an importer of another name your catalog holds for the same format among them — the call is refused naming them, as Configuration describes. A format you name that no importer advertises is refused naming the capability an importer would have to advertise — import:langflow for a Langflow source — which is what an importer you add to the catalog declares, rather than a generic miss you then have to interpret.

A core importer the server’s machine does not hold is fetched once, by the first import that needs it. The import fetches it from the served workspace’s default registry, holds it to the module the compiler’s release publishes, verifies its signature under that registry’s trust policy and the host functions it uses, as a pull verifies a plugin it fetches, and keeps it in the workspace’s content cache, so every later import reads it from there and reaches no registry. Nothing else is written for it — no lockfile, and no record of trusted plugins. Over HTTPS this is the one registry a call to this tool can make the server contact, under the bound Which credentials a call spends sets for a registry read: the registry is the default registry of the workspace this server serves, so it is one that workspace is configured with; nothing in the call names a registry or carries a credential; and the fetch spends this host’s own login and trust policy. The tool still reaches the workspace and nothing further, so aggrega:workspace-write is all a call needs: what the fetch leaves behind is a module in the workspace’s own content cache. A module that does not verify is refused as it is at a terminal, and nothing is kept. Where the module cannot be fetched — the workspace is offline, its registry cannot be reached, or the registry does not hold it — the call is refused under A plugin’s .wasm is not on this machine, naming the importer, its version and what puts its module on the machine.

Where the workspace names no catalog folder, the import reads the catalog its default registry publishes. A workspace whose workspace.catalog_dirs, AGGREGA_CATALOG_DIRS and root name no catalog folder reads the standard-library catalog as one signed snapshot, at catalog/snapshot on the served workspace’s default registry — the same registry a core importer is fetched from, reached on the same terms, with nothing in the call naming a registry or carrying a credential. A snapshot is fetched once: its signature is verified under that registry’s trust policy, and it is kept in the workspace’s content cache and read there as a catalog folder, held to its digest, with no registry asked for it again. Which snapshot a call reads: with upgrade, the newest; otherwise the one the record in the output directory names, fetched by its digest where the machine does not hold it; otherwise the one the workspace last fetched as the newest; otherwise the newest. The record the import writes names the snapshot it read, by its digest, so a later call drafting into the same directory reads the same catalog. Offline, a call that would have to fetch a snapshot is refused naming what to run, and upgrade is refused whatever the machine holds, since only the registry can say which snapshot is the newest. A registry that publishes no snapshot leaves the import with no catalog, and a warn entry in diagnostics says so. A workspace that names a catalog folder imports against it and fetches no snapshot, and upgrade changes nothing there.

Leave format out and the format is recognised by the signatures the importers declare — your catalog’s and the core importers’ alike. Each importer’s Plugin entity records them: the syntax a source is read in, the file names a signature applies to, and the paths the parsed tree must or must not carry. The source is parsed, through the parser your workspace’s catalog serves for a syntax — or, for a syntax your catalog serves no parser for, the one the compiler itself carries — once for each syntax a signature applying to its name reads it in, and the format of the one importer whose signature matches is the one used. The importer then reads the source through the same parser. The core importers’ signatures read a file as JSON or YAML, and those naming no file read it as JSON — the Dify importer’s as YAML — so recognising a file imported on its own reads it in both and needs no parser in your workspace’s catalog: the compiler carries a JSON and a YAML parser, and one your catalog serves is used in its place. A directory is recognised the same way over its files: each signature is tried against the files of it its patterns select, and a signature declaring no pattern applies to none of them. Recognition reads the file you named — or, of a directory, only the files a signature’s patterns select — and no network. A source no signature matches is refused asking for format and naming the formats the importers advertise — or, for a directory, asking for one of its files sent on its own as source or a format whose importer declares file patterns, naming only those — under the condition No importer recognises the source; a source signatures of more than one format match is refused naming them, under the condition More than one importer recognises the source; neither is handed to a guessed importer. Send format to name the format outright in either case — for a directory, one whose importer declares file patterns, since a directory is read only through those. A blank format is refused rather than read as though you had left it out, because those are different requests.

Send target to draft the Manifest the drafted Release builds against for one provider. target is a provider capability — the word a Recipe’s spec.capability binds to, such as compose or helm — and it is aggrega import’s --target, composed by the same operation, so a call and the command draft the same files from the same source. For each component type and each feature type the drafts need — on the drafted Aggregate’s components, their connections and its subsystems, on the catalog Aggregates it composes, and on the drafted Release’s attachments — in the order the drafts first declare it, the import looks in the workspace’s catalog for the Recipes, or for a feature type the feature recipes, that implement the type and bind to that capability. Where there is exactly one — several versions of one count as one — the Manifest maps the type to it by its capability-qualified name with no version, such as compose/postgres, which the first pull pins in the lockfile at the highest version available. Where there are several of different names, it maps the one named after the type itself, such as helm/postgres for core/datastore/postgres. Where there is none, or several with none so named, the type is left unmapped and a warn entry in diagnostics names it and why — the several each by name — so a build of the drafts stops naming each instance or attachment of it, under No Recipe is mapped for a component or feature instance, until the mapping is added. Where the importer drafts the Manifest itself, to choose the Recipe one instance renders through or a feature recipe among several, each mapping it wrote that the catalog offers for that type and capability is kept, any other is dropped with a warn entry, and the types it leaves are mapped as above. The Manifest is drafted as manifest.yaml beside the drafted Release, named and versioned as the Release is, and the Release’s spec.manifest is set to that name — the comment the importer wrote in its place is replaced, and nothing else in the Release changes. A Release that already names a Manifest is left as it is, and where the import drafts no Release the Manifest is drafted beside the Aggregate, with its name and version, and an info entry says nothing references it. The Manifest and the edited Release are drafts like the others: in written, in the record, and handed back under dry_run. A target no Recipe in the catalog binds to is refused before the importer runs, under An import’s target names a capability no Recipe in the catalog binds to, naming it as you sent it and the capabilities the catalog’s Recipes bind to, and nothing is written. Leave target out and no Manifest is drafted — except under sync, which drafts for the target the earlier import was sent; an empty target is refused rather than read as though you had left it out.

Send output_dir to name the directory the drafts go in. Leave it out and they land beneath the root of the workspace the call resolved — the place aggrega import writes them when you name no destination, wherever you run it, and the place the language server’s aggrega/import writes them when its request names none. The destination is optional on all three, and named the same way as every path you send this server. Over HTTP it is a directory inside the workspace this server serves, written relative to its root: a value climbing out of the root, an absolute location outside it, and a directory leading out of it through a link — a directory not made yet beneath such a link included — are each refused naming output_dir, and nothing is read or written. Over standard input and output it is taken as named, as every path there is: a relative value resolves against the workspace root the call resolved, and an absolute one may name a directory outside the workspace, which is drafted into as aggrega import --output-dir drafts into it. What is written there is held, with its links resolved, to the workspace — or, for a directory you named outside it, to that directory — so a link inside it leading out of it is refused and nothing is written. An empty output_dir is refused rather than read as though you had left it out. On standard input and output cli-import carries the command’s --output-dir as its own output_dir too; a relative value there resolves in the folder the command runs in: the workspace root the call names, else the one the server was started with, else the folder the server runs in.

Every drafted path is checked against the output directory before anything is written. A path reaching outside it is refused naming both the path and the directory, and nothing at all is written — not even the files in the same set whose own paths were fine, because a refused import that left part of itself behind is a result nobody asked for. A drafted path comes from the importer plugin rather than from you, which is why it is checked for the same reason a path you sent is.

Every import that drafts anything also writes .aggrega-import.json beside its drafts: the record of what it wrote — the target it was sent, where it was sent one, the catalog snapshot it read, where it read one, and each drafted file and, in a drafted Aggregate or Release, each key at every depth, with a digest of the text written there; any other drafted file is recorded whole. A key’s text is its line, its value’s lines where its value is not a mapping of keys, and the comment lines written directly above it at its own indentation. written names the record with the drafts, and under dry_run it is among the drafts handed back. The record is JSON, so nothing that reads the workspace’s YAML documents reads it.

A call never writes over an Aggregate already in the output directory. An Aggregate is the document an author goes on editing once it is drafted, so a call one of whose drafts would land on a file that reads as an Aggregate is refused, naming the draft and the directory, and nothing at all is written — under dry_run too, since a dry run refuses what the write refuses. Every other file already at a drafted path is written over, and a file an earlier import drafted that this one does not draft is left where it is.

Send sync to bring what an earlier import drafted up to date with the source instead, changing only what the import wrote. A sync sent no target drafts for the target the record names, so it drafts the Manifest the earlier import drafted; one sent a target drafts for it, and the record then names it. A recorded target no Recipe in the catalog binds to is refused as a sent one is, the refusal saying the target is the recorded one. Each part is judged three ways — what the record says the import last wrote there, what is on disk, and what the source drafts now. A part the source left as the import last wrote it stays exactly as it is on disk, whether or not an author edited it. A part the source changed is written anew, a part it dropped is removed — a drafted file deleted whole — and a part it gained is added beside the parts the draft names around it, each only where what is on disk is what the import last wrote and holds nothing an author added. Everything else stays byte for byte: a key an author added anywhere — a parameter, a Feature, under a drafted Component instance too, another Component, the environment a drafted Release leaves for its author — a comment not written directly above a drafted key, and every file the record does not list. The answer’s drift lists each part brought up to date — or, under dry_run, each part that would be — in the order the draft names them, each as change (added, removed or changed), file, the drafted file it is in, and key, the keys leading to it in a drafted Aggregate or Release as a list, empty where the part is the whole file; the text answer names each on a line of its own in the words aggrega import writes on standard error, <change> <key> in <file> or <change> <file>. An empty drift under dry_run says the drafts are in step with the source. Under dry_run the drafts handed back are the files the sync would write, with the content it would give them. A sync that would change or remove a part an author edited, add a part where an author already wrote one, or remove a part holding something an author added is refused, naming each such part and why, and nothing is written; a comment written directly above a drafted key edits that key. A sync over an Aggregate no record lists is refused saying so, as is one whose record cannot be read, and a sync whose importer could not finish writes nothing. A sync into a directory holding no record and nothing at its drafted paths writes the whole draft. drift is an empty list for a call that is not a sync.

The answer carries source, as you named it; format, how the source was read; workspace_root, the root of the workspace the call resolved; output_dir, the directory the drafted paths are relative to; written, the files that reached disk; drift, what a sync brought up to date; diagnostics, one entry per construct the importer could not translate; decisions, how the importer mapped each source node; and halted. output_dir is the directory you sent, or that root where you sent none, read off what the import actually used, and it is reported under dry_run too, where nothing is written but each drafted path is still relative to it. Over HTTP workspace_root is kept back and marked workspace_root_withheld, because the root is a place on the server’s host, as What an answer says about the server’s filesystem sets out; output_dir is kept back and marked output_dir_withheld where it is that root, and otherwise told by its name relative to the root — the form your own paths take — so where the drafts went is still in the answer. An import the importer could not finish still drafts what it could, and it comes back flagged as a failure carrying that whole answer — halted true, the files that did reach disk named in written, and the diagnostics beside them naming what is missing. That is a partial result you can keep or discard, not a call that did nothing.

decisions says where the import guessed. It carries one entry per source node the importer mapped, in the importer’s order: source_node, the node’s id, type and params_summary; candidates, each catalog Component the importer weighed for it as component, score, tier and signals — what each of its signals contributed, under table, category, domain_labels, shape and name; chosen, the target it chose, the mode it wrote it in — a reference to an existing Component or a draft — and the choice’s tier; rationale, why; and swap_hint, how to choose differently. candidates is absent where the importer weighed none, chosen where it made no choice, and rationale and swap_hint where it wrote none. Every value is the importer’s own — how it scores a candidate and where its tiers fall are its choices — so read an entry as its account of the mapping. decisions is in the answer under dry_run and when the import halted alike, and it is an empty list for an importer that reports none. The text answer names each decision on a line of its own after the diagnostics, in the words aggrega import writes on standard error: mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, the score being the best candidate’s.

dry_run does everything except write. Each drafted file comes back under drafts with its path, relative to output_dir, and its content, and nothing is created — for a client that puts the result in front of you before it is saved. Every other behaviour is the write’s, the same importer over the same source reporting the same diagnostics, so a source the write would refuse is refused under it too. Without it the files are on disk and written names them, and drafts is absent rather than repeating bytes you asked to have written.

The drafts are a starting point you own and go on editing. Whether what they say is admissible — whether a socket is one the producer declares, or whether a Feature’s applicability is satisfied — is not decided here. That is what validate answers.

On standard input and output the same capability is also reachable as cli-import, which runs the command and hands back the text it printed; over HTTP that tool does not exist, and this one is how the capability is reached there.

Publishing, signing and withdrawing

Four tools put something where other people will resolve it. publish-entity bundles a catalog entity and publishes it; publish-artifact publishes a standalone file, such as a documentation bundle, with its bytes opaque and no entity envelope parsed; sign-artifacts signs already-published references and attaches each signature, leaving a reference that already carries one its registry’s trust policy verifies as it is; deprecate-artifact attaches a signed withdrawal marker to one. Read What an assistant can do without asking you first before you allow any of them: these are the tools whose effects leave the machine.

publish-entity takes entity, the document to publish, and a Plugin also needs plugin, the executable published inside its manifest. publish-artifact takes file with the name and tag it is published under. Every path argument here is absolute or relative to the workspace root, the same contract every other tool on this surface uses, and workspace_root names the workspace the call means — on a server reached over standard input and output. A server reached over HTTPS refuses workspace_root and requires each of those paths to resolve inside the workspace it serves, as One process, one workspace sets out. registry is the destination and defaults to the workspace’s configured one; sending neither, with no default configured, is refused naming what to send. sign-artifacts takes references, one or more registry addresses rather than paths, and optionally jobs, how many of them are signed at once: left out, they are signed one after another, and a value below 1 is refused naming what to send. Each is still signed exactly as it would be alone, as aggrega sign describes. deprecate-artifact takes either reference with severity and reason, or from naming a batch file — and refuses content arguments sent alongside a batch file rather than dropping them, because a batch file supplies its own and a silently ignored argument reads as one that was honoured.

The two publishing tools take dry_run, which shows what a publication would send without contacting any registry. It computes the bundle, reports what it would have published, and answers with beyond_this_machine false and the destination it would have addressed in registries; publish-entity also answers with the digest that publication would land, the one aggrega push --dry-run prints. It is the way to show someone a proposed publication before it becomes one. Signing and withdrawing have no such form: both act on something already published, so there is nothing to preview.

publish-entity answers with windows_unusable_entries where the archive it publishes carries entries Windows cannot hold as written — a path with a part named after a device, such as CON, AUX or NUL, in any letter case and whatever extension follows, or a part ending in a full stop or a space — naming each, the entity document’s own file name first, then the files it carries. It is absent where there is none, which includes an entity published as its document alone. aggrega running on Windows refuses to unpack such an entry, so a Windows workspace cannot use the version; these are the entries aggrega push warns about, and the answer’s text names them too. They refuse nothing: the call goes ahead or is refused exactly as it would be without them, dry_run included.

publish-entity takes pin_sources, which runs the entity author’s pin step on the entity before it is bundled, so the entity.lock the step writes beside it is part of what is published. It is the same step the pin tool runs, writing the same bytes, and it runs before any refusal that judges the entity — so a publication refused there, for a missing signature say, still leaves the lock written beside the entity. A refusal about the call itself, such as an offline workspace or no destination, comes first and pins nothing. Leave it out and the workspace’s pin_sources_at_push decides; send it and it decides in either direction. A publication that pins writes inside the workspace as well as to the registry, so over HTTP it needs a credential carrying both scopes, and one carrying only the scope that admits publishing is refused naming the other. The result carries pin, in the shape the pin tool answers with, where the step ran; under dry_run the step reports the lock it would write and writes nothing. Where the step does not run, a Recipe or FeatureRecipe whose entity.lock records no pin for an input it reads is refused — or one the input no longer matches — before anything is bundled, dry_run included, naming aggrega pin, pin_sources, and pin_sources_at_push. It is the refusal pull raises over the same lock, and checking it fetches each remote source the entity writes out in full, as the step would.

Signing is where the credential is spent, and three of the four tools do it — a data-artifact publication signs nothing, and is signed afterwards by reference. identity_token supplies a keyless identity for the call. On a server reached over standard input and output, leaving it out falls through to the identity that server’s own environment carries, and key_path selects an offline held key instead. Over a listener neither of those is reachable: the environment is not read, key_path is refused and withheld from what these three tools advertise, and a key the served workspace’s configuration names is not reached — so only a token sent in the call signs, as Which credentials a call spends sets out. One call signs with one credential. Every reference sign-artifacts is sent, and every entry of a batch file deprecate-artifact reads, is signed with the same held key or the same keyless identity; where the served workspace’s configuration names a key for one reference’s registry and none for another’s, or two different keys, the call signs nothing and is refused naming the registries on each side, before any identity is resolved or any registry is read — send one call per credential, or one key_path for them all on standard input and output. Over a listener no configured key is reached, so there every reference is signed with the identity the call sends and the call is never refused for this. The refusal is described in References signed together need different signing credentials. fulcio_url, rekor_url and timestamp_url override the keyless endpoints the workspace configures, on either transport. When no identity resolves at all the call refuses and names what to send — nothing here opens a browser or waits on a person, because there is nobody watching a protocol stream, and a call that hung would be the silent failure that refusal exists to prevent. On publish-entity, whether a signature is attached at all follows the destination registry’s policy unless sign says otherwise, and a registry that requires signatures refuses an unsigned publication whatever you send: there is no argument that bypasses that refusal. See aggrega sign for the two signing modes and what each contacts.

Each result carries the facts rather than a transcript: where the artifact landed, its tag, the published digest — or, for a catalog entity’s dry run, the digest a publication would land — whether the tag already pointed at byte-identical content, whether a publication was signed, and its reach. A signing batch reports every reference signed with the digest its signature commits to, in the order the references were given, and a batch in which any reference failed comes back as a failure naming each one rather than as a result with a short list — a partial batch reported as a success is how a refusal comes to be read as a pass. A deprecation reports each marker with its own digest, since a marker is attached as an untagged referrer of the artifact it withdraws and nothing else addresses it. Signing or withdrawing a reference nothing published is refused rather than attached to nothing.

The two parts of an answer

Every tool answers with a readable text, and with a structured result beside it wherever the operation has one. The text is written for a person reading the conversation. The structured result carries the same answer as fields a program reads — a verdict, a list of files, a diagnostic — and a refusal carries one too where the operation had findings in hand when it refused, as What a refused build hands back describes for a build.

The structured result also carries the text, as text_answer. Every tool’s structured result has a text_answer field holding the answer’s text exactly as the text carries it: every sentence, in order, unchanged. So a client that hands its model the structured result rather than the text, as Claude Desktop does, still hands it every sentence the text says — the line the argumentless describe-capabilities answer opens with, the configuration in force that config-show reports, the sentence naming the folder an answer used where no workspace was found. text_answer is written first, ahead of the fields the tool answers with, and it is the text the caller receives: over HTTP it names each place on the server’s host as the text does, as What an answer says about the server’s filesystem sets out. The text itself stays the prose it is, for the clients that read it, so the same words travel twice in each answer.

No tool is an exception, lint included. No tool answers with a field of its own named text_answer, so the field never stands in for one. lint’s structured result keeps its summary — the number of entities checked and of findings, in total and by severity, under the names aggrega lint writes with -o json — and carries text_answer beside it. describe-capabilities keeps its own fields too: version_summary, the version line on its own, where it is sent no arguments, and in each entry of its index a summary, that tool’s one-line purpose.

No tool advertises an output schema. A tool’s listing carries a schema for the arguments it takes and none for its result, so text_answer is named here rather than in a schema.

An answer with no structured result is its text alone. A refusal of a call’s arguments, and any other failure for which the operation had nothing structured to report, comes back as its text and nothing else, and the text is then the only part a client has to show its model.

When a call does not succeed

Where the answer arrives depends on one thing: whether the caller can fix it by changing the arguments of a tool that exists.

Everything that can be fixed that way comes back as the tool’s own result, flagged as a failure and carrying the correction as its text — a combination of selectors the tool does not accept, a required argument left out, an argument sent as the wrong JSON type, a path that does not resolve, a diagnostic from the compiler. That is the channel an assistant is shown, so it reads what went wrong and calls again with the argument corrected.

The protocol’s error channel is kept for what has no tool result to live in: a tool name the server does not serve, a request whose parameters it cannot read, a method it does not implement, and a message that is not valid JSON at all. Reading a resource and rendering a prompt answer there too, because neither of those results carries a failure flag of its own.

A tool’s advertised schema also declares most of the rules its arguments must satisfy — which selectors are mutually exclusive, which argument is meaningful only alongside another, and which are required — so a client composing calls against the declared schema rarely has to make the call to learn them. A rule the schema does not state is still refused, with a sentence naming it; pull’s rule that verify is not combined with upgrade_targets or pin_sources is left to the refusal on purpose, for the reason given under Resolving what a Release depends on.

What stops the server

Over standard input and output, closing the connection stops it. The server reads one message per line and exits cleanly when its standard input reaches end of stream, so a client that closes the connection shuts the server down. That is the ordinary case on that transport, because you never launch the command yourself: the client that started it is what ends it, so quitting your editor, or disabling this server for a project, is what stopping it usually looks like.

Asking the process itself to stop reaches the server on either transport. An interrupt from a terminal, or a termination request from a supervisor or a container runtime, shuts it down on the first request, whether or not a client is sending anything: it stops accepting messages, ends the work a call in progress is doing, and exits cleanly. A second request ends the process at once. Over standard input and output a call still running when the process is asked to stop therefore does not finish; a listener instead drains, letting a call already being answered finish within a bounded budget before the process exits.

A client can also stop one call without stopping the server, and how it does so is the transport’s. Calls are answered concurrently, so ending one is acted on while that call is still running rather than waiting behind it. Over standard input and output a client names the call’s id; cancelling a call that has already been answered, or one the server is not working on, does nothing — which is what makes such a message safe to send without first knowing whether the answer is already on its way back. Over HTTP there is no message to send: closing the connection that carried the call ends it. Either way the call is told to stop — its work ends at the next point the operation checks, and an operation that never checks runs to its end — nothing further is sent for that call, every other call in progress carries on, and the server keeps serving.

When to use it

Use aggrega mcp when you want an AI assistant to help author Aggrega entities against the real schemas and reference — so its suggestions are grounded in the exact structure the compiler accepts rather than guessed. It fits the authoring loop directly: the assistant reads a kind’s schema and reference, scaffolds a skeleton, fills the fields your role owns, and validates before handing the draft back. See Authoring Aggrega files for that loop.

Over standard input and output you typically never type aggrega mcp yourself. Instead you name it once in your client’s MCP configuration, and the client starts and stops it for you. A listener is the other case: there you run the process, and it keeps running for callers who did not start it.

Example: client configuration over standard input and output

Point an MCP client at the command with a stdio server entry:

{
"mcpServers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

The only prerequisite is the installed aggrega binary on the client’s PATH. For per-client configuration paths and troubleshooting, see Connect the MCP server. To fetch a schema directly from the command line without a client, see aggrega get-schema.