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/public/assets/agent-platform/file-based-mcp-demo.mp4 b/public/assets/agent-platform/file-based-mcp-demo.mp4 new file mode 100644 index 0000000..f86200d Binary files /dev/null and b/public/assets/agent-platform/file-based-mcp-demo.mp4 differ diff --git a/public/assets/agent-platform/file-based-mcp-demo.poster.jpg b/public/assets/agent-platform/file-based-mcp-demo.poster.jpg new file mode 100644 index 0000000..a7feca6 Binary files /dev/null and b/public/assets/agent-platform/file-based-mcp-demo.poster.jpg differ diff --git a/public/assets/agent-platform/file-based-mcp-setting.png b/public/assets/agent-platform/file-based-mcp-setting.png new file mode 100644 index 0000000..c23a01d Binary files /dev/null and b/public/assets/agent-platform/file-based-mcp-setting.png differ diff --git a/public/assets/agent-platform/file-based-mcp-toggle.gif b/public/assets/agent-platform/file-based-mcp-toggle.gif deleted file mode 100644 index 0c05571..0000000 Binary files a/public/assets/agent-platform/file-based-mcp-toggle.gif and /dev/null differ diff --git a/src/content/docs/agent-platform/capabilities/mcp.mdx b/src/content/docs/agent-platform/capabilities/mcp.mdx index fb1f827..ef986fa 100644 --- a/src/content/docs/agent-platform/capabilities/mcp.mdx +++ b/src/content/docs/agent-platform/capabilities/mcp.mdx @@ -5,6 +5,7 @@ description: >- custom tools and data sources through a standardized interface. --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +import DemoVideo from '@components/DemoVideo.astro'; MCP servers extend Warp's [local agents](/agent-platform/local-agents/interacting-with-agents/) in a modular, flexible way by exposing custom tools or data sources through a standardized interface — essentially acting as plugins for Warp. Warp supports a variety of connection protocols, including Streamable HTTPS and SSE, along with custom headers and environment variables. @@ -95,21 +96,49 @@ 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 manually configured servers. Compared to manually adding a server in **Settings**, file-based MCP servers offer a few additional benefits: -To enable, go to **Settings** > **Agents** > **MCP servers** and toggle **File-based MCP Servers** on. +* **Configurable directly with an agent** - Use the [bundled skill](#using-agent-add-mcp) `/agent-add-mcp` to allow Warp's agent to add or update an MCP server without leaving the conversation. +* **Inherited across providers and repos** - Warp reads the same `.warp/.mcp.json` file used by Warp-managed servers, and also picks up file-based configuration from third-party agent providers (Claude Code, Codex, and others) and from cloned repos, so the same server definition can follow you across tools. -![File-based MCP Servers toggle](/assets/agent-platform/file-based-mcp-toggle.gif) +#### Supported providers -When enabled: +Warp reads MCP server definitions from the following providers: -* **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. +| Provider | Global config | Project-scoped config | Auto-spawn behavior | +| -------- | ------------- | --------------------- | ------------------- | +| Warp | `~/.warp/.mcp.json` | `.warp/.mcp.json` at project root | Global servers auto-spawn by default. Project-scoped servers require explicit approval. | +| Claude Code | `~/.claude.json` | `.mcp.json` at project root | Global servers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. Project-scoped servers require explicit approval. | +| Codex | `~/.codex/config.toml` | `.codex/config.toml` at project root | Global servers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. Project-scoped servers require explicit approval. | +| Other agents | `~/.agents/.mcp.json` | `.agents/.mcp.json` at project root | Global servers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. Project-scoped servers require explicit approval. | -Supported providers: +For provider-specific setup, see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp#user-scope) and [Codex MCP docs](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server). -* **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). +#### Auto-spawn behavior + +Auto-spawn controls whether Warp starts detected file-based MCP servers without requiring you to start each server manually. Global Warp servers auto-spawn by default. To auto-spawn supported global servers from third-party agents, go to **Settings** > **Agents** > **MCP servers** > **Auto-spawn** and toggle **Auto-spawn servers from third-party agents** on. + +![Toggle to auto-spawn global file-based MCP servers](/assets/agent-platform/file-based-mcp-setting.png) + +Project-scoped servers from any provider must be toggled on individually from the MCP servers page. Project-scoped servers started from the MCP servers page are session-scoped. After restarting Warp, toggle the server on again if you still trust the repo and want to use those tools. + +#### Using `/agent-add-mcp` + +Use the built-in `/agent-add-mcp` skill to allow Warp's agent to create or update Warp-managed file-based MCP configuration. The skill helps you choose whether to save the server globally or in the current project, then writes the server definition to the matching file: + +* **Global:** `~/.warp/.mcp.json` +* **Project-scoped:** `{repo_root}/.warp/.mcp.json` + + + +The demo shows how to use `/agent-add-mcp` to allow Warp's agent to add an MCP server, choose where Warp saves the file-based configuration, and review the generated `.warp/.mcp.json` file before using the server. + +#### Security mitigations + +MCP config files can start local commands and send data to external tools. Warp adds approval gates around file-based MCP servers to reduce the risk of untrusted config changes: + +* **Config edits require approval** - Warp prevents edits to MCP config files unless you explicitly approve the change. This keeps an agent or automation from silently adding a server that can run commands or access data. +* **Project-scoped servers never auto-spawn** - Warp detects project-scoped MCP config files in cloned repos, but requires you to start each server manually. This prevents a cloned repo from automatically starting an MCP server that runs arbitrary local commands. :::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. 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)