mixos-mcp

mixos-mcp is an MCP stdio server for agents. Install the binary at /opt/mixos/bin/mixos-mcp and register the MCP server as mixos. It ships in the server prefix archive. Its package, binary and component are the single naming exception.

Connection

The server starts without a Bus connection. The first Bus tool connects using libs/bus. MIXOS_NODED_URL overrides the node configuration URL; otherwise the native client's node config discovery applies, including MIXOS_NODE_CONFIG, MIXOS_ETC and the user/system defaults.

Set MIXOS_BROKER_ACCOUNT to the broker's operating-system account and MIXOS_BUS_SOCKET to the session's Unix socket. With either set, verified Unix ingress is required and connection failures never fall back to TCP. Without an explicit socket, the node config or MixOS runtime directory provides the endpoint. Without either variable, the native WebSocket client uses the discovered URL. Calls are never replayed after reconnecting.

{
  "mcpServers": {
    "mixos": {
      "command": "/opt/mixos/bin/mixos-mcp",
      "env": {
        "MIXOS_NODED_URL": "ws://192.0.2.10:4200/ws",
        "MIXOS_BROKER_ACCOUNT": "user",
        "MIXOS_BUS_SOCKET": "/run/mixos/session/4/noded/bus.sock"
      }
    }
  }
}

Tools

Each name below is exposed as mcp__mixos__<name> in Claude Code.

  • bus_call, bus_list_services, bus_node_info, bus_list_peers, noded_ping
  • term_list, term_snapshot, term_type, term_tab, term_pane
  • log_tail, log_search
  • app_describe, app_commands, app_execute
  • desktop_windows, desktop_window_wait
  • context_search, index_workspace, knowledge_digest, knowledge_brief
  • skills_retrieve, skills_store, skills_refine, skills_graduate, skills_list, skills_delete
  • docs_feedback, journal_feedback, memory_feedback, journal_supersede
  • mix_execute, mcp_status

Application commands

app_describe {service} calls app.describe on that Bus service. app_commands {service} calls <service>.commands. Its result contains the application's command rows unchanged: id, label, menu, shortcut, more (when present), enabled and checked, plus any further metadata.

app_execute {service, id, params?} calls <service>.execute once with {id} or {id, params}. service is a Bus service name such as "busviewer", id is a dotted command id such as "file.refresh", and params is an optional JSON object. Parameters are forwarded unchanged as a sibling of id; the application owns validation and may refuse unsupported parameters. Successful calls return {service, command, result}; application error messages from the Bus client pass through unchanged as tool errors. The same error-text pass-through and prefix removal apply to app_describe, desktop_windows and desktop_window_wait through their shared native helper.

Retired tools: app_actions_list, app_action_invoke, app_controls_list, app_control_get, app_control_set and app_control_wait have been removed without aliases. Use app_commands and app_execute for registry commands, and app_describe to discover an application's state verbs. These retired tool names must not be reused.

Knowledge tools

Knowledge tools retain their ranking, indexing, feedback and skill-learning behaviour. By default they send indexd.<action> requests to indexd on the selected Bus. An absent backend returns an explicit tool error. Skill refinement also needs a configured LLM backend. Settings are MixOS strict-data files: knowledge.conf.mix, domains.conf.mix, skills.conf.mix and llm.conf.mix. LLM Bus providers use the same broker. api_key_cmd is Mix source, executed by /opt/mixos/bin/mix -c.

Host indexd from a desk

When a desk cannot reach the host's Bus, select SSH in $MIXOS_ETC/knowledge.conf.mix (normally ~/.config/mixos/knowledge.conf.mix):

indexd: {
    transport: "ssh",
    target: "indexd",
    ssh_host: "user@host.example",
    ssh_command: ["/opt/mixos/bin/indexd", "bridge"],
    call_timeout_secs: 120
}

Install indexd on the host and configure key-based SSH access for the desk's user. The client runs ssh -T -o BatchMode=yes -o ServerAliveInterval=30 with the configured host and command. The host command runs in the remote login shell; use trusted command arguments. indexd bridge uses the host's local Bus; target selects the address only in Bus mode.

One bridge is shared by knowledge tools for the MCP server's lifetime, with one request in flight at a time. Each call has a deadline, including queueing and retries. A broken pipe, exited child or bridge transport failure gets one restart and retry; an application error is returned immediately. A timeout discards the child and returns an error without replaying the call. A retried mutation may already have executed, so retry is not an exactly-once guarantee. Normal MCP shutdown closes stdin and reaps the bridge. Restart the MCP server after changing transport settings.

Missing settings default to transport: "bus", target: "indexd", the command above, an empty ssh_host and a 120-second call deadline. SSH mode requires ssh_host. When a Bus route is available, select transport: "bus", target: "indexd.host.example.bus" instead. Presence is checked with indexd.stats at the configured target, including routed targets.

The default client domain map expands the user's home for ~/Projects/mixos (mixos), ~/.mix (mix), ~/.ns (ns) and ~/.mc (mc). Custom domains.conf.mix maps override these defaults. index_workspace expands only a leading ~ or ~/, resolves the workspace to an absolute path, and sends absolute file paths and content to indexd.

Terminal tools preserve explicit pane selection and instance checks. Native application tools require an exact service and semantic target. Read-only tools do not invoke mutations; arbitrary bus_call and mix_execute can. Mix execution runs in an isolated worker with bounded output.

Logging and tests

Stdout is reserved for MCP. Logs go to stderr, journald and ~/.local/log/mixos/mixos-mcp.log. Arguments and results are redacted by default; RUST_LOG=mixos_mcp=trace explicitly enables full arguments. --version --json reports build provenance without starting MCP or the Bus.

Package tests cover parameter translation, target guards, output schemas, redaction and provider decoding. The stdio integration test uses the real fixture broker, including verified Unix ingress and lazy reconnection. An in-process fake application checks command listing, execute request bodies with and without parameters, and unchanged application error messages. It also checks configured knowledge targets, paginated re-indexing and absolute file metadata. SSH client tests use a local Mix fake bridge through a test-only command hook; no SSH connection or indexd process is required.

This page as Markdown · This page describes the current main branch of MixOS.