Use Muxlio from your assistant¶
MCP connects your assistant to Muxlio. You describe the work; the assistant builds a workflow, validates it, starts a run, and helps you inspect the results.
Connect once¶
First follow Start Muxlio. The service starts its MCP listener at http://localhost:7602/mcp by default.
Register your authoring client from the workspace:
muxlio integrations add --client kiro --scope project
muxlio integrations doctor --client kiro --scope project
Choose claude (Claude Code), codex (CLI and IDE), cursor, or kiro.
Registration is noninteractive and uses the installed absolute muxlio-mcp
executable over stdio by default. Use --binary /absolute/path/to/muxlio-mcp
if it is not beside muxlio or on PATH. The bridge reads coordinator credentials
from the protected Muxlio config; tokens are never copied into client settings.
Use --data-dir for a nondefault Muxlio runtime and --server NAME to select a
saved coordinator profile.
Every integrations command requires --scope project or --scope user.
--workspace /absolute/project selects the project (default: current directory).
Only the chosen client and scope are modified:
| Client | Project config | User config |
|---|---|---|
| Claude Code | .mcp.json |
~/.claude.json |
| Codex CLI / IDE | .codex/config.toml |
$CODEX_HOME/config.toml or ~/.codex/config.toml |
| Cursor | .cursor/mcp.json |
~/.cursor/mcp.json |
| Kiro | .kiro/settings/mcp.json |
~/.kiro/settings/mcp.json |
Muxlio merges the named muxlio server, preserving unrelated settings. Repeating
an identical add leaves the file unchanged. A conflicting custom or edited entry
is rejected with instructions; it is never overwritten. Config symlinks are
rejected. JSON and TOML may be reformatted on a change (including TOML comments).
A hash receipt beside the config tracks ownership without storing credentials.
Keep that receipt to allow safe repair and removal.
muxlio integrations list --scope project
muxlio integrations doctor --client kiro --scope project --config-only
muxlio integrations repair --client kiro --scope project --binary /new/path/muxlio-mcp
muxlio integrations remove --client kiro --scope project
repair can recreate a missing registration or update an unchanged managed
entry. Custom or edited entries require manual review first. remove deletes
only an unchanged managed entry. Restart the client after changes.
Doctor starts the actual client's noninteractive CLI and requests server_health
and get_workers, requiring structured successful tool results. It can consume
model quota and requires client login, project trust and MCP approvals. It does
not bypass workspace trust. If the CLI is absent, unsupported by its installed
version, or cannot confirm the calls, doctor fails with recovery instructions;
open the IDE and ask it to invoke both tools. --config-only checks registration
and executable/endpoint validity without claiming a live connection. A user
registration cannot be verified in a workspace with a project muxlio override.
Claude's private local-scope muxlio entry also takes precedence over both scopes;
doctor asks you to review that entry before verifying a different registration.
Client output and configuration contents are withheld from diagnostics.
Remote HTTP¶
Use the service's Streamable HTTP endpoint and an environment variable containing its bearer token. Export the variable securely in the environment that launches the client; Muxlio stores only its name, using each client's interpolation syntax. Kiro IDE may require approval of that environment variable. Remote endpoints require HTTPS; HTTP is accepted only for loopback addresses.
muxlio integrations add --client codex --scope user --transport http \
--url https://muxlio.example.com/mcp --bearer-env MUXLIO_MCP_TOKEN
For saved remote endpoints, add an mcpProfiles entry to your protected Muxlio
config.json, then use --transport http --profile office:
muxlio init --client NAME --scope project combines setup, authoring instructions
and local stdio registration. --agent NAME remains a compatible authoring-client
alias; it does not select an execution adapter. Init defaults to project scope.
Antigravity currently receives instructions only: no installed CLI contract was
available to verify MCP registration, so integrations rejects it explicitly.
Install and invoke the Muxlio skill¶
Run muxlio init --client NAME --scope project --workspace /absolute/project
to install the complete skill bundle in a target project, including a repository
unrelated to Muxlio. Use --scope user for discovery across projects. Skill
locations are separate from MCP configuration:
| Client | Project skill | User skill |
|---|---|---|
| Claude Code | .claude/skills/muxlio/SKILL.md |
~/.claude/skills/muxlio/SKILL.md |
| Codex | .agents/skills/muxlio/SKILL.md |
~/.agents/skills/muxlio/SKILL.md |
| Kiro | .kiro/skills/muxlio/SKILL.md |
~/.kiro/skills/muxlio/SKILL.md |
| Cursor 2.4+ | .cursor/skills/muxlio/SKILL.md |
~/.cursor/skills/muxlio/SKILL.md |
Codex's skill location is independent of CODEX_HOME. Cursor setup checks
cursor --version. Older or unrecognized versions receive a manual project rule
at .cursor/rules/muxlio.mdc, with its bundle under .cursor/muxlio. Global
filesystem rules are unsupported: for user scope, make Cursor 2.4+ available on
PATH or use project scope. An existing project rule keeps its complete activation
frontmatter, including descriptions, globs and alwaysApply, rather than being
converted to a skill with different activation behavior.
Setup archives legacy .skills/muxlio and Codex .codex/skills/muxlio directories
(also $CODEX_HOME/skills/muxlio for user scope) under
.muxlio-skill-backups/legacy-*/muxlio in the selected scope. Relative resources
and user edits remain together, outside discovery. Changed destination files,
including customized Cursor rule bodies, are saved beside the file with a
.muxlio-backup-<content hash> suffix before the canonical content is installed.
Unrelated files are retained. Review and reapply custom guidance as needed.
Init reports these paths in text or JSON skillsPreserved; repeated setup leaves
identical files alone. Write failures and invalid skill metadata fail setup.
Restart the client in the target project. Invoke /muxlio in Claude Code or
Cursor's skill menu, $muxlio in Codex, or explicitly ask Kiro to use the Muxlio
skill (custom Kiro agents must include skill://.kiro/skills/**/SKILL.md in their
resources). For Cursor's manual rule, attach @muxlio.
Ask it to use Muxlio to draft a workflow summarizing supplied documents, without
starting it. Confirm the skill loads and its authoring reference is readable.
Then start a fresh chat and ask a trivial unrelated question, such as "What is
2 + 2?"; it should answer directly without invoking Muxlio. The shared skill
also covers when durable, multi-step, scheduled, independently verifiable, or
multi-executor work benefits from orchestration. Small interactive tasks stay
in the client unless Muxlio is explicitly requested. Every client uses the same
decision guide, preflight, approval, and completion evidence rules; native skill
syntax does not select an execution adapter. Existing custom rule activation
settings remain the user's choice.
The delegation acceptance harness compares the same prompts and workflow semantics across authoring clients, including local-only work, plan approval, preflight blockers, and run evidence.
Skill discovery contracts: Claude Code, Codex, Kiro, Cursor skills, and Cursor rule activation.
Client config contracts: Claude Code, Codex, Cursor, and Kiro.
Ask for a workflow¶
To start from a reusable shape, ask the assistant to call
list_workflow_templates, inspect a template's schemas, and call
instantiate_workflow_template with your chosen executors. The
workflow template catalog provides five
generic shapes and a non-code example. Instantiation returns an ordinary plan
and digest for inspection, validation and submission with separate run inputs.
Describe the inputs, the steps to run, the checks they must pass, and the output you need. For example:
Build a Muxlio workflow for implementing a list of features in this project. For each feature, implement it, review the change, and run this project's build and tests. If checks fail, fix the issue and retry up to a limit. Commit locally only after checks pass. Show me the workflow before starting it.
The assistant can construct Plan IR directly or instantiate a template. For
one-off work, it validates the plan with check_plan, runs preflight_run with
the plan, input, and target workspace, then sends those same values to start_run
after a feasible preflight. Both single-step and multi-step plans use this flow.
Developers can also author workflow source and use build and test for
reviewed, trusted definitions. Source compilation executes arbitrary code with
host filesystem and network access. It requires trustedSource: true on the MCP call.
Prefer check_plan or JSON files for untrusted submissions; see the
compilation security guide.
Follow the work¶
Ask your assistant to check the run, read logs and reports, or explain a failure. You can also use the web UI. Closing the client leaves the run on the coordinator. Your execution machine still needs to stay running.
Use get_run_summary with the saved runId from any MCP client connected to the
same coordinator to retrieve the current outcome and links later. get_run,
get_input_requests, get_attempts, get_logs, and artifact tools provide the
full retained details, subject to the client's normal permissions. Task handles
can also be polled while retained; a live original conversation is unnecessary.
Operators can optionally configure signed run notifications
through POST /v1/subscriptions, using payloadMode: "notification" and event
filters for completion, failure, input required, and reconciliation required.
Receivers get metadata and visible run/status links, with durable event IDs and
bounded retries. No prompt, transcript, answer, or failure text is included in
this mode. The receiver decides how to surface the alert; a client integration
can opt in if its host supports notifications. Muxlio cannot generally resume a
disconnected conversation or reopen a closed chat. Notifications are optional
and do not replace later status retrieval.
For client configuration examples, tool arguments, authentication, and protocol behavior, see the MCP reference.
Start a one-off workflow inline¶
If the run needs an authorized workspace, call list_workspaces with an
administrator credential or a workspaces:read grant. Use the returned canonical
workspaceId in both preflight_run and start_run. When the workspace
has a configured digest, pin it as workspaceDigest in the plan. See the
tool reference.
The following single-step plan echoes the run input. Call check_plan with
the plan field. Pass the complete arguments below to preflight_run, then
to start_run after a feasible result. Add the same workspaceId to both
calls when targeting a specific workspace.
{
"plan": {
"irVersion": "1.0",
"name": "echo",
"root": "root",
"subgraphs": {
"root": {
"nodes": [{"id": "echo", "kind": "project", "inputs": {"value": {"expr": {"op": "input"}}}}],
"output": {"result": {"ref": {"node": "echo", "port": "value"}}}
}
}
},
"input": {"message": "Hello"}
}
The coordinator retains the exact plan used for the run without adding a workflow registry entry. The template walkthrough shows the same inline flow for a multi-step plan.
Save and start a registered workflow¶
Register when the user explicitly asks to save or publish a workflow, or when a concrete use case needs a reusable version or a registered pin for a schedule or trigger. See schedules and triggers. Use the named workflow tools below when publishing under a stable name.
Call register_workflow_version once with {"plan": <compiled Plan IR>}.
The coordinator validates and stores an immutable definition and returns its
digest. Any authenticated client of that coordinator can reuse it:
{
"planDigest": "sha256:<digest returned by registration>",
"workspaceId": "project",
"input": {"request": "Generate the weekly report"},
"idempotencyKey": "weekly-report-2026-11-13"
}
Pass these arguments to start_run. Supply exactly one of plan or
planDigest. Inputs must match the registered plan's inputSchema.
The coordinator loads the definition, validates input, authorizes the target
workspace, and pins the registered bytes and digest
without rewriting them. Workspace aliases resolve to a canonical run workspace,
stored separately from the definition. A workspace fixed in the plan cannot be
overridden with a different workspace.
Reuse the same idempotency key on retries. The same authenticated caller,
definition, exact input bytes, and canonical workspace return the original run;
changed inputs or a changed definition require a new key. Omit workspaceId
to use the plan's workspace or the coordinator's configured default.
The HTTP equivalent is POST /v1/runs with the same body fields except that
idempotencyKey is sent as the Idempotency-Key header. Register through
POST /v1/workflow-versions with the Plan IR itself as the body.
list_workflow_versions lists registered digests and their retirement state.
Unknown digests return 404. Operators can retire a definition with authenticated
DELETE /v1/workflow-versions/<digest>; future reference submissions return 410
(MUXLIO_WORKFLOW_VERSION_RETIRED). Retirement persists across restart and
does not change existing runs. Uploading identical content does not reactivate a
retired version. Change the definition and register its new digest.
Publish a named workflow¶
Use the coordinator's operator credential to create, inspect, and update named
workflows. Supply a stable workflowId to create_workflow along with the
compiled plan. The plan's name is display text and can change across versions.
| MCP tool | HTTP endpoint | Arguments |
|---|---|---|
create_workflow |
POST /v1/workflows |
workflowId, plan |
get_workflow |
GET /v1/workflows/{workflowId} |
workflowId in the HTTP path |
update_workflow |
POST /v1/workflows/{workflowId} |
workflowId in the HTTP path, expectedCurrentRevision, and either plan or planDigest |
Each response includes currentRevision, currentDigest, and the history
with each version's digest, display name, and publication time. The current
version appears first, followed by the other versions in reverse publication
order. To publish a new version, pass a compiled plan and the
currentRevision you observed as expectedCurrentRevision. Concurrent
changes return HTTP 409 for a competing update. Repeating a publication keeps
the original history entry and timestamp. To switch back, pass the prior
version's planDigest with the same revision guard.
Pass currentDigest or any eligible history digest as planDigest to
start_run. Workspace selection and authorization still apply when submitting
the run. Every run keeps its exact plan bytes, and schedules and triggers
continue to use their configured digest. Choose a new digest explicitly when
configuring automation. A digest can be retired once no named workflow uses it
as current. Retired versions remain visible in history and are ineligible for
selection.