CLI: expose --mcp-command and --env on `buzz agents draft-create`/`draft-update` (GUI Advanced parity)

[adamazad]

Problem

buzz agents draft-create / draft-update can set channel, display_name,
system_prompt, runtime, provider, model, respond_to — but not the
harness's MCP command or extra env. Those are the two fields that let a managed
agent carry external tools (an app's own MCP server + the token it needs).

Today only Desktop's Create-agent → Advanced exposes them
(desktop/src/features/agents/channelAgents.ts:237 → runtime.mcpCommand,
plus env_vars in useGlobalAgentConfig.ts:18). The harness already supports
an arbitrary MCP:

• crates/buzz-acp/src/config.rs:261 — #[arg(long, env = "BUZZ_ACP_MCP_COMMAND")] pub mcp_command: String
• crates/buzz-acp/src/lib.rs:4141 build_mcp_servers() — takes any command (derives name from path), not hardcoded to buzz-cli; injects BUZZ_RELAY_URL / BUZZ_PRIVATE_KEY into its env.
• crates/buzz-acp/src/lib.rs:3721 — extra_env passthrough already exists.

So the capability is there; the CLI just can't reach it. Anyone scripting agent
provisioning (CI, an app's own setup command) is forced through the Desktop GUI.

Ask

Add to buzz agents draft-create and draft-update:

--mcp-command <cmd>        # BUZZ_ACP_MCP_COMMAND for the harness
--env KEY=VALUE            # repeatable; merged into the MCP subprocess env (extra_env)

Wire them into the same request the Desktop Advanced panel already sends
(runtime.mcpCommand, env_vars) — no new harness behavior, just CLI parity
with the GUI.

Why

Lets an app provision a fully-configured managed agent from one scripted command
— e.g. a <app> mcp tool server + its <APP>_TOKEN — instead of walking a user
through the Advanced GUI. Same motivation as the install deep-link (#2911):
make the agent path scriptable end-to-end.

Happy to send the PR if the shape looks right.

[adamazad]

Update: verified the CLI agents draft-create/draft-update path is the owner-encrypted no-secret owner-review contract (desktop/src/features/agents/agentManagement.ts parseAgentManagementRequest — strict hasOnlyKeys([channelId, displayName, systemPrompt]), drops the whole draft on any unknown key; agentManagement.test.mjs rejects secret-shaped fields). So adding --env/--mcp-command to the draft payload can't work as I first framed it — Desktop would reject it, and it'd push secrets through a boundary that deliberately excludes them.

Downstream (Figura) no longer needs this on the critical path: our agent authors figs via the CLI (no MCP injection needed) and keeps its token out-of-band in the harness env, so the no-secret draft carries only name+channel+prompt. Leaving this open as a lower-priority ask for a direct (non-draft) scriptable managed-agent provisioning command (mcpCommand/env_vars live on CreateManagedAgentInput, not the draft) — but that's a bigger design conversation and may conflict with the owner-review model by design. No PR incoming for now.

[jamiehudson1-collab]

Correction on the premise here: there is no Desktop UI for setting mcp_command, in Create or Edit.

I went looking for the "Create-agent → Advanced" panel this issue references and it doesn't exist as described. Every reference to mcpCommand in desktop/src is one of:

• Internal plumbing — types, hooks, channelAgents.ts:239/362, welcomeGuide.ts:241-257, instanceInputForDefinition.ts:153 — all just pass a value through from a predefined "runtime" object (runtimeToUse.mcpCommand in AddTeamToChannelDialog.tsx:143), never render an editable field.
• Test-only scaffolding (e2eBridge.ts, mock harness definitions).
• The one actual UI render, UserProfilePanelFields.tsx:355-360 — and it's a read-only, copy-to-clipboard display field on an agent's profile card (same treatment as "ACP command"/"Status"/"Runtime" — diagnostic info, not a setting). It's also gated behind if (managedAgent?.mcpCommand), so it only shows up once the value is already non-empty — every managed agent I checked (built-in Fizz/Honey/Bumble plus a custom one) had mcp_command: "", so this field doesn't render for any of them today.

So the actual state is: the harness fully supports an arbitrary MCP command end-to-end (confirmed, as this issue says), but there's no way to set it from the UI at all — not via a form, not via Advanced, nothing. EditAgentAdvancedFields.tsx (the real "edit agent" advanced-settings component) has zero MCP references.

This changes the ask: adding CLI flags for parity with a GUI path that doesn't exist just moves the same gap sideways. Worth either (a) scoping this issue to add both the GUI field and the CLI flags, or (b) splitting a separate issue for "no UI path exists to set mcp_command at all" so it's tracked independently of CLI scripting parity. Happy to help with either.

[jamiehudson1-collab]

Follow-up correction, this time on the harness-config side rather than just the missing UI: mcp_command doesn't even work via direct config-file edit. There is currently no way at all — not UI, not CLI, not hand-editing managed-agents.json — to give an individual agent a custom MCP server.

Traced it through desktop/src-tauri/src/:

• ManagedAgentRecord.mcp_command's own doc comment (managed_agents/types.rs:262) says outright: "Create-time snapshot of the catalog MCP command. Never read at spawn — the effective MCP command is always re-derived from the runtime catalog... no longer written by updates."
• At actual spawn (managed_agents/runtime.rs:527-529), the value is computed independently via known_acp_runtime(effective_command).and_then(|r| r.mcp_command) — a lookup into a hardcoded static table, KnownAcpRuntime in managed_agents/discovery/runtime_metadata.rs (the field is literally commented "vestigial" there). The persisted record's mcp_command is never consulted at this point. It's passed to the child only as the BUZZ_ACP_MCP_COMMAND env var (runtime.rs:585-591) — there's no --mcp-command CLI flag anywhere in this path.
• It's actively hostile to manual edits, not just indifferent: on every app launch, reconcile_provider_mcp_commands (migration.rs:1220, called from migration.rs:191) runs reconcile_mcp_commands_in_file (migration.rs:975), recomputes the catalog-derived "expected" value, and patches the JSON file to match if a hand-edited value differs (migration.rs:1003-1017).
• No file watcher exists on managed-agents.json either (grep for notify::/watch( across desktop/src-tauri/src is empty) — config is only read via explicit load_managed_agents calls (storage.rs:234), at launch and on user-initiated actions. So even ignoring the reconciler, a hand-edit only has a chance of mattering after a manual stop/start — which immediately triggers the reconciler and clobbers it anyway.

So "the harness already supports an arbitrary MCP command" (true — crates/buzz-acp genuinely does, via BUZZ_ACP_MCP_COMMAND) is disconnected from Desktop's actual managed-agent spawn path, which hardcodes it per-runtime-type from source, not per-agent from any persisted/user-facing config. Changing it today requires editing discovery/runtime_metadata.rs and rebuilding the app — and that changes it for every agent of that runtime, not one specific agent.

Given both corrections now on this thread, this issue's scope may need rethinking beyond "add CLI flags" — the whole record-level mcp_command field looks like dead/vestigial plumbing that should either be wired up for real (UI + spawn-time read + no reconciler clobber) or removed to stop implying a capability that doesn't exist.