sync: update from private repo (edc775f2)

docs/mcp.md

@@ -2,8 +2,10 @@
 
 The orchestrator can call tools hosted on external **MCP servers** (OAuth-secured
 SaaS like Canva, or self-hosted servers with static API keys). Connected MCP
-tools are exposed to pieces via `mcp__<server>__<tool>` names, and can be
-allowlisted with `mcp__<server>__*` wildcards in `piece.allowed_tools`.
+tools surface to tasks as `mcp__<server>__<tool>` names. Availability is
+governed by connecting a server to the workspace (per-space), not by any piece
+allowlist — the workspace tool policy always carries the `mcp__*` pattern and
+the aggregator scopes results to the job's space and a valid token.
 
 This document is the **operator runbook** for setting up, troubleshooting, and
 maintaining MCP integrations. For internal design notes, see
@@ -107,29 +109,24 @@ sections — global at top (admin only), user's own below.
 4. If using a private IP, ensure `mcp.allow_private_addresses: true` is set
    (see Prerequisites).
 
-## How tools flow into pieces
+## How tools flow into tasks
 
 The orchestrator caches `tools/list` results in `mcp_server_tools`, refreshed
-on registration and on explicit admin refresh (no automatic TTL today). Piece
-authors expose them via `allowed_tools`:
+on registration and on explicit admin refresh (no automatic TTL today). There
+is no per-piece allowlist: the workspace tool policy always carries the
+`mcp__*` pattern, so every tool from a server connected to the job's space is
+offered automatically. The aggregator scopes results to that space and a valid
+token, so a task only ever sees tools from servers connected to its own
+workspace.
 
-```yaml
-movements:
-  - name: design
-    allowed_tools:
-      - Read
-      - Write
-      - mcp__canva__*           # all tools from server `canva`
-      - mcp__my-tools__lint     # a specific tool from `my-tools`
-```
-
-The wildcard `mcp__<server>__*` expands to all currently-cached tools for that
-server.
+To expose a server's tools, connect the server to the workspace (**Settings →
+MCP**). To *require* one, list it in the piece's `required_mcp` frontmatter —
+that only controls job parking when no connection exists (see below).
 
 ## Job parking and resume
 
-When a piece requires an MCP server (via `required_mcp` frontmatter or
-discovered from `allowed_tools`) and the user has no connection, the worker
+When a piece requires an MCP server (via `required_mcp` frontmatter) and the
+user has no connection, the worker
 parks the job:
 
 - `jobs.status = 'waiting_human'`