Add a Remote MCP Server to Warp: Settings, OAuth and Fixes

Open Settings > Agents > MCP servers, click + Add, choose Streamable HTTP or SSE Server (URL), and paste the server as JSON [1]:

{
  "my-server": {
    "url": "https://mcp.example.com/mcp"
  }
}

Warp connects to a server that is already running at that address; it starts nothing on your machine [1]. Most clients' configurations can be pasted in as they are, mcpServers wrapper included [1].

Everything below is checked against Warp's documentation on 2 November 2026 [1].

TL;DR:

• A remote entry is url plus optional headers. There is no type field to get wrong [1].
• OAuth opens your browser the first time a server starts without saved credentials. Credentials stay on that device [1].
• Servers you leave running start again the next time you open Warp; stopped ones stay stopped [1].
• Every server has View Logs, which is where a failed connection explains itself [1].

Four ways to the MCP servers page

All open the same list [1]:

• Settings > Agents > MCP servers
• Warp Drive > Personal > MCP Servers
• The Command Palette: search for "Open MCP Servers"
• Settings > Agents > Warp Agent > Manage MCP servers

The fields a remote entry takes

Several servers at once, in the shape other clients use [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

The URL is the MCP endpoint itself, usually ending in /mcp (older servers use /sse), not the product's homepage or its docs page. env and working_directory belong to command servers only, not to URL servers [1].

Sign in to a server that needs it

Start a server that has no saved credentials and Warp opens a browser window for its sign-in [1]. Credentials are stored on your device and reused in later sessions, so on a new machine you sign in again [1]. You can revoke them from the MCP servers page [1].

A server that takes an API key instead gets it in headers, as Authorization: Bearer ... [1]. MCP OAuth covers what a server has to publish for the browser sign-in to work.

Servers from files and from other agents

Warp also reads servers from files [1]:

So a server you already set up in Claude Code or Codex can show up in Warp without adding it twice [1]. Edits to these files from inside Warp also ask for your approval [1].

Share a server with your team

The share icon on a server puts it in Warp Drive, where teammates find it under Shared [1]. Sensitive values in env are replaced with variables that each teammate fills in [1]. The documentation describes that scrubbing for env only, not for headers [1], so take a token out of a URL server's headers before you share it.

When it will not connect

Warp's documentation points out that logs may contain API keys, so clean them before you paste them anywhere [1]. The log folders are ~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/mcp on macOS, $env:LOCALAPPDATA\warp\Warp\data\logs\mcp on Windows, and ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp on Linux [1].

For what the server's own error codes mean, see MCP server errors and MCP server connection failed.

Check it from outside before you share it

Warp connects from your own machine, so a server on localhost or your VPN works for you and for nobody else. Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it passes there and fails in Warp, the problem is in your configuration, not the server.

The same setup in other clients is in OpenCode, Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Cursor, VS Code, LibreChat, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.

Sources

1. Model Context Protocol, Warp docs