feat(desktop): MCP servers defined in .mcp.json are not visible to agent sessions

[matthewdonsemail-lab]

Problem

When an MCP server is added to .mcp.json in the agent's working directory and Buzz Desktop is restarted, the server's tools are never surfaced to the agent session. The agent reports only its built-in tools (e.g. buzz-dev-mcp). The MCP server is completely invisible.

Reproduction steps

1. Install an MCP server locally, e.g. @playwright/mcp (npm install @playwright/mcp).
2. Add an entry to .mcp.json in the agent's working directory:

   {
     mcpServers: {
       playwright: {
         command: node,
         args: [
           node_modules/@playwright/mcp/cli.js,
           --user-data-dir, C:\Users\0\.buzz\chrome-matthew-don,
           --executable-path, C:\Users\0\.cloakbrowser\chromium-146.0.7680.177.5\chrome.exe
         ]
       }
     }
   }

3. Restart Buzz Desktop.
4. Trigger an agent session and query which tools are available.

Expected: The agent session lists tools provided by the playwright MCP server (e.g. browser_navigate, browser_snapshot, etc.).

Actual: Agent session reports zero playwright tools. Only built-in tools are present.

Additional confirmation

The MCP server binary runs without errors when launched manually:

cd C:\Users\0\.buzz
node node_modules\@playwright\mcp\cli.js --user-data-dir=... --executable-path=...

No crash, no error output. The server itself is healthy — Buzz Desktop simply never wires it through.

Also confirmed: no per-agent mcp_servers field exists in managed-agents.json (C:\Users\0\AppData\Roaming\xyz.block.buzz.app\agents\managed-agents.json). There is no second config to update.

Root cause (hypothesis)

Buzz Desktop spawns MCP servers at startup, but there is no mechanism that injects the discovered tools from those servers into an agent's tool list for the session. The connection between "server is running" and "agent can call its tools" is the missing link. PR #4588 adds the Project-owned connection model that appears to be the infra foundation for this.

Impact

Without persistent MCP tools, agents are forced into an anti-pattern workaround: chain all browser automation steps into a single shell call because the browser is a child process of the shell and is killed when the shell exits:

cd /c/Users/0/.buzz && npx @playwright/cli open --headed & sleep 4 &&   npx @playwright/cli --s=default goto 'https://x.com/...' &&   npx @playwright/cli --s=default snapshot

This means:

• No multi-step interactive sessions — the entire sequence must be planned upfront
• No ability to react to page state between steps
• No persistent authenticated browser context across tool calls

This is a significant capability gap for any agent doing web automation (outreach, scraping, form filling, etc.).

Related

• PR feat(desktop): add Project connection setup #4588 — adds Project-owned MCP connection model (infra foundation)
• Issue Docs: how to connect an external MCP server (Olostep) to Buzz agents? #4515 — missing docs on how Desktop picks up .mcp.json

Suggested resolution

1. After PR feat(desktop): add Project connection setup #4588 lands, implement agent bindings so a Project-owned MCP connection's tools are injected into agent sessions bound to that project.
2. Add a UI indicator in Desktop showing which MCP servers are active and their tools are available to the current agent session — right now there is zero feedback on whether a server loaded or failed silently.
3. Document the end-to-end flow: add .mcp.json entry → configure Project connection → bind agent → confirm tools visible in session.

[matthewdonsemail-lab]

Related: Issue #4853 — child processes killed on shell exit

This issue has a compounding problem that deserves its own tracking: even before MCP tools are wired through, any service an agent starts via shell is immediately killed when the shell tool call ends.

The two issues together describe the full picture:

• feat(desktop): MCP servers defined in .mcp.json are not visible to agent sessions #4852 (this issue): MCP servers are not surfaced to agent sessions, so the agent is forced to use shell commands for browser automation.
• feat(desktop): child processes spawned by agent shell commands are killed when the shell exits — need configurable keep-alive toggle #4853: Shell-spawned child processes (including browser sessions) are killed when the shell exits due to Windows Job Object JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE inheritance.

The workaround we're using today is chaining everything into one shell call, which is an anti-pattern:

npx @playwright/cli open --headed & sleep 4 && goto && snapshot

Fixing #4852 (MCP tools wired through) is the correct long-term resolution — if the browser runs as an MCP-managed process, it lives outside the Job Object entirely. But #4853 also needs a configurable keep-alive toggle for any other long-running services agents need to maintain across tool calls.

[wolfyy970]

I reproduced this in the managed-agent path and now have the full handoff working locally: a Project connection resolves into the shared MCP launch document, Codex starts through ACP, sees the tool, and calls it.

#4164 defines the versioned document and stdio handoff. #4271 extends the same schema to HTTP. Once those land, the remaining Desktop work is to resolve .mcp.json and Project connections into that document before session/new.

I'm using this issue's expected behavior as the acceptance test: a configured server appears as an agent tool after launch and still works after a Buzz restart, without storing credentials in portable configuration.

[matthewdonsemail-lab]

Source references from current main (2ea9385015fb922de2adf0a53e86fc5a21d07b90)

Adding concrete repository references from the reproduced Playwright use case:

• desktop/src-tauri/src/managed_agents/config_bridge/claude.rs and config_bridge/codex.rs detect MCP servers from provider config, which establishes a discovery/display path but not agent-session injection.
• desktop/src-tauri/src/managed_agents/discovery/runtime_metadata.rs calls mcp_command vestigial and says agents use the bundled CLI integration.
• desktop/src-tauri/src/managed_agents/runtime.rs resolves a single derived mcp_command and injects it through BUZZ_ACP_MCP_COMMAND; this is the current launch boundary where a Project connection/LaunchSpec handoff would need to become visible to the agent.
• desktop/src-tauri/src/managed_agents/agent_snapshot_tests.rs explicitly prevents MCP toolset and command fields from entering portable snapshots, so the solution should remain device-local as proposed in feat(desktop): add Project connection setup #4588.

The expected UX remains: configure/test a device-local Project connection, bind it to an agent, launch the session, and see the discovered tools without relying on portable agent config.