@brutalsystems/muster 0.4.0 → 0.6.0

package/README.md

@@ -76,24 +76,36 @@ Add `--open` to display the launched session in a new Terminal.app window on mac
 
 ```sh
 muster run codex --open --prompt "Review this project" --format human
-muster run claude --open --prompt "Review this project" --format human
+muster run claude --open --terminal ghostty --prompt "Review this project" --format human
+muster run codex --open --terminal iterm2 --prompt "Review this project" --format human
 ```
 
 MCP `run` accepts `open: true`. This requires tmux and selects it when the host
 is auto; explicit pty hosts and tasks are rejected. Detached launch remains the
-default. Terminal.app is currently the only supported viewer; there is no
-`--terminal` selection yet. The host remains tmux, and successful results include
-`terminal_opened: true` (a launch event, not a live window-status check).
+default. `--terminal auto|terminal|iterm2|ghostty` requires `--open`; omitted or
+`auto` uses Terminal.app. MCP accepts the same `terminal` values. Explicit
+choices never silently fall back. iTerm2 and Ghostty must be installed as
+`iTerm.app` or `Ghostty.app` in `/Applications` or `~/Applications`.
+The host remains tmux. Successful results include `terminal_opened: true` and
+the resolved `terminal` (a launch event, not a live window-status check).
 Closing the Terminal window leaves the session running; use `muster stop <id>`
-to stop it. macOS may require Terminal automation permission. If opening fails,
+to stop it. Terminal.app and iTerm2 may require macOS Automation permission.
+Ghostty opens a separate app instance that exits when its last window closes;
+that instance disables saved-window restoration so previous tabs and windows
+are not duplicated. It uses the [Ghostty macOS launch interface](https://github.com/ghostty-org/ghostty/discussions/9221).
+Terminal.app creates the requested window before activation
+to avoid also opening a default shell window on startup.
+iTerm2 uses its [documented scripting interface](https://iterm2.com/documentation-scripting.html).
+If the launch request to the viewer fails,
 Muster stops the launched session and returns an error.
 
 Auto-selection tries tmux, then pty. Every peer includes `host`, `capabilities`
 and `attach_hint`. Watchability is separate from the runtime's idle/busy state.
 
-- **tmux:** a window in the dedicated `muster` session on the `muster` tmux
-  server. Watchable and attachable; survives the CLI or MCP server exiting.
-  Use the returned attach hint, or `tmux -L muster attach -t muster`.
+- **tmux:** each agent has its own session on the dedicated `muster` tmux
+  server. Opening or exiting one agent does not switch another agent's viewer.
+  Watchable and attachable; survives the CLI or MCP server exiting.
+  Use the returned attach hint to reconnect to that agent.
 - **pty:** not watchable or attachable. The CLI prints the peer record and stays
   running to own the terminal. Ctrl-C stops it. MCP-owned pty sessions stop when
   the MCP server disconnects. There is no persistent pty daemon.
@@ -116,6 +128,7 @@ max_concurrent = 4
 permissions = "deny"
 sandbox = "read-only"
 allow_dangerous_flags = false
+default_mcp = []
 ```
 
 Choose `sandbox = "workspace-write"` yourself when agents should edit files.
@@ -166,8 +179,8 @@ The concurrency cap is shared by separate CLI/MCP processes, including pending
 launches. Settings apply to both kinds; tasks are read-only by default.
 
 Codex defaults to an explicit sandbox and never-ask approval policy. Muster enumerates
-and explicitly disables inherited MCP servers, then verifies the effective
-configuration. Hooks, plugins, app connectors, automatic skill-MCP installation
+and explicitly disables inherited MCP servers, enables only the selected
+operator definitions, then verifies the effective server selection. Hooks, plugins, app connectors, automatic skill-MCP installation
 and external notifications are disabled for the child. Unknown MCP names that
 cannot be addressed safely are refused.
 
@@ -181,9 +194,10 @@ arrive after startup; this v1 is not an enterprise policy-enforcement layer.
 Claude permissions and its command sandbox are different mechanisms; neither
 claim implies that every external tool is OS-sandboxed.
 
-These child restrictions deliberately prevent propagating spawn authority.
-Custom MCP tools—including Tin Can—are not automatically injected into the
-child. The child's runtime inbox remains reachable from an external Tin Can.
+These child restrictions prevent automatically propagating spawn authority.
+External tools are enabled only through the operator configuration and launch
+selection described below. The child's runtime inbox remains reachable from an
+external Tin Can even when it has no MCP tools of its own.
 No user-level runtime configuration is rewritten, and workspace-trust dialogs
 are never accepted automatically.
 
@@ -194,6 +208,64 @@ requester, runtime, kind and host. Registry and task outputs also live under
 closed: verify no Muster operation is running before removing that directory.
 There is no automatic time-based lock theft.
 
+## Optional tools for launched agents
+
+MCP servers are optional. Muster does not require or install Tin Can (or any
+other MCP server). Register only servers you want launched agents to use in
+`~/.muster/config.toml`. For example, to use an already-installed Tin Can:
+
+```toml
+# Optional personal defaults for sessions. Omit to keep launches MCP-free.
+default_mcp = ["tincan"]
+
+[mcp_servers.tincan]
+command = "tincan"
+tools = ["peers", "send_peer", "message_log"]
+required = false
+```
+
+Then either runtime can use it:
+
+```sh
+muster run codex --mcp tincan --prompt 'Coordinate with the other agent'
+muster run claude --mcp tincan --prompt 'Coordinate with the other agent'
+muster run codex --no-mcp --prompt 'Work without external tools'
+```
+
+`--mcp NAME` is repeatable and **replaces** personal defaults. `--no-mcp` clears
+them and cannot be combined with `--mcp`. MCP `run` takes `mcp: ["tincan"]`;
+`mcp: []` disables all servers. Omitted selection uses `default_mcp` for sessions.
+Tasks have no defaults, but accept an explicit selection.
+
+Definitions support either `command` plus optional `args`, `env`, and `env_vars`
+for stdio, or `url` plus optional `bearer_token_env_var` for Streamable HTTP.
+`tools` is a required nonempty list of exact tool names. Use `env_vars` and
+`bearer_token_env_var` to reference credentials in the launch environment;
+credentials are not written to launch logs. HTTP OAuth setup shared across
+runtimes, plugin/app tools, MCP resources and prompts are outside this interface.
+Server and tool names must contain only letters, digits, underscores or hyphens.
+Relative stdio commands run from the requested working directory; prefer an
+absolute executable path or a command on PATH.
+
+Before agent launch, Muster initializes each selected server and checks its tool
+catalog. No tool is called during preflight. An explicit `--mcp` selection is
+required: a missing server, missing credential, or missing configured tool fails
+that launch. Defaults are optional unless their definition sets `required = true`;
+an unavailable optional default is skipped with `mcp_warnings`. Each preflight is
+bounded by `startup_timeout_sec` (default 10, maximum 60) and the launch deadline.
+JSON results and `list` report selected logical names in `mcp`; human output shows
+`MCP:` and any warnings. These describe launch configuration, not continuous
+server health.
+
+Codex receives isolated definitions, using a fresh runtime name when an inherited
+server has the same name, and its native tool allowlist. Claude receives a private
+Muster stdio connection that filters both tool discovery and calls; newly added
+upstream tools cannot bypass the selection. Only selected tools are preapproved.
+Claude connection specifications are stored with owner-only permissions under
+`~/.muster/mcp`, removed on stop, task completion, or when `list` observes an ended
+session. MCP server access is separate from filesystem sandbox permissions: a
+selected external tool may have its own write or network capabilities.
+
 ## MCP installation
 
 Installed deliberately, in the one session that should hold spawn authority —

package/dist/codex-policy.js

@@ -1,7 +1,9 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import TOML from "@iarna/toml";
+import { codexMcpConfig } from "./mcp.js";
 const exec = promisify(execFile);
-export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000) {
+export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000, selected = []) {
     const args = [
         "--disable",
         "hooks",
@@ -17,24 +19,48 @@ export async function codexPolicyArgs(env, cwd, deadline = Date.now() + 8000) {
         "notify=[]",
     ];
     async function list(extra) {
-        const { stdout } = await exec("codex", [...extra, "mcp", "list", "--json"], {
-            env,
-            cwd,
-            timeout: Math.max(1, Math.min(4000, deadline - Date.now())),
-            maxBuffer: 1024 * 1024,
-        });
-        const value = JSON.parse(stdout);
-        if (!Array.isArray(value))
+        try {
+            const { stdout } = await exec("codex", [...extra, "mcp", "list", "--json"], {
+                env,
+                cwd,
+                timeout: Math.max(1, Math.min(4000, deadline - Date.now())),
+                maxBuffer: 1024 * 1024,
+            });
+            const value = JSON.parse(stdout);
+            if (!Array.isArray(value))
+                throw new Error("Cannot verify effective Codex MCP configuration");
+            return value;
+        }
+        catch {
             throw new Error("Cannot verify effective Codex MCP configuration");
-        return value;
+        }
     }
-    for (const server of await list(args)) {
+    const inherited = await list(args);
+    const usedNames = new Set(inherited.map((s) => s.name));
+    for (const server of inherited) {
         if (typeof server.name !== "string" ||
             !/^[a-zA-Z0-9_-]+$/.test(server.name))
             throw new Error("Cannot safely disable an inherited MCP server with a non-simple name");
         args.push("-c", `mcp_servers.${server.name}.enabled=false`);
     }
-    if ((await list(args)).some((s) => s.enabled !== false))
-        throw new Error("Inherited Codex MCP servers remain enabled; refusing launch");
+    const expected = [];
+    for (const server of selected) {
+        let name = server.name;
+        let suffix = 0;
+        // Config layers merge nested maps. A fresh key prevents inherited env,
+        // credentials or per-tool policy from surviving the requested definition.
+        while (usedNames.has(name))
+            name = `muster_${server.name}_${++suffix}`;
+        usedNames.add(name);
+        expected.push(name);
+        args.push("-c", `mcp_servers.${name}=${TOML.stringify.value(codexMcpConfig(server))}`);
+    }
+    const enabled = (await list(args))
+        .filter((s) => s.enabled !== false)
+        .map((s) => s.name)
+        .sort();
+    expected.sort();
+    if (JSON.stringify(enabled) !== JSON.stringify(expected))
+        throw new Error("Inherited Codex MCP servers remain enabled or requested servers are missing; refusing launch");
     return args;
 }

package/dist/config.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import TOML from "@iarna/toml";
 import { z } from "zod";
+import { mcpName, mcpServerSchema } from "./mcp.js";
 export const configSchema = z
     .object({
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).default("auto"),
@@ -17,6 +18,8 @@ export const configSchema = z
         "danger-full-access",
     ])
         .default("read-only"),
+    default_mcp: z.array(mcpName).default([]),
+    mcp_servers: z.record(mcpName, mcpServerSchema).default({}),
     allow_dangerous_flags: z.boolean().default(false),
 })
     .strict();

package/dist/format.js

@@ -40,10 +40,14 @@ function recordHuman(record, color) {
         lines.push(field("Permissions", clean(record.permissions)));
     if (record.sandbox)
         lines.push(field("Sandbox", clean(record.sandbox)));
+    if (record.mcp)
+        lines.push(field("MCP", record.mcp.length ? record.mcp.map(clean).join(", ") : "none"));
+    for (const warning of record.mcp_warnings ?? [])
+        lines.push(field("MCP warning", clean(warning)));
     if (record.host)
         lines.push(field("Host", `${clean(record.host)}${record.host === "pty" ? " (not watchable or attachable)" : ""}`));
     if (record.terminal_opened)
-        lines.push(field("Terminal", "Terminal.app (opened at launch)"));
+        lines.push(field("Terminal", `${record.terminal === "ghostty" ? "Ghostty" : record.terminal === "iterm2" ? "iTerm2" : "Terminal.app"} (opened at launch)`));
     if (record.exit_code !== undefined)
         lines.push(field("Exit code", badExit ? paint(clean(record.exit_code), 31) : clean(record.exit_code)));
     if (record.signal)

package/dist/guard.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { resolve } from "node:path";
+import { mcpName, claudeMcpConfig } from "./mcp.js";
 export const runSchema = z
     .object({
     runtime: z.enum(["codex", "claude"]),
@@ -14,8 +15,10 @@ export const runSchema = z
     kind: z.enum(["session", "task"]).default("session"),
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).optional(),
     open: z.boolean().optional(),
+    terminal: z.enum(["auto", "terminal", "iterm2", "ghostty"]).optional(),
     permissions: z.enum(["auto", "deny", "bypass"]).optional(),
     sandbox: z.enum(["read-only", "workspace-write", "full-access"]).optional(),
+    mcp: z.array(mcpName).optional(),
     args: z.array(z.string()).default([]),
 })
     .strict();
@@ -52,7 +55,7 @@ function extras(req) {
     }
     return result;
 }
-export function launchArgs(req, config) {
+export function launchArgs(req, config, mcp = [], bridgePath) {
     const extra = extras(req);
     const policy = resolvePermissions(req, config);
     if (req.runtime === "codex")
@@ -88,7 +91,11 @@ export function launchArgs(req, config) {
         disableAllHooks: true,
         permissions: {
             defaultMode: mode,
-            deny: readonly ? ["Edit", "Write", "NotebookEdit"] : [],
+            allow: mcp.flatMap((s) => s.config.tools.map((t) => `mcp__${s.name}__${t}`)),
+            deny: [
+                ...(readonly ? ["Edit", "Write", "NotebookEdit"] : []),
+                ...mcp.flatMap((s) => s.excludedTools.map((t) => `mcp__${s.name}__${t}`)),
+            ],
             additionalDirectories: [],
         },
         sandbox: {
@@ -111,7 +118,7 @@ export function launchArgs(req, config) {
         "",
         "--strict-mcp-config",
         "--mcp-config",
-        '{"mcpServers":{}}',
+        JSON.stringify(claudeMcpConfig(mcp, bridgePath)),
         "--settings",
         JSON.stringify(settings),
         ...extra,

package/dist/hosts/terminal.js

@@ -1,13 +1,30 @@
 import { access, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
 import { constants } from "node:fs";
 import { delimiter, join } from "node:path";
 import { command } from "../identity/processes.js";
-export async function terminalAvailable(platform = process.platform) {
+export async function terminalAvailable(platform = process.platform, terminal = "terminal") {
     if (platform !== "darwin")
         return false;
     try {
-        await access("/System/Applications/Utilities/Terminal.app");
-        await access("/usr/bin/osascript", constants.X_OK);
+        if (terminal === "terminal") {
+            await access("/System/Applications/Utilities/Terminal.app");
+        }
+        else {
+            const name = terminal === "ghostty" ? "Ghostty.app" : "iTerm.app";
+            const found = await Promise.all(["/Applications", join(homedir(), "Applications")].map(async (dir) => {
+                try {
+                    await access(join(dir, name));
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }));
+            if (!found.some(Boolean))
+                return false;
+        }
+        await access(terminal === "ghostty" ? "/usr/bin/open" : "/usr/bin/osascript", constants.X_OK);
         return true;
     }
     catch {
@@ -25,23 +42,52 @@ export async function tmuxExecutable() {
         }
         catch { }
     }
-    throw new Error("Cannot locate tmux executable for Terminal.app");
+    throw new Error("Cannot locate tmux executable for terminal viewer");
 }
-export async function openTerminal(tmux, server, hostRef, deadline) {
+export async function openTerminal(tmux, server, hostRef, deadline, terminal = "terminal") {
     if (!/^[a-zA-Z0-9_-]+$/.test(server) || !/^@\d+$/.test(hostRef))
         throw new Error("Invalid tmux terminal target");
     if (Date.now() >= deadline)
-        throw new Error("Launch deadline expired before opening Terminal.app");
+        throw new Error("Launch deadline expired before opening terminal");
+    const timeout = Math.max(1, Math.min(10000, deadline - Date.now()));
+    if (terminal === "ghostty") {
+        await command("/usr/bin/open", [
+            "-na",
+            "Ghostty",
+            "--args",
+            "--quit-after-last-window-closed=true",
+            // A separate instance otherwise restores the user's saved tabs/windows.
+            "--window-save-state=never",
+            "-e",
+            tmux,
+            "-L",
+            server,
+            "attach-session",
+            "-t",
+            hostRef,
+        ], timeout);
+        return;
+    }
     const quoted = "'" + tmux.replaceAll("'", "'\\''") + "'";
-    const shellCommand = `${quoted} -L ${server} attach-session -t muster \\; select-window -t ${hostRef}`;
+    const shellCommand = `${quoted} -L ${server} attach-session -t ${hostRef}`;
+    // Terminal must create the requested window before activation. Activating
+    // a cold app first also creates its default shell window.
     await command("/usr/bin/osascript", [
         "-e",
-        `on run argv
-  tell application "Terminal"
+        terminal === "iterm2"
+            ? `on run argv
+  tell application "iTerm"
+    create window with default profile command (item 1 of argv)
     activate
+  end tell
+end run`
+            : `on run argv
+  tell application "Terminal"
+    launch
     do script (item 1 of argv)
+    activate
   end tell
 end run`,
         shellCommand,
-    ], Math.max(1, Math.min(10000, deadline - Date.now())));
+    ], timeout);
 }

package/dist/hosts/tmux.js

@@ -1,4 +1,5 @@
 import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -24,11 +25,11 @@ export class TmuxHost {
             return false;
         }
     }
-    openAvailable() {
-        return terminalAvailable();
+    openAvailable(terminal = "terminal") {
+        return terminalAvailable(process.platform, terminal);
     }
-    async open(hostRef, deadline) {
-        await openTerminal(await tmuxExecutable(), this.server, hostRef, deadline);
+    async open(hostRef, deadline, terminal = "terminal") {
+        await openTerminal(await tmuxExecutable(), this.server, hostRef, deadline, terminal);
     }
     capabilities() {
         return { watchable: true, attachable: true, survivesParentExit: true };
@@ -52,13 +53,9 @@ export class TmuxHost {
             file,
         ];
         try {
-            let output;
-            try {
-                output = await this.call(["new-session", "-s", "muster", ...common], opts.deadline);
-            }
-            catch {
-                output = await this.call(["new-window", "-t", "muster", ...common], opts.deadline);
-            }
+            // Window selection is session-wide: sharing a session makes every
+            // attached terminal follow whichever agent was opened most recently.
+            const output = await this.call(["new-session", "-s", `muster-${randomUUID()}`, ...common], opts.deadline);
             const [hostRef, pid] = output.trim().split("\t");
             if (!hostRef || !/^@\d+$/.test(hostRef) || !Number(pid))
                 throw new Error("tmux returned an invalid window identity");
@@ -69,8 +66,7 @@ export class TmuxHost {
             try {
                 const windows = await this.call([
                     "list-windows",
-                    "-t",
-                    "muster",
+                    "-a",
                     "-F",
                     "#{window_id}\t#{pane_start_command}",
                 ]);
@@ -87,14 +83,16 @@ export class TmuxHost {
         try {
             return (await this.call([
                 "list-windows",
-                "-t",
-                "muster",
+                "-a",
                 "-F",
-                "#{window_id}\t#{pane_pid}\t#{window_name}",
+                "#{window_id}\t#{pane_pid}\t#{window_name}\t#{session_name}",
             ]))
                 .trim()
                 .split("\n")
-                .filter(Boolean)
+                .filter((l) => {
+                const session = l.split("\t")[3];
+                return (session === "muster" || /^muster-[0-9a-f-]{36}$/.test(session ?? ""));
+            })
                 .map((l) => {
                 const [hostRef, pid, label] = l.split("\t");
                 return { hostRef: hostRef, pid: Number(pid), label: label };
@@ -117,6 +115,6 @@ export class TmuxHost {
         }
     }
     attachHint(hostRef) {
-        return `tmux -L ${this.server} attach-session -t muster \\; select-window -t ${hostRef}`;
+        return `tmux -L ${this.server} attach-session -t ${hostRef}`;
     }
 }

package/dist/mcp-bridge.js

@@ -0,0 +1,91 @@
+// Claude has permission rules, but no MCP exposure allowlist. This stdio
+// connection exposes and dispatches only the operator-selected tools, including
+// when the upstream server changes its tool catalog after launch.
+import { readFile } from "node:fs/promises";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { mcpServerSchema, mcpName, mcpTransport } from "./mcp.js";
+async function main() {
+    const [path, name] = process.argv.slice(2);
+    if (!path || !name || !mcpName.safeParse(name).success)
+        throw new Error("Invalid MCP bridge arguments");
+    const definitions = JSON.parse(await readFile(path, "utf8"));
+    const config = mcpServerSchema.parse(definitions[name]);
+    const client = new Client({ name: "muster-tool-bridge", version: "1" }, { capabilities: {} });
+    const server = new Server({ name: `muster-${name}`, version: "1" }, { capabilities: { tools: {} } });
+    let shutdown;
+    const close = () => (shutdown ??= Promise.resolve().then(async () => {
+        await client.close().catch(() => { });
+        await server.close().catch(() => { });
+    }));
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+        process.once(signal, () => {
+            void close().finally(() => process.exit(0));
+        });
+    process.stdin.once("end", () => {
+        void close();
+    });
+    process.stdin.once("close", () => {
+        void close();
+    });
+    server.onclose = () => {
+        void close();
+    };
+    client.onclose = () => {
+        void close();
+    };
+    const transport = mcpTransport(config, process.env, process.cwd());
+    const timer = setTimeout(() => {
+        void close().finally(() => process.exit(1));
+    }, config.startup_timeout_sec * 1000);
+    try {
+        await client.connect(transport);
+        if (shutdown) {
+            await close();
+            return;
+        }
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : {});
+            tools.push(...page.tools.filter((t) => config.tools.includes(t.name)));
+            cursor = page.nextCursor;
+        } while (cursor);
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+        if (!config.tools.includes(params.name))
+            return {
+                isError: true,
+                content: [
+                    { type: "text", text: "Tool not enabled for this Muster launch" },
+                ],
+            };
+        return await client.callTool({
+            name: params.name,
+            arguments: params.arguments,
+        });
+    });
+    try {
+        await server.connect(new StdioServerTransport());
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}
+main().catch(() => {
+    process.stderr.write("Muster MCP connection failed; check the selected server configuration.\n");
+    process.exitCode = 1;
+});

package/dist/mcp.js

@@ -0,0 +1,207 @@
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const mcpName = z.string().regex(/^[a-zA-Z0-9_-]+$/);
+const environmentName = z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/);
+export const mcpServerSchema = z
+    .object({
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).default([]),
+    url: z
+        .string()
+        .url()
+        .refine((s) => /^https?:\/\//.test(s), "MCP URL must use HTTP(S)")
+        .optional(),
+    env: z.record(z.string()).default({}),
+    env_vars: z.array(environmentName).default([]),
+    bearer_token_env_var: environmentName.optional(),
+    tools: z.array(mcpName).min(1),
+    required: z.boolean().default(false),
+    startup_timeout_sec: z.number().positive().max(60).default(10),
+})
+    .strict()
+    .superRefine((v, ctx) => {
+    if (!!v.command === !!v.url)
+        ctx.addIssue({
+            code: "custom",
+            message: "MCP server requires exactly one of command or url",
+        });
+    if (v.command && v.bearer_token_env_var)
+        ctx.addIssue({
+            code: "custom",
+            message: "bearer_token_env_var requires an HTTP server",
+        });
+    if (v.url &&
+        (v.args.length || Object.keys(v.env).length || v.env_vars.length))
+        ctx.addIssue({
+            code: "custom",
+            message: "args, env and env_vars require a stdio server",
+        });
+});
+export function selectMcp(req, config) {
+    // Personal defaults apply to sessions, not unattended one-shot tasks.
+    const names = req.mcp ?? (req.kind === "session" ? config.default_mcp : []);
+    return [...new Set(names)].map((name) => {
+        const server = Object.hasOwn(config.mcp_servers, name)
+            ? config.mcp_servers[name]
+            : undefined;
+        if (!server)
+            throw new Error(`Unknown MCP server: ${name}`);
+        return {
+            name,
+            config: server,
+            required: req.mcp !== undefined || server.required,
+        };
+    });
+}
+export function mcpEnvironment(servers, base, source) {
+    const env = { ...base };
+    for (const { config } of servers) {
+        for (const key of [
+            ...config.env_vars,
+            ...(config.bearer_token_env_var ? [config.bearer_token_env_var] : []),
+        ]) {
+            if (source[key] !== undefined)
+                env[key] = source[key];
+        }
+    }
+    return env;
+}
+function serverEnv(config, env) {
+    const result = { ...config.env };
+    for (const key of config.env_vars) {
+        if (env[key] === undefined)
+            throw new Error(`Missing MCP environment variable: ${key}`);
+        result[key] = env[key];
+    }
+    return result;
+}
+function headers(config, env) {
+    if (!config.bearer_token_env_var)
+        return {};
+    const value = env[config.bearer_token_env_var];
+    if (!value)
+        throw new Error("Missing MCP bearer token environment variable");
+    return { Authorization: `Bearer ${value}` };
+}
+export function mcpTransport(config, env, cwd) {
+    const transport = config.command
+        ? new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: { ...env, ...serverEnv(config, env) },
+            cwd,
+            stderr: "pipe",
+        })
+        : new StreamableHTTPClientTransport(new URL(config.url), {
+            requestInit: { headers: headers(config, env) },
+        });
+    if (transport instanceof StdioClientTransport)
+        transport.stderr?.on("data", () => { });
+    return transport;
+}
+export async function prepareMcp(selected, env, cwd, deadline) {
+    const servers = [], warnings = [];
+    for (const server of selected) {
+        const client = new Client({ name: "muster-preflight", version: "1" }, { capabilities: {} });
+        let timer;
+        let diagnostic = "startup or tool discovery failed (check executable, credentials and server configuration)";
+        try {
+            const timeout = Math.min(server.config.startup_timeout_sec * 1000, deadline - Date.now());
+            if (timeout <= 0)
+                throw new Error("deadline");
+            const transport = mcpTransport(server.config, env, cwd);
+            const discover = async () => {
+                await client.connect(transport);
+                const names = new Set();
+                let cursor;
+                do {
+                    const page = await client.listTools(cursor ? { cursor } : {});
+                    for (const tool of page.tools) {
+                        if (!mcpName.safeParse(tool.name).success)
+                            throw new Error("Unsupported tool name");
+                        names.add(tool.name);
+                    }
+                    cursor = page.nextCursor;
+                } while (cursor);
+                const missing = server.config.tools.filter((name) => !names.has(name));
+                if (missing.length) {
+                    diagnostic = `configured tools not found: ${missing.join(", ")}`;
+                    throw new Error("missing tools");
+                }
+                return [...names].filter((name) => !server.config.tools.includes(name));
+            };
+            const excludedTools = await Promise.race([
+                discover(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("timeout")), timeout);
+                }),
+            ]);
+            servers.push({ ...server, excludedTools });
+        }
+        catch {
+            // Server errors may include tokens or environment values; never log them.
+            const message = `MCP server ${server.name}: ${diagnostic}`;
+            if (server.required)
+                throw new Error(message);
+            warnings.push(`${message}; skipped optional default`);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            await client.close().catch(() => { });
+        }
+    }
+    return {
+        servers,
+        summary: {
+            mcp: servers.map((s) => s.name),
+            ...(warnings.length ? { mcp_warnings: warnings } : {}),
+        },
+    };
+}
+export function codexMcpConfig(server) {
+    const c = server.config;
+    return {
+        ...(c.command
+            ? { command: c.command, args: c.args, env: c.env, env_vars: c.env_vars }
+            : {
+                url: c.url,
+                ...(c.bearer_token_env_var
+                    ? { bearer_token_env_var: c.bearer_token_env_var }
+                    : {}),
+            }),
+        enabled: true,
+        required: server.required,
+        enabled_tools: c.tools,
+        disabled_tools: [],
+        startup_timeout_sec: c.startup_timeout_sec,
+        default_tools_approval_mode: "approve",
+    };
+}
+export function claudeMcpConfig(servers, bridgePath) {
+    if (servers.length && !bridgePath)
+        throw new Error("Missing MCP bridge configuration");
+    return {
+        mcpServers: Object.fromEntries(servers.map(({ name, config }) => [
+            name,
+            {
+                type: "stdio",
+                command: process.execPath,
+                args: [
+                    fileURLToPath(new URL("../dist/mcp-bridge.js", import.meta.url)),
+                    bridgePath,
+                    name,
+                ],
+                env: Object.fromEntries([
+                    ...config.env_vars,
+                    ...(config.bearer_token_env_var
+                        ? [config.bearer_token_env_var]
+                        : []),
+                ].map((key) => [key, "${" + key + "}"])),
+            },
+        ])),
+    };
+}

package/dist/muster.js

@@ -13,7 +13,7 @@ const listSchema = z
     .strict();
 const idSchema = z.object({ id: z.string().min(1) }).strict();
 const help = `Usage:
-  muster run <codex|claude> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [-- RUNTIME_OPTIONS]
+  muster run <codex|claude> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [--open] [--terminal APP] [-- RUNTIME_OPTIONS]
   muster list [--kind session|task] [--format json|human]
   muster stop <id> [--format json|human]
   muster output <id>
@@ -21,7 +21,10 @@ const help = `Usage:
 
 run also accepts --format json|human, --permissions auto|deny|bypass,
 and --sandbox read-only|workspace-write|full-access before -- RUNTIME_OPTIONS.
---open displays a tmux session in Terminal.app on macOS.
+--open displays a tmux session on macOS. --terminal accepts auto (Terminal.app),
+terminal, iterm2, or ghostty, and requires --open.
+--mcp NAME is repeatable and replaces configured session defaults; --no-mcp
+clears them. Tasks use no MCP defaults; select servers explicitly.
 run, list and stop default to JSON. output prints raw task text.
 
 pty launches print their record and keep this process running. Ctrl-C stops the
@@ -53,7 +56,7 @@ async function main() {
             });
         });
     if (mcp) {
-        const server = new Server({ name: "muster", version: "0.4.0" }, { capabilities: { tools: {} } });
+        const server = new Server({ name: "muster", version: "0.6.0" }, { capabilities: { tools: {} } });
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: [
                 {
@@ -76,7 +79,12 @@ async function main() {
                             },
                             open: {
                                 type: "boolean",
-                                description: "Open the tmux session in Terminal.app (macOS only).",
+                                description: "Open the tmux session in a terminal viewer (macOS only).",
+                            },
+                            terminal: {
+                                type: "string",
+                                enum: ["auto", "terminal", "iterm2", "ghostty"],
+                                description: "Viewer app; requires open. Auto uses Terminal.app.",
                             },
                             permissions: {
                                 type: "string",
@@ -88,6 +96,11 @@ async function main() {
                                 enum: ["read-only", "workspace-write", "full-access"],
                                 description: "Defaults to config (read-only). Full access requires config authorization.",
                             },
+                            mcp: {
+                                type: "array",
+                                items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
+                                description: "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
+                            },
                             args: { type: "array", items: { type: "string" } },
                         },
                         required: ["runtime", "prompt"],
@@ -170,12 +183,21 @@ async function main() {
                 kind: { type: "string" },
                 host: { type: "string" },
                 open: { type: "boolean" },
+                terminal: { type: "string" },
                 format: { type: "string" },
                 permissions: { type: "string" },
                 sandbox: { type: "string" },
+                mcp: { type: "string", multiple: true },
+                "no-mcp": { type: "boolean" },
             },
         });
-        const { format = "json", ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, ...values } = parsed;
+        if (noMcp !== undefined && command !== "run")
+            throw new Error("--no-mcp applies only to run");
+        if (noMcp && values.mcp)
+            throw new Error("--mcp and --no-mcp cannot be combined");
+        if (noMcp)
+            values.mcp = [];
         if (format !== "json" && format !== "human")
             throw new Error("format must be json or human");
         if (command === "output" && parsed.format !== undefined)

package/dist/run.js

@@ -17,27 +17,30 @@ import { assertClaudePolicy } from "./claude-policy.js";
 import { codexPolicyArgs } from "./codex-policy.js";
 import { CodexRpc } from "./codex-rpc.js";
 import { assignNames, resolvePeer } from "./naming.js";
+import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
 export class Muster {
     config;
     home;
     env;
     drivers;
+    sourceEnv;
     registry;
     log;
     owned = new Set();
     closing = false;
     active = new Set();
-    constructor(config, home, env, drivers) {
+    constructor(config, home, env, drivers, sourceEnv) {
         this.config = config;
         this.home = home;
         this.env = env;
         this.drivers = drivers;
+        this.sourceEnv = sourceEnv;
         this.registry = new Registry(home);
         this.log = new LaunchLog(home);
     }
     static async create(opts = {}) {
         const env = launchEnv(opts.env ?? process.env), home = opts.home ?? join(env.HOME ?? homedir(), ".muster");
-        return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts());
+        return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts(), { ...(opts.env ?? process.env) });
     }
     run(input, requester = "cli") {
         if (this.closing)
@@ -52,16 +55,22 @@ export class Muster {
             throw new Error("cwd is not a directory");
         if (req.kind === "task" && req.host)
             throw new Error("host applies only to session launches");
+        if (req.terminal && !req.open)
+            throw new Error("--terminal requires --open");
+        const terminal = !req.terminal || req.terminal === "auto" ? "terminal" : req.terminal;
         const requestedHost = req.host ?? this.config.host;
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))
             throw new Error("--open requires a tmux session on macOS");
         const permissions = resolvePermissions(req, this.config);
-        const argv = launchArgs(req, this.config), driver = req.kind === "session"
+        const selectedMcp = selectMcp(req, this.config);
+        let argv = launchArgs(req, this.config);
+        const driver = req.kind === "session"
             ? await selectHost(req.open ? "tmux" : requestedHost, this.drivers)
             : undefined;
-        if (req.open && (!driver?.open || !(await driver.openAvailable?.())))
-            throw new Error("--open requires Terminal.app on macOS and tmux");
+        if (req.open &&
+            (!driver?.open || !(await driver.openAvailable?.(terminal))))
+            throw new Error(`--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
         let policy = [];
         if (req.runtime === "claude")
             await assertClaudePolicy(this.env);
@@ -81,22 +90,37 @@ export class Muster {
                 prompt: req.prompt,
                 host: driver?.id ?? null,
                 requester,
-                ...(req.open ? { open: true } : {}),
+                ...(req.open ? { open: true, terminal } : {}),
                 args: req.args,
+                mcp: selectedMcp.map((s) => s.name),
                 ...permissions,
             });
+            const prepared = await prepareMcp(selectedMcp, mcpEnvironment(selectedMcp, this.env, this.sourceEnv), req.cwd, deadline);
+            const runtimeEnv = mcpEnvironment(prepared.servers, this.env, this.sourceEnv);
+            entry = await this.registry.update(entry.launchId, prepared.summary);
+            let bridgePath;
+            if (req.runtime === "claude" && prepared.servers.length) {
+                const dir = join(this.home, "mcp");
+                await mkdir(dir, { recursive: true, mode: 0o700 });
+                bridgePath = join(dir, entry.launchId + ".json");
+                entry = await this.registry.update(entry.launchId, {
+                    mcpConfigPath: bridgePath,
+                });
+                await writeFile(bridgePath, JSON.stringify(Object.fromEntries(prepared.servers.map((s) => [s.name, s.config]))), { mode: 0o600 });
+            }
+            argv = launchArgs(req, this.config, prepared.servers, bridgePath);
             if (req.runtime === "codex") {
-                policy = await codexPolicyArgs(this.env, req.cwd, deadline);
+                policy = await codexPolicyArgs(runtimeEnv, req.cwd, deadline, prepared.servers);
                 argv.splice(1, 0, ...policy);
             }
             if (this.closing)
                 throw new Error("Launch cancelled: Muster is closing");
             if (req.kind === "task")
-                return await this.startTask(entry, argv);
+                return await this.startTask(entry, argv, runtimeEnv);
             const launched = await driver.launch({
                 argv,
                 cwd: req.cwd,
-                env: this.env,
+                env: runtimeEnv,
                 label: req.prompt.slice(0, 48),
                 deadline,
             });
@@ -111,7 +135,7 @@ export class Muster {
                 ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
                 : "no descendant runtime identity found";
             if (req.runtime === "codex")
-                rpc = new CodexRpc(this.env, req.cwd, policy);
+                rpc = new CodexRpc(this.env, req.cwd);
             while (Date.now() < deadline) {
                 if (deadline - Date.now() < 25)
                     break;
@@ -171,6 +195,7 @@ export class Muster {
                         const peer = {
                             kind: "session",
                             ...permissions,
+                            ...prepared.summary,
                             name: named.display,
                             canonical_id: named.canonicalId,
                             runtime,
@@ -186,8 +211,9 @@ export class Muster {
                         };
                         if (req.open) {
                             openingTerminal = true;
-                            await driver.open(launched.hostRef, deadline);
+                            await driver.open(launched.hostRef, deadline, terminal);
                             peer.terminal_opened = true;
+                            peer.terminal = terminal;
                         }
                         entry = await this.registry.update(entry.launchId, {
                             id: identity.id,
@@ -228,19 +254,20 @@ export class Muster {
             await rpc?.close();
         }
     }
-    async startTask(entry, argv) {
+    async startTask(entry, argv, env) {
         const dir = join(this.home, "tasks", entry.id);
         await mkdir(dir, { recursive: true, mode: 0o700 });
         const outputPath = join(dir, "output.txt"), exitPath = join(dir, "exit.json"), startPath = join(dir, "start"), specPath = join(dir, "launch.json");
         await writeFile(specPath, JSON.stringify({
             argv,
             cwd: entry.cwd,
-            env: this.env,
+            env,
             outputPath,
             exitPath,
             startPath,
             logHome: this.home,
             launchId: entry.launchId,
+            mcpConfigPath: entry.mcpConfigPath,
         }), { mode: 0o600 });
         const child = spawn(process.execPath, [
             fileURLToPath(new URL("../dist/task-worker.js", import.meta.url)),
@@ -268,6 +295,8 @@ export class Muster {
                 kind: "task",
                 permissions: entry.permissions,
                 sandbox: entry.sandbox,
+                mcp: entry.mcp ?? [],
+                ...(entry.mcp_warnings ? { mcp_warnings: entry.mcp_warnings } : {}),
                 id: entry.id,
                 runtime: entry.runtime,
                 state: "running",
@@ -288,6 +317,15 @@ export class Muster {
         }
     }
     async stopEntry(entry) {
+        try {
+            await this.stopEntryProcesses(entry);
+        }
+        finally {
+            if (entry.mcpConfigPath)
+                await rm(entry.mcpConfigPath, { force: true });
+        }
+    }
+    async stopEntryProcesses(entry) {
         if (!entry.root)
             return;
         if (!(await isSame(entry.root))) {
@@ -391,6 +429,8 @@ export class Muster {
             if (kind && kind !== original.kind)
                 continue;
             const e = await this.refreshed(original);
+            if (e.mcpConfigPath && !["starting", "running"].includes(e.status))
+                await rm(e.mcpConfigPath, { force: true });
             if (e.kind === "session")
                 result.push({
                     ...e.peer,
@@ -412,6 +452,8 @@ export class Muster {
                 catch { }
                 result.push({
                     kind: "task",
+                    ...(e.mcp ? { mcp: e.mcp } : {}),
+                    ...(e.mcp_warnings ? { mcp_warnings: e.mcp_warnings } : {}),
                     ...(e.permissions
                         ? { permissions: e.permissions, sandbox: e.sandbox }
                         : {}),

package/dist/task-worker.js

@@ -33,6 +33,8 @@ async function finish(code, signal, error) {
     finished = true;
     try {
         await output.close();
+        if (spec.mcpConfigPath)
+            await rm(spec.mcpConfigPath, { force: true });
         await new LaunchLog(spec.logHome).write({
             event: "task_exit",
             launch_id: spec.launchId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {