# Workspace MCP 预算控制

> 按服务名预留名额，理解滞回警告、批量拒绝和不同管理路径。

- 网址：https://funcoding.ai/agents/qwen-code/runtime/mcp-budget/
- 核实日期：2026-10-08（命令、配置和价格以官方文档为准）
- 官方来源：[Qwen Code 官方文档：MCP Budget Guardrails](https://github.com/QwenLM/qwen-code/blob/main/docs/developers/daemon/06-mcp-budget-guardrails.md)、[Qwen Code 官方文档：MCP Transport Pool](https://github.com/QwenLM/qwen-code/blob/main/docs/developers/daemon/05-mcp-transport-pool.md)

---
WorkspaceMcpBudget 在一个 workspace pool 内统一管理 reservation。它限制配置服务名的名额，不直接限制每个 fingerprint 的连接数或全部本机子进程数量。

## 预算模式

| 模式 | 预留与事件 |
| --- | --- |
| off | 不实施预算跟踪和事件限制 |
| warn | 跟踪预留，在阈值处警告；controller 的 tryReserve 不拒绝 |
| enforce | 名额已满时拒绝新服务名，并记录 refusal |

--mcp-client-budget 提供正预算；--mcp-budget-mode=enforce 缺少正预算会启动失败。两者通过 childEnvOverrides 的 QWEN_SERVE_MCP_CLIENT_BUDGET、QWEN_SERVE_MCP_BUDGET_MODE 传入 child。

这描述预算 controller。动态添加路由还有独立预检，warn 超预算也可能返回 skipped:budget_warning_only；不能把 controller 的“从不拒绝”外推为所有 HTTP 操作都一定连接。见[动态 MCP](https://funcoding.ai/agents/qwen-code/daemon/runtime-mcp/)。

## 服务名与进程数

同名但不同 fingerprint 的 entry 共用一个 reservation。只有同名其他 entry 与仍在 spawn 的 sibling 都不存在时，关闭才释放该名额；启动失败也要回滚相应 reservation。

reservation 包含正在连接的服务，并跨暂时断开保留。它与 CONNECTED liveCount 不相等；subprocessCount 又只计 stdio。仪表盘应分别展示，不能把 budget 当硬 OS 进程上限。

tryReserve 是同步操作，名额检查与登记之间不 await，避免两个不同名字的并发 acquire 同时穿过剩余一个名额。

## 警告滞回

预留数/预算达到 75% 时发一次 mcp_budget_warning；之后必须降到严格低于 37.5% 才重新准备下一次警告。围绕 75% 上下波动不会不断重复告警。

阈值使用 reservation count，不使用瞬时 connected 数，这使重连期间的告警更稳定。

## 批量拒绝与快照

beginBulkPass/endBulkPass 将一轮 discovery 的拒绝合并成 mcp_child_refused_batch。嵌套 pass 只在最外层结束时发送；不在 pass 内的懒加载拒绝立即发长度为 1 的同形状 batch。

lastRefusedServerNames 在下一轮最外层 pass 开始时清空，而不是上轮发出事件后立即清空，因此两轮之间的 GET /workspace/mcp 仍能看到最近拒绝名单。

workspace 事件带 scope:workspace，可能广播给多个附着 session。多个 UI 观察到同一事件不代表发生了多次独立拒绝。

## Pool 与 legacy 路径

pool 内使用 WorkspaceMcpBudget；独立 CLI/SDK 或关闭 pool 后由 McpClientManager 的会话预算逻辑接管。QWEN_SERVE_NO_MCP_POOL=1 同时使 mcp_workspace_pool、mcp_pool_restart capability 消失，不能继续按工作区总预算理解结果。

状态用 budgets[]，scope 可为 workspace 或 session。未知 scope 应忽略而非使整个快照解析失败。budget 与 mode 在 controller 建立后固定，改变它们需重建 pool。