Output schemas

An MCP tool may declare an output schema: the JSON Schema of the structuredContent it returns, so a client knows the shape of a result before calling. arcane-mcp can declare one for each action, derived from Arcane’s OpenAPI document. It is experimental and off by default: turn it on with ARCANE_MCP_OUTPUT_SCHEMAS=on (see Configuration).

Where they are declared

• Only on the individual tool surface, one schema per tool. A meta or dynamic tool runs many actions, so its schema would be the union of all of theirs, which tells a client nothing it could rely on.
• Only for actions that the generic executor runs from an OpenAPI operation with a JSON response: 420 of the 461 actions. Actions with a hand-written handler build their own value; downloads and streams have no JSON schema.
• In safe mode, a mutating action answers with a preview instead of its result, so it declares none.

What a schema describes

The schema describes structuredContent, which is not Arcane’s response body: the server takes the payload out of Arcane’s {success, data, pagination} envelope (see Output format). An object’s fields come to the top, a list goes under items, a single value under value, and pagination and the envelope’s other members (such as failedEnvironments) sit beside them.

Relaxed on purpose

Arcane does not always send what its document declares, and a client may refuse a result that does not match a declared output schema, which would turn a successful call into an error. So each schema is relaxed: it states the type of each field Arcane declares and nothing a harmless divergence could break.

• Every field also admits null, and no field is required.
• Objects accept fields the document does not list.
• Value constraints are dropped: enum, format, pattern, bounds and lengths. oneOf reads as anyOf.
• The root is always an object, as MCP requires.

Where Arcane is known to send another type, the schema widens that field. Arcane (v2.16.1 to v2.17.2, whose compose-go library is unchanged on this point) sends compose byte sizes (mem_limit, mem_reservation, mem_swappiness, memswap_limit, shm_size, a build’s shm_size, deploy resources’ memory, a tmpfs size) as strings such as "0", while its document says integer, so those fields accept an integer or a string.

When a result still does not fit

The server checks every result against the declared schema before sending it. If some part still does not fit, the call stays successful:

• structuredContent carries null in that part, so it matches the schema;
• the text gains a short Output schema note with the JSON Pointer of each adjusted part and Arcane’s original value there, so nothing Arcane returned is lost (up to 20 parts, the JSON cut at 4000 bytes);
• the server logs a warning naming the action and the adjusted pointers.

How the schemas were validated

The live end-to-end suite has a validator mode (E2E_VALIDATE_OUTPUT=1) that checks the structuredContent of every successful call against the action’s schema and writes what does not fit to a report. On Arcane v2.16.1, 2714 results checked across the three surfaces showed one divergence, the compose byte sizes above, in four actions (project.compose, project.runtime, project.update, project.updates); the widened fields cover it. On Arcane v2.17.0, 2843 results of 414 actions checked across the three surfaces, with those fields widened, showed none. On Arcane v2.17.1, 2892 results checked across the three surfaces showed none either, the compose fields it adds (umask, use_service_name_alias) included. On Arcane v2.17.2, 2908 results of 455 actions showed none.

What they cost

The schemas carry descriptions and the referenced component schemas, so they are large: the individual surface’s tools/list result grows from 988 KB to 1.85 MB. Clients use them to check and type results; they are not normally passed to the model.