diff --git a/.warp/references/settings-schema.json b/.warp/references/settings-schema.json index fb2c719..a72e32f 100644 --- a/.warp/references/settings-schema.json +++ b/.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" } }, diff --git a/src/content/docs/agent-platform/capabilities/mcp.mdx b/src/content/docs/agent-platform/capabilities/mcp.mdx index fb1f827..5a58d89 100644 --- a/src/content/docs/agent-platform/capabilities/mcp.mdx +++ b/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. diff --git a/src/content/docs/terminal/settings/all-settings.mdx b/src/content/docs/terminal/settings/all-settings.mdx index 2939c7c..b8bdbbf 100644 --- a/src/content/docs/terminal/settings/all-settings.mdx +++ b/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)