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 runs the first time an agent actually uses the server, 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, 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.

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 triggers the standard browser consent flow the first time a local agent actually calls it — not when you save the config. 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. It fires on first use, not on save — ask the agent to do something that calls the server before assuming the flow is broken.
• 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 — check there 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, start it, and ask a local agent to use it — the first call opens the browser consent screen. This only works with a local agent; a Warp cloud agent hits the OAuth limitation above. The account-holder walkthrough is in the Warp setup doc.