Update file-based MCP server docs

.warp/references/settings-schema.json

@@ -1462,7 +1462,7 @@
           "properties": {
             "file_based_mcp_enabled": {
               "default": false,
-              "description": "Whether third-party file-based MCP servers are automatically detected.",
+              "description": "Whether global file-based MCP servers from third-party agents are automatically spawned. Warp-managed global MCP servers auto-spawn regardless of this setting, and project-scoped servers must be started manually.",
               "type": "boolean"
             }
           },

src/content/docs/agent-platform/capabilities/mcp.mdx

@@ -95,26 +95,37 @@ To add a multiple MCP servers, you can click the **+ Add** button then paste in
 
 ### File-based MCP servers
 
-Warp detects MCP server configurations managed by supported third-party agents and can automatically spawn them alongside your manually configured servers.
+Warp detects MCP server configurations saved in supported config files and can spawn them alongside your manually configured servers.
 
-To enable, go to **Settings** > **Agents** > **MCP servers** and toggle **File-based MCP Servers** on.
+Warp-managed file-based servers use `.warp/.mcp.json` files. The built-in `/add-mcp-server` skill can help create or update these files for you:
 
-![File-based MCP Servers toggle](/assets/agent-platform/file-based-mcp-toggle.gif)
+* **Global:** `~/.warp/.mcp.json`
+* **Project-scoped:** `{repo_root}/.warp/.mcp.json`
 
-When enabled:
+Global Warp servers are detected and auto-spawned by default, even if the third-party auto-spawn setting is off.
 
-* **Global/user-scoped servers** - spawned on Warp startup and available in any session.
-* **Project-scoped servers** - spawned when you enter a repo containing a supported config file, and available within that project only.
+To auto-spawn supported global servers from third-party agents, go to **Settings** > **Agents** > **MCP servers** and toggle **Auto-spawn servers from third-party agents** on.
 
-Supported providers:
+![File-based MCP Servers toggle](/assets/agent-platform/file-based-mcp-toggle.gif)
+
+When this setting is enabled:
 
-* **Claude Code** - reads user-scoped config (`~/.claude.json`) and project-scoped config (`.mcp.json` at project root). See [user scope](https://code.claude.com/docs/en/mcp#user-scope) and [project scope](https://code.claude.com/docs/en/mcp#project-scope) in the Claude Code docs.
-* **Codex** - reads global config (`~/.codex/config.toml`) and project-scoped config (`.codex/config.toml` at project root). See [Codex MCP docs](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server).
+* **Global third-party servers** are spawned on Warp startup and available in any session.
+* **Project-scoped servers** are detected when you enter a repo containing a supported config file, but are not spawned automatically.
+
+Project-scoped servers from any provider, including Warp, must be toggled on individually from the MCP servers page. This is intentional: cloned repositories can contain MCP config files that run arbitrary commands, so Warp never starts project-scoped file-based servers automatically. Project-scoped servers started from the MCP servers page are session-scoped; after restarting Warp, toggle them on again if you still trust the repo and want to use those tools.
 
 :::note
 File-based servers that require OAuth show an authentication modal on their first spawn. Credentials are saved for future spawns, the same as manually configured MCP servers.
 :::
 
+Supported providers:
+
+* **Warp** - reads global config (`~/.warp/.mcp.json`) and project-scoped config (`.warp/.mcp.json` at project root). Global Warp servers auto-spawn by default. Use `/add-mcp-server` in Agent Mode to add or update Warp-managed MCP config files.
+* **Claude Code** - reads user-scoped config (`~/.claude.json`) and project-scoped config (`.mcp.json` at project root). Global Claude Code servers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. See [user scope](https://code.claude.com/docs/en/mcp#user-scope) and [project scope](https://code.claude.com/docs/en/mcp#project-scope) in the Claude Code docs.
+* **Codex** - reads global config (`~/.codex/config.toml`) and project-scoped config (`.codex/config.toml` at project root). Global Codex servers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. See [Codex MCP docs](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server).
+* **Other agents** - reads global config (`~/.agents/.mcp.json`) and project-scoped config (`.agents/.mcp.json` at project root). Global servers from this provider auto-spawn only when **Auto-spawn servers from third-party agents** is enabled.
+
 ### Managing MCP servers
 
 After MCP servers are registered in Warp, you can **Start** or **Stop** them from the MCP servers page. Each running server will have a list of available tools and resources.

src/content/docs/terminal/settings/all-settings.mdx

@@ -267,7 +267,7 @@ Settings for Warp's agents, including model behavior, permissions, knowledge, MC
 
 **Section**: `[agents.mcp_servers]`
 
-* `file_based_mcp_enabled` — Whether third-party file-based MCP servers are automatically detected. Type: boolean. Default: `false`.
+* `file_based_mcp_enabled` — Whether global file-based MCP servers from third-party agents are automatically spawned. Warp-managed global MCP servers auto-spawn regardless of this setting, and project-scoped servers must be started manually. Type: boolean. Default: `false`.
 
 ### Profiles (permissions)