Connect
Enable public MCP in the active server config. It uses the HTTP port already serving the API and console. This is a configuration change for the next planned server start; it starts no second MCP process.
[mcp]
enabled = true
allowed_origins = []A programmatic MCP client can connect without an Origin header. Browser callers must match an explicitly allowed origin. An empty list refuses browser origins.
{"mcpServers":{"aion":{"type":"http","url":"http://127.0.0.1:8080/mcp"}}}The client configuration spelling depends on the host. The endpoint and HTTP transport above are the Aion contract. Authenticated calls use the same bearer validation as the HTTP API.
Read before acting
Describe a run first and carry its returned handles unchanged. A transcript handle includes the run, activity and attempt. History and transcript cursors are different sequences.
Namespace is an authorization scope. Public run tools require it, except connected-worker listing can omit it only with authority over all namespaces. Authoring tools operate in the server’s configured workspace and require deploy authority.
Reading tools
describe_run
The first call to make about any run. One read answers: what the run is, what status history projects it to, which step it is on right now, which of its dispatched activities nothing can currently serve, and the exact handles for reading each step's agent transcript. Every handle it returns is complete and usable as-is — pass them back verbatim to read_transcript or read_history rather than assembling your own.
namespaceworkflow_id run_id?
Public /mcp catalogue. Read-only.
read_transcript
A page of what the agent running one activity attempt actually said and did. Returns immediately with whatever exists now — it never waits for more. To follow a live step, call again with from_seq = the next_from_seq you were given. run_id is REQUIRED and is not decoration: the run is an axis of the durable stream key, and a handle naming a run that never dispatched this activity/attempt is refused rather than served empty.
namespaceworkflow_idrun_idactivity_idattempt from_seq?limit?
Public /mcp catalogue. Read-only.
read_history
A page of the workflow's authoritative event history — the record everything else is projected from. Large payloads are elided to a size marker rather than truncated silently. Returns immediately; page with next_from_seq.
namespaceworkflow_id from_seq?limit?payload_limit_bytes?
Public /mcp catalogue. Read-only.
list_connected_workers
Lists workers connected to the live dispatch registry, independent of whether the server supervises their processes. Supply namespace, task_queue, and activity_type together to distinguish no workers from workers all excluded by liveness.
namespace?task_queue?activity_type?
Public /mcp catalogue. Read-only.
list_runs
Find runs in a namespace by type, status, or start window, newest start first, one page at a time. Use this to locate a workflow_id you do not already hold — never invent one. `count` is the total matching the filter; pass `next_cursor` back as `cursor` with the SAME filter for the following page.
namespacelimit workflow_type?status?started_after?started_before?cursor?
Public /mcp catalogue. Read-only.
query
Ask a running workflow one of the queries its own code registered. Records nothing and changes nothing: a query runs against replayed state. An unknown query name is answered as a failure, never as an empty result.
namespaceworkflow_idquery_name run_id?arguments?
Public /mcp catalogue. Read-only.
list_documents
Every AWL document in the server's authoring workspace, sorted by path. Use this to see what exists before reading, saving, or deploying — document paths come from here or from a previous save, never from a guess. An empty list means the workspace holds no documents yet, which is a normal starting state.
Public /mcp catalogue. Read-only.
read_document
The saved source of one workspace document, with the content_hash of exactly those bytes. The hash is the revision identity deploy_document verifies: if you deploy the document as-is, pass this hash; if you edit first, save_document gives you the new one.
path
Public /mcp catalogue. Read-only.
check_document
Run the AWL checker over source you are drafting, WITHOUT saving anything. Returns whether the document parses (`ok`), whether it would be accepted by deploy (`deploys_green`), the step count, and every diagnostic with its line, column, and full extent (`range`, zero-based UTF-16 positions). Pass `path` — the workspace path the document lives at or will be saved at — so schema imports resolve against the workspace; omit it only for a document with no imports. Check after every structural edit and treat each diagnostic as a source defect: a document that is not green will be refused by deploy_document.
source path?
Public /mcp catalogue. Read-only.
assistant_context
Read what the operator has on screen in the Aion console right now: the page they are on, the concepts that page explains, and the document their editor is showing with any selection inside it and where their caret is. Call this BEFORE asking the operator where anything is — the document's path comes back with it, so you never need to ask which directory a repository is in or which file is open. It answers for THIS conversation only and takes no arguments: there is no session to name, because the credential you called with already names one.
Assistant conversation only. Not in the public /mcp catalogue. Read-only.
assistant_document_check
Run the AWL checker over the document the operator is editing, as it now stands — your own edits included. This is the SAME check the operator's editor runs, with the same workspace — verdicts differ only when the operator's own typing has diverged their buffer from the shared document, and their bytes win. It takes no arguments: the document is the one your credential's conversation shares. Check after every edit and fix what it reports with `assistant_document_edit` BEFORE telling the operator what you changed — an edit you have not checked is work you have not finished.
Assistant conversation only. Not in the public /mcp catalogue. Read-only.
Writing tools
save_document
Write the full source of one document into the authoring workspace, creating or replacing it, and get back the content_hash of what was saved. Every save also stores a revision keyed by that hash, so no previously saved state is lost. The returned content_hash is what deploy_document requires — deploy immediately after saving, with the hash you were just handed. Requires the deploy grant.
pathsource
Public /mcp catalogue. Changes state; read the target before calling.
deploy_document
Compile the SAVED document at `path` and load it into the engine, making its workflow type startable with start_run. `content_hash` must be the hash of the currently saved document — take it from the save_document (or read_document) result and pass it unchanged. A hash that does not match what is saved is refused rather than deployed: the document changed since you last held it, so re-read or re-save and deploy the returned hash. There is deliberately no way to deploy unsaved source. Requires the deploy grant.
pathcontent_hash
Public /mcp catalogue. Changes state; read the target before calling.
start_run
Start a workflow of a deployed type and get its handles back immediately. Set await_completion to have the server hand you a task instead: the call returns a taskId at once, the run proceeds, and tasks/get carries the outcome when it lands. await_completion requires the tasks extension — without it the call is refused rather than silently turned into a plain start. That task never expires and survives a server restart, because it is the run itself read through the task model. Cancelling the task does nothing to the run; use the cancel tool to stop the run. A start REFUSED before it began — an undeployed type, an input the deployed contract does not accept, a workflow id already live — comes back as an error whose detail carries class `refused_before_start` with the engine's own reason: nothing was recorded for it, so there is no run to look up and nothing to cancel.
namespaceworkflow_type input?task_queue?routing_key?display_name?await_completion?
Public /mcp catalogue. Changes state; read the target before calling.
signal
Deliver a named signal to a running workflow. The signal is recorded durably in the run's history, so delivering the same signal twice records it twice and the workflow sees both.
namespaceworkflow_idsignal_name run_id?payload?
Public /mcp catalogue. Changes state; read the target before calling.
cancel
Cancel the selected workflow run, stop its in-flight activities and recursively cancel Running or Paused descendants. An omitted run_id selects the latest run. The reason is recorded in history.
namespaceworkflow_id run_id?reason?
Public /mcp catalogue. Changes state; read the target before calling.
assistant_document_edit
Edit the document the operator is editing, in place. Submit one or more edits, each quoting the EXACT bytes to replace (`old_string`, which must occur exactly once in the document as it now stands) and what replaces them (`new_string`). The batch is atomic: if any edit does not apply, none of it does, and the failure says which edit and why. Applied edits appear in the operator's editor immediately — they watch each change land and choose to keep or revert it, so make SMALL, named changes one concept at a time rather than rewriting the whole document. Read the document with `assistant_context` first and quote from what it returned; after editing, run `assistant_document_check` and fix what it reports before telling the operator what you changed. This edits the operator's BUFFER — never read or write files to reach this document, and never save it: saving stays the operator's act. Edit only when the operator asked for a change: a question gets an answer in a sentence or two and no edit. When you have changed something, say what in a sentence or two — never paste the document back into your reply; the operator is looking at it.
edits
Assistant conversation only. Not in the public /mcp catalogue. Changes state; read the target before calling.
The cards marked assistant conversation only are absent from public tools/list. Their bearer identifies the conversation; no argument lets a caller select another person’s buffer.
Complete schemas
Public read schemas
Run reads, worker listing and authoring checks.
Public write schemas
Start, signal, cancel, save and deploy.
Conversation schemas
Read context, edit the shared buffer and check it.
Awaited starts
Start can request a task that settles when the run ends. That requires the tasks extension. The task reads durable run state and survives restart. Use the run cancel tool to end the workflow run, stop its in-flight activities and recursively cancel Running or Paused descendants. Task cancellation ends the MCP task.
Starts and signals are not idempotent. Two accepted calls can create two runs or record two signal deliveries. Repeated deployment also appends a deployment record, even for identical source.