Warp Terminal MCP Server Setup 2026: Agent Mode Configuration

Key Takeaways

Where Warp's MCP config lives

Warp keeps its own MCP configuration separate from any other tool's, so it can run its own server set even if you also use Claude Code or Codex CLI in the same terminal:

You can edit either file directly, or go through the UI: Settings → Agents → MCP servers, or open the command palette and search "Open MCP Servers." The Warp Drive path (Warp Drive → Personal → MCP Servers) reaches the same underlying list.

The two server shapes

CLI server (Warp launches it):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {}
    }
  }
}

command and args are required. Warp starts the process when the agent needs it and shuts it down when you're done — you don't manage the process lifecycle yourself.

Streamable HTTP/SSE server (already running somewhere):

{
  "mcpServers": {
    "hosted-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

For a url-based server, Warp connects to an endpoint that's already up — it doesn't spawn anything locally. headers is where a bearer token or API key goes for authenticated remote servers.

Step 1: Add your first server through the UI

Open the command palette (cmd-shift-p on macOS) and run "Open MCP Servers," then click + Add. You can either fill in the individual fields (name, command, args) or paste a raw JSON snippet if you're adding more than one server at once — pasting is faster if you already have a working config from Claude Desktop or another client, since the mcpServers object format is shared.

Step 2: Or edit .mcp.json directly

For version-controlled, team-shared setups, editing the project file directly is more predictable than the UI:

mkdir -p .warp

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost/myapp_development"
      }
    }
  }
}

Warp picks up changes to this file automatically — no restart required for most edits, though if a server seems stuck, toggling it off and on from the MCP servers page forces a clean reconnect.

Step 3: Let Warp auto-discover configs from other tools

If you already run Claude Code or OpenAI's Codex CLI in the same project, Warp looks for their configs too:

This means a server you set up once for Claude Code shows up as an available (but not auto-started) option in Warp. You have to explicitly toggle auto-spawn on for discovered servers — Warp doesn't silently start a process a different tool defined, and project-scoped discovered servers ask for approval on first use each session as a safety check against a malicious repo shipping a .mcp.json that runs something you didn't expect.

Step 4: Verify the server connected

From the MCP servers page, a connected server shows its available tools listed underneath its name. In an Agent Mode conversation, ask something that requires the new server:

List the files in the current project using the filesystem MCP server.

If the agent calls the tool and returns real output, the connection is live.

Authentication options

Warp supports three ways to get credentials into a server:

1. Environment variables — the env block on a CLI server, same as any other MCP client.
2. OAuth — for servers that support it (Figma is one example), Warp opens a browser for one-click login and stores the resulting credential locally.
3. Custom headers — for url-based servers, headers.Authorization carries a bearer token or API key.

Troubleshooting Warp MCP connections

Server shows as disconnected or won't start

Click View Logs on that server from the MCP servers page. On macOS, logs also live under ~/Library/Group Containers/.../mcp if you need to grep them directly. Warp's own docs flag that these logs can contain API keys, so don't paste raw log output into a public bug report or chat without redacting.

If the log shows the process exiting immediately, run the exact command and args by hand in your regular terminal first:

npx -y @modelcontextprotocol/server-filesystem /tmp

If it errors there, it will error identically inside Warp — fix the standalone invocation before assuming Warp is the problem.

Auth keeps failing after it worked once

OAuth tokens and stored credentials for MCP servers live under ~/.mcp-auth. If a token got corrupted or the server rotated its signing key, wipe it and re-authenticate:

rm -rf ~/.mcp-auth

Then reconnect the server from the MCP servers page — you'll be prompted through the OAuth flow again.

A discovered server from Claude Code or Codex isn't showing up

Auto-discovery only surfaces servers Warp can find at the documented paths (~/.claude.json, .mcp.json, ~/.codex/config.toml, .codex/config.toml). If your Claude Code config lives somewhere nonstandard, or the project file is in a parent directory Warp isn't scanning, it won't appear — copy the mcpServers block into .warp/.mcp.json directly rather than relying on discovery.

The agent doesn't use a connected server's tools

This isn't always a connection problem. Warp's own guidance notes that some models are more reliable at picking MCP tools than others for a given prompt — if a tool call should obviously fire and doesn't, try rephrasing the request to name the tool or server explicitly, or switch models for that conversation.

Project-scoped server keeps asking for approval every session

That's expected behavior, not a bug — project-scoped servers discovered from a repo's config require per-session approval by design, since anyone with write access to the repo could otherwise get a command executed on your machine without you seeing it first. If you trust the repo and want to stop the prompt, promote the server into your global ~/.warp/.mcp.json instead of relying on discovery.

Frequently Asked Questions

Q: Can I use the same mcpServers JSON I already wrote for Claude Desktop or Cursor?
A: Yes — the object shape (command/args/env for local servers) is shared across clients. Paste it into .warp/.mcp.json or use the "paste JSON" option in the Add Server UI.

Q: Does Warp manage the lifecycle of a url-based remote server?
A: No. url/httpUrl servers are assumed to already be running somewhere (locally or hosted) — Warp only connects to them. Only command-based CLI servers get started and stopped by Warp itself.

Q: Why does a server I set up in Claude Code show up in Warp but not run automatically?
A: Auto-discovered servers default to not auto-spawning. You have to explicitly enable auto-spawn for a discovered server, which is Warp's way of not silently running a process another tool's config defined without your consent.

Q: Where do I look first when a server that used to work suddenly stops authenticating?
A: Check ~/.mcp-auth for a stale or corrupted token — rm -rf ~/.mcp-auth and reconnecting through the MCP servers page usually resolves it if the server uses OAuth.

Q: Is it safe to share my project's .warp/.mcp.json with teammates?
A: Warp's team sharing feature auto-scrubs sensitive env values when you share a server config, but always double-check before committing .warp/.mcp.json to a shared repo — a hardcoded token in env rather than a reference to an environment variable will leak.

Related Guides