How to Add a Remote MCP Server to Warp

How do I add a remote MCP server to Warp?

Open Settings → Agents → MCP servers, click + Add, and paste a JSON block whose root key is mcpServers. For a server with no static token, that's just a name and a url. Warp handles OAuth-enabled servers with a browser flow that opens when Warp starts the server without stored credentials, and stores the resulting credentials on-device — no header, no token field, nothing else to configure.

The same settings page is reachable from Warp Drive → Personal → MCP Servers, from the Command Palette ("Open MCP Servers"), or from Settings → Agents → Warp Agent → Manage MCP servers, and the same JSON works in a file if you'd rather manage servers that way.

Adding the server

From the UI: Settings → Agents → MCP servers → + Add → paste the config.

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

From a file: the identical JSON works in ~/.warp/.mcp.json for every project, or in .warp/.mcp.json inside a specific project's root for that project only. Project-scoped servers never auto-spawn — Warp requires explicit approval from the MCP servers page before it loads one, which is worth knowing if a project-level entry seems to sit there doing nothing. That approval lasts for the current session, so after restarting Warp you toggle the server on again. Global servers, by contrast, start automatically.

Warp can also pick up MCP configs written for other agents — Claude Code (~/.claude.json, .mcp.json), Codex (~/.codex/config.toml), and ~/.agents/.mcp.json — when Auto-spawn servers from third-party agents is turned on.

A server that takes a static token or header instead of OAuth adds a headers block:

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

Warp also runs local command-based servers (spawned as a subprocess with command, args, and optional env), which is the shape you'll see for filesystem or CLI-wrapped MCP servers rather than remote ones — not the focus here, but the same mcpServers file holds both kinds side by side.

Authorization

If the server supports OAuth, Warp opens the standard browser consent flow when it starts the server without stored credentials. For a global server that is usually right after you save the config, because global servers start automatically; for a project-scoped server, it is when you approve and toggle it on. Approve it in the browser, and Warp stores the credentials on-device. Because storage is per-machine, working across more than one machine means signing in again on each one; that's expected, not a sign of a broken config.

If the server instead expects a static token, put it in headers as shown above rather than waiting for a prompt that will never come.

Managing servers

The MCP servers page lists every configured server with Start and Stop controls, and shows the tools and resources a running server exposes. Click View Logs on a server to diagnose a connection problem — Warp's own docs flag that logs can contain sensitive data, so review before sharing one with anyone else.

Verifying

Start the server from the MCP servers page if it isn't already running, then ask a local agent something that exercises it — for a server with a distinctive tool name, asking the agent to use that tool directly is the fastest check. If it responds with real output instead of saying the tool isn't available, the connection is live.

What usually goes wrong

• The OAuth prompt never appears. Start the server from the MCP servers page (Start) — if no credentials are stored, that opens the sign-in. For a project-scoped server, approve it there first.
• Auth looks stuck or stale. Warp's docs list resetting stored credentials as a fix: remove the local auth cache and reconnect.
• A project-level .warp/.mcp.json isn't loading. Project-scoped servers require explicit approval on the MCP servers page, and the approval lasts only for the current session — after restarting Warp, toggle it on again before assuming the file is wrong.
• A cloud agent can't reach an OAuth server. This is a platform limitation, not a config mistake — see below.
• Connection fails immediately. Check the URL against exactly what the server publishes, including the path and any trailing slash.

The cloud agent gap

Warp's cloud agents are a separate execution path from the local app, and they handle MCP authentication differently. Per Warp's own docs, a direct url server that requires OAuth and has no Authorization header can't be used by cloud agents at all — not a degraded experience, an outright block. The documented workarounds are to run that task with a local agent instead, or to set the server up as a managed MCP installation and reference it by warp_id, which handles the OAuth exchange on Warp's side rather than through a header.

Cloud agents do work with url servers that take a static token or header, and with command servers whose secrets are passed through env — it's specifically the browser-based OAuth path that's unavailable to them today.

A worked example

With a real OAuth-enabled server — Tempreon, a hosted MCP server that carries your context between tools:

{
  "mcpServers": {
    "tempreon": {
      "url": "https://api.tempreon.com/functions/v1/tempreon-mcp/mcp"
    }
  }
}

Add it under Settings → Agents → MCP servers; when Warp starts it without stored credentials, the browser consent screen opens. Then ask a local agent to use it. A local agent is the reliable route for now: a direct url entry hits the cloud agent limitation above, and we haven't confirmed Tempreon works as a managed MCP installation yet. The account-holder walkthrough is in the Warp setup doc.