SoundBlaster · SoundBlaster · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/README.md b/README.md
@@ -115,6 +115,21 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-c
 For full start/stop/status commands, Cursor JSON snippets, troubleshooting, and
 rollback to direct mode, see [Broker Mode Guide](docs/broker-mode.md).
 
+#### Multi-Agent Guidance
+
+When you run multiple MCP client processes at the same time:
+
+- **For shared MCP upstream sessions:** run one broker daemon host and configure each client with `--broker-connect`.
+- **For Web UI dashboard hosting:** only one process can bind a given `host:port` (for example `127.0.0.1:8080`).
+- If multiple direct-mode processes start with the same `--web-ui-port`, one process serves the dashboard and other processes continue MCP without dashboard hosting.
+- This ownership rule is process-level and independent from Xcode window state.
+
+Current limitation:
+- Broker CLI modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the Web UI dashboard process.
+- If you need dashboard diagnostics, run a separate direct-mode/Web-UI process (for example `--web-ui-only`) in parallel.
+
+See [Web UI Setup Guide](docs/webui-setup.md#multi-agent-web-ui-ownership-model) and [Troubleshooting](docs/troubleshooting.md#mcp-tools-are-green-but-dashboard-is-unreachable).
+
 ### Python Environment Setup (Development)
 
 If you plan to run `make install`, `pytest`, or other development commands, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error.
@@ -486,6 +501,10 @@ Features:
 
 Open http://localhost:8080 in your browser to view the dashboard.
 
+Important for multi-agent setups:
+- The dashboard is hosted by one wrapper process, not by Xcode or `mcpbridge`.
+- A single `host:port` can have only one listener; additional processes on the same port skip dashboard startup and continue MCP traffic.
+
 See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration.
 
 ## Known Issues

diff --git a/...Web_UI_host/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host.md b/...Web_UI_host/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host.md
@@ -0,0 +1,64 @@
+# PRD: FU-P13-T16 — Document multi-agent MCP usage and single Web UI host
+
+## 1. Objective
+
+Improve user-facing documentation so multi-agent MCP behavior is predictable and operable. The task clarifies that Web UI is not a separate service by default; it is hosted by one wrapper process that successfully binds a specific `host:port`. In multi-agent environments (Zed/Cursor/Claude/Codex starting separate wrapper instances), multiple processes may attempt to start Web UI on the same port, and non-host processes will continue MCP bridging while dashboard startup is skipped.
+
+The documentation must establish a recommended topology: one dedicated broker/Web UI host process and client processes using `--broker-connect`. It must also provide direct-mode alternatives (single Web UI owner, unique ports per process) and concrete diagnostics for “tools are green, dashboard unavailable.”
+
+## 2. Success Criteria and Acceptance Tests
+
+### Success Criteria
+- Multi-agent guidance is explicit in `README.md` and links to deeper broker/Web UI docs.
+- `docs/broker-mode.md` defines dedicated host + client proxy setup with concrete commands.
+- `docs/webui-setup.md` and `docs/troubleshooting.md` explain Web UI ownership semantics and conflict behavior.
+- All quality gates pass and coverage remains at or above project threshold.
+
+### Acceptance Tests
+- Validate docs contain at least one end-to-end example where only the host uses `--web-ui` and clients use `--broker-connect`.
+- Validate docs include direct-mode guidance for multiple agents without broker mode.
+- Validate troubleshooting includes listener ownership checks (`lsof`) and recovery options (`--web-ui-restart`, alternate port, dedicated host).
+
+## 3. Test-First Plan
+
+1. Add/update unit tests that lock in any behavior statements referenced by documentation if assertions are missing.
+2. If runtime behavior is already tested, avoid new tests and instead verify existing tests still cover described semantics.
+3. Run required quality gates in full:
+   - `pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing`
+
+## 4. Execution Plan (Hierarchical TODO)
+
+### Phase A — Source-of-truth alignment
+- Inputs: existing CLI/runtime behavior in `src/mcpbridge_wrapper/__main__.py`, `src/mcpbridge_wrapper/webui/server.py`.
+- Outputs: validated behavior statements for port collision and startup skip behavior.
+- Verification: docs assertions map to observed code paths and current warnings.
+
+### Phase B — Documentation updates
+- Inputs: `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, `docs/troubleshooting.md`.
+- Outputs: updated multi-agent sections, recommended topology commands, direct-mode fallback, and diagnostics.
+- Verification: link integrity, command consistency, no conflicting guidance.
+
+### Phase C — Validation artifacts
+- Inputs: updated docs + gate results.
+- Outputs: `SPECS/INPROGRESS/FU-P13-T16_Validation_Report.md` with PASS/FAIL verdict and evidence.
+- Verification: report includes command results and explicit acceptance criteria checks.
+
+## 5. Decision Points and Constraints
+
+- Constraint: preserve backward-compatible single-client setup instructions.
+- Constraint: avoid claiming behavior not implemented in code (for example automatic Web UI failover between processes).
+- Decision: use `FU-P13-T16` review subject `fu_p13_t16_multi_agent_mcp_docs` for report naming consistency.
+
+## 6. Notes (Docs to update)
+
+- `README.md`
+- `docs/broker-mode.md`
+- `docs/webui-setup.md`
+- `docs/troubleshooting.md`
+
+---
+**Archived:** 2026-02-28
+**Verdict:** PASS
diff --git a/...nt_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Validation_Report.md b/...nt_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Validation_Report.md
@@ -0,0 +1,39 @@
+# Validation Report: FU-P13-T16 — Document multi-agent MCP usage and single Web UI host
+
+**Date:** 2026-02-28
+**Task ID:** FU-P13-T16
+**Verdict:** PASS
+
+## Scope Implemented
+
+- Added multi-agent guidance to `README.md` clarifying:
+  - broker mode recommendation for shared MCP transport
+  - Web UI ownership semantics (single listener per `host:port`)
+  - current broker-mode limitation for dashboard hosting
+- Updated `docs/broker-mode.md` with:
+  - dedicated multi-agent topology section
+  - explicit Web UI behavior in broker modes
+  - Zed broker-connect config example
+- Updated `docs/webui-setup.md` with a dedicated multi-agent ownership model section.
+- Updated `docs/troubleshooting.md` with a new diagnostic path for: MCP tools connected while dashboard is unreachable.
+
+## Quality Gates
+
+- `pytest` → FAIL in this shell due environment import path (`ModuleNotFoundError: mcpbridge_wrapper`)
+- `PYTHONPATH=src pytest` → PASS (`672 passed, 5 skipped`)
+- `ruff check src/` → PASS
+- `mypy src/` → PASS
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS
+  - Total coverage: **91.5%** (required: >= 90%)
+
+## Acceptance Criteria Check
+
+- [x] Documentation states that only one process can bind a given Web UI `host:port`.
+- [x] Documentation explains why MCP can be healthy while Web UI is unavailable.
+- [x] Documentation provides a dedicated broker host + `--broker-connect` client pattern.
+- [x] Troubleshooting includes concrete checks for listener ownership and port conflicts.
+
+## Notes
+
+- The repository test environment in this session requires `PYTHONPATH=src` for direct `pytest` invocation.
+- No runtime code behavior was changed; this task is documentation-only.
diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-02-28 (FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow)
+**Last Updated:** 2026-02-28 (FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| FU-P13-T16 | [FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/](FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/) | 2026-02-28 | PASS |
 | FU-P11-T2-4 | [FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/](FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/) | 2026-02-28 | PASS |
 | FU-P11-T2-3 | [FU-P11-T2-3_Reorder_sessions_from_the_last_to_the_first/](FU-P11-T2-3_Reorder_sessions_from_the_last_to_the_first/) | 2026-02-28 | PASS |
 | BUG-T18 | [BUG-T18_Error_Breakdown_full_width_layout_fix/](BUG-T18_Error_Breakdown_full_width_layout_fix/) | 2026-02-26 | PASS |
@@ -162,6 +163,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_fu_p13_t16_multi_agent_mcp_docs.md](_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md) | Review report for FU-P13-T16 |
 | [REVIEW_P1-T1_project_structure.md](_Historical/REVIEW_P1-T1_project_structure.md) | Review report for P1-T1 |
 | [REVIEW_P1-T2_pyproject.toml.md](_Historical/REVIEW_P1-T2_pyproject.toml.md) | Review report for P1-T2 |
 | [REVIEW_P1-T3_linting_config.md](_Historical/REVIEW_P1-T3_linting_config.md) | Review report for P1-T3 |
@@ -273,6 +275,8 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-02-28 | FU-P13-T16 | Archived REVIEW_fu_p13_t16_multi_agent_mcp_docs report |
+| 2026-02-28 | FU-P13-T16 | Archived Document_multi_agent_MCP_usage_and_single_Web_UI_host (PASS) |
 | 2026-02-28 | FU-P11-T2-3 | Archived REVIEW_fu_p11_t2_3_session_ordering report |
 | 2026-02-28 | FU-P11-T2-3 | Archived Reorder_sessions_from_the_last_to_the_first (PASS) |
 | 2026-02-26 | BUG-T18 | Archived REVIEW_bug_t18_error_breakdown_layout report |

diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md b/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md
@@ -0,0 +1,28 @@
+## REVIEW REPORT — FU-P13-T16 multi-agent MCP docs
+
+**Scope:** origin/main..HEAD
+**Files:** 9
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- Documentation now aligns with runtime behavior: Web UI hosting is single-listener per `host:port`, and broker-mode flags are documented as transport-focused paths without dashboard hosting.
+- Guidance now separates two concerns clearly for multi-agent users: shared MCP transport (`--broker-daemon` + `--broker-connect`) vs dashboard ownership in direct/Web-UI-only modes.
+
+### Tests
+- Validation gates were executed and recorded in `FU-P13-T16_Validation_Report.md`.
+- Coverage remains above project threshold (91.5%).
+
+### Next Steps
+- No actionable review findings.
+- FOLLOW-UP step is skipped.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -2,9 +2,9 @@
 
 ## Recently Archived
 
+- **FU-P13-T16** — Document multi-agent MCP usage and single Web UI host (2026-02-28, PASS)
 - **FU-P11-T2-4** — Add one-command Web UI restart workflow (2026-02-28, PASS)
 - **FU-P11-T2-3** — Reorder sessions from the last to the first (2026-02-28, PASS)
-- **BUG-T9** — Orphaned Web UI server process blocks port after MCP client disconnect or config change (2026-02-25, PASS)
 
 ## Suggested Next Tasks
 

diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -2588,6 +2588,25 @@ Phase 9 Follow-up Backlog
 
 ---
 
+#### ✅ FU-P13-T16: Document multi-agent MCP usage and single Web UI host
+- **Status:** ✅ Completed (2026-02-28, PASS)
+- **Description:** Updated multi-agent documentation to clarify Web UI ownership, explain why MCP can remain healthy while the dashboard is unavailable, and document stable multi-agent topologies for both broker mode and direct mode.
+- **Priority:** P1
+- **Dependencies:** P13-T6, FU-P13-T8, FU-P13-T10
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - Updated `README.md` with explicit multi-agent guidance and Web UI ownership notes
+  - Updated `docs/broker-mode.md` with multi-agent topology details and broker/Web UI behavior notes
+  - Updated `docs/webui-setup.md` with a dedicated multi-agent ownership model section
+  - Updated `docs/troubleshooting.md` with diagnostics for reachable MCP + unreachable dashboard states
+- **Acceptance Criteria:**
+  - [x] Documentation states that only one process can bind a given Web UI `host:port`
+  - [x] Documentation explains why MCP can be healthy while Web UI is unavailable
+  - [x] Documentation provides a dedicated broker host + `--broker-connect` client pattern
+  - [x] Troubleshooting includes concrete checks for listener ownership and port conflicts
+
+---
+
 ### Phase 14: Release 0.4.0 Readiness
 
 #### ✅ P14-T5: Stabilize broker Unix-socket permission test against path-length limits — Completed (2026-02-20, PASS)

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -263,6 +263,36 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex
 
 **Note:** Multiple wrapper processes can run simultaneously on *different* ports. Make sure you identify the PID bound specifically to the port you want, not just any `mcpbridge` process. If the port is immediately re-occupied, close/restart MCP clients (Cursor/Zed/Claude) that may auto-spawn a new wrapper process.
 
+## Error: "MCP tools are green, but dashboard is unreachable"
+
+**Symptom:** Your MCP client reports connected tools, but `http://127.0.0.1:8080` (or your configured Web UI URL) does not open.
+
+**Cause:** MCP bridge and Web UI hosting are related but not identical:
+
+- MCP can stay healthy even if Web UI startup is skipped.
+- Only one process can own a given Web UI `host:port`.
+- In broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`), the dashboard server is not started.
+- A healthy MCP status does not guarantee an active dashboard listener on the expected port.
+
+**Diagnosis:**
+
+```bash
+# 1) Is anything listening on the expected dashboard port?
+PORT=8080
+lsof -nP -iTCP:$PORT -sTCP:LISTEN
+
+# 2) Which wrapper processes are currently alive?
+pgrep -af "xcodemcpwrapper|mcpbridge-wrapper|mcpbridge_wrapper"
+```
+
+If step 1 returns no listener, no process currently owns the dashboard port.
+
+**Solution options:**
+
+1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only.
+2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process.
+3. **Broker mode for multi-agent MCP:** use `--broker-daemon` + `--broker-connect` for clients, and run dashboard diagnostics separately with `--web-ui-only` when needed.
+
 ## Error: "Tool charts are fresh, but Audit Log / Session Timeline look stale"
 
 **Symptom:** Chart widgets (request counts, tool distribution) show new activity, but `/api/audit`

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md b/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md
@@ -37,6 +37,26 @@ xcodemcpwrapper --web-ui --web-ui-port 9090
 xcodemcpwrapper --web-ui --web-ui-config /path/to/webui.json
 ```
 
+### Multi-agent Web UI ownership model
+
+The Web UI dashboard is hosted by the wrapper process that successfully binds the configured `host:port`.
+
+- Only one process can listen on a single `host:port` (for example `127.0.0.1:8080`).
+- If another wrapper process starts with the same Web UI port, MCP can keep working while dashboard startup is skipped for that process.
+- This is expected behavior in multi-agent setups and can look like: tools are available, but `http://127.0.0.1:8080` is unreachable.
+- Ownership is decided at wrapper-process startup by successful port binding.
+
+Recommended patterns:
+
+1. **Single owner (recommended):** enable `--web-ui` for one designated client process only.
+2. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port.
+3. **Shared config for consistency:** if multiple processes may start with Web UI args, use the same `--web-ui-config` so audit log paths stay aligned.
+
+Broker-mode note:
+
+- Broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the dashboard server.
+- Use direct mode with `--web-ui` (or `--web-ui-only` for diagnostics) when dashboard access is required.
+
 ### Enabling via mcp.json
 
 Add `--web-ui` and, optionally, `--web-ui-config` to the `args` array in your MCP client config:

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md
@@ -108,6 +108,21 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-c
 For troubleshooting and rollback details, see <doc:CursorSetup>,
 <doc:ClaudeCodeSetup>, <doc:CodexCLISetup>, and <doc:Troubleshooting>.
 
+#### Multi-Agent Guidance
+
+When you run multiple MCP client processes at the same time:
+
+- **For shared MCP upstream sessions:** run one broker daemon host and configure each client with `--broker-connect`.
+- **For Web UI dashboard hosting:** only one process can bind a given `host:port` (for example `127.0.0.1:8080`).
+- If multiple direct-mode processes start with the same `--web-ui-port`, one process serves the dashboard and other processes continue MCP without dashboard hosting.
+- This ownership rule is process-level and independent from Xcode window state.
+
+Current limitation:
+- Broker CLI modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the Web UI dashboard process.
+- If you need dashboard diagnostics, run a separate direct-mode/Web-UI process (for example `--web-ui-only`) in parallel.
+
+See <doc:WebUIDashboard> and <doc:Troubleshooting>.
+
 ### Python Environment Setup (Development)
 
 If you plan to run development commands such as `make install`, `make test`, or editable installs, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error.
@@ -274,6 +289,10 @@ Features:
 
 Open http://localhost:8080 in your browser to view the dashboard.
 
+Important for multi-agent setups:
+- The dashboard is hosted by one wrapper process, not by Xcode or `mcpbridge`.
+- A single `host:port` can have only one listener; additional processes on the same port skip dashboard startup and continue MCP traffic.
+
 ## Known Issues
 
 - **BUG-T5 → FU-P13-T7 (P0):** Empty-content tool results can still violate strict `structuredContent` expectations in strict MCP clients.

diff --git a/docs/broker-mode.md b/docs/broker-mode.md
@@ -14,6 +14,26 @@ Broker mode lets short-lived MCP client processes share a single long-lived upst
 
 Use broker mode when you want lower process churn across repeated MCP client restarts.
 
+## Multi-agent topology and Web UI ownership
+
+Recommended topology for multiple agents/clients:
+
+1. Start one broker host process with `--broker-daemon`.
+2. Configure every MCP client process with `--broker-connect`.
+3. Keep broker mode focused on MCP transport reuse.
+
+Web UI behavior in broker modes:
+
+- `--broker-daemon`, `--broker-connect`, and `--broker-spawn` paths do not start the Web UI dashboard server.
+- Passing `--web-ui` together with broker flags does not produce a broker-hosted dashboard.
+- If you need dashboard diagnostics while running broker mode, run a separate wrapper process with `--web-ui-only` on a chosen port.
+
+Direct-mode alternative for dashboard-heavy workflows:
+
+- Enable `--web-ui` in direct mode for one designated owner process.
+- Point your browser to that owner's `host:port`.
+- Other direct-mode processes can run without `--web-ui`, or on separate Web UI ports.
+
 ## Paths used by broker mode
 
 By default, broker state is stored in `~/.mcpbridge_wrapper/`:
@@ -107,6 +127,25 @@ rm -f "$PID_FILE" "$SOCK"
 }
 ```
 
+### Zed Agent (`settings.json`)
+
+```json
+{
+  "context_servers": {
+    "xcode-tools": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "mcpbridge-wrapper",
+        "mcpbridge-wrapper",
+        "--broker-connect"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
 ### Claude Code
 
 ```bash