From 43ac4c3d19ef90fbc5c18071665a13037f96bb5d Mon Sep 17 00:00:00 2001 From: Varoon Kodithala Date: Fri, 1 May 2026 01:32:19 +0000 Subject: [PATCH 1/2] Update file-based MCP server docs Co-Authored-By: Oz --- .warp/references/settings-schema.json | 2 +- .../docs/agent-platform/capabilities/mcp.mdx | 39 ++++++++++++++----- .../docs/terminal/settings/all-settings.mdx | 2 +- 3 files changed, 32 insertions(+), 11 deletions(-) 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..b40f26b 100644 --- a/src/content/docs/agent-platform/capabilities/mcp.mdx +++ b/src/content/docs/agent-platform/capabilities/mcp.mdx @@ -95,26 +95,47 @@ 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) -* **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). +When this setting is enabled: + +* **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. + +Warp recognizes MCP servers under the `mcpServers`, `servers`, `mcp.servers`, and `mcp_servers` wrapper keys in JSON config files. Codex configs are read from TOML under `mcp_servers`. + +#### Suggested demos + +Add short demos for these flows: + +* Using `/add-mcp-server` to create a global Warp MCP server, then restarting Warp to show it auto-spawns by default. +* Enabling **Auto-spawn servers from third-party agents** and showing a global Claude Code or Codex MCP server start automatically. +* Opening a cloned repo with a project-scoped MCP config and showing that the server appears under the relevant **Detected from** section but must be toggled on manually after each restart. + ### 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) From 7dcca0b6527959abda176355f01c99395a573d48 Mon Sep 17 00:00:00 2001 From: vkodithala Date: Fri, 1 May 2026 09:26:33 -0400 Subject: [PATCH 2/2] fix: Remove 'suggested demos' section --- src/content/docs/agent-platform/capabilities/mcp.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/content/docs/agent-platform/capabilities/mcp.mdx b/src/content/docs/agent-platform/capabilities/mcp.mdx index b40f26b..5a58d89 100644 --- a/src/content/docs/agent-platform/capabilities/mcp.mdx +++ b/src/content/docs/agent-platform/capabilities/mcp.mdx @@ -126,16 +126,6 @@ Supported providers: * **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. -Warp recognizes MCP servers under the `mcpServers`, `servers`, `mcp.servers`, and `mcp_servers` wrapper keys in JSON config files. Codex configs are read from TOML under `mcp_servers`. - -#### Suggested demos - -Add short demos for these flows: - -* Using `/add-mcp-server` to create a global Warp MCP server, then restarting Warp to show it auto-spawns by default. -* Enabling **Auto-spawn servers from third-party agents** and showing a global Claude Code or Codex MCP server start automatically. -* Opening a cloned repo with a project-scoped MCP config and showing that the server appears under the relevant **Detected from** section but must be toggled on manually after each restart. - ### 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.