Skip to main content
Model Context Protocol (MCP) is an open standard that lets AI applications connect to external tools and data sources through a consistent interface. In Warp, MCP servers extend the AI agent’s built-in capabilities: once a server is connected, the agent can call its tools automatically whenever they are relevant to your prompt — no manual copy-pasting of API responses required. Common uses include querying a database, fetching GitHub pull request details, running browser automation, searching internal documentation, and calling any REST or GraphQL API.

​
How MCP servers work in Warp

When an MCP server is running, it registers a set of tools with the agent. The agent sees these tools alongside its built-in tools (run command, read file, etc.) and decides when to call them based on your prompt. Results are returned to the agent as context for its next step. Warp supports two transport types:
TransportHow it works
stdioWarp spawns a local process and communicates over stdin/stdout. Best for servers distributed as npm packages or executables.
HTTP (streamable)Warp connects to a running HTTP server over a URL. Best for remote or OAuth-authenticated servers.

​
Adding MCP servers in settings

The simplest way to add an MCP server is through Warp’s settings UI.
1

Open MCP settings

Go to Settings → AI → MCP Servers.
2

Add a server

Click Add MCP server. You can paste a JSON snippet for a stdio server, enter an HTTP URL for a remote server, or pick from the MCP gallery.
3

Configure variables

Some servers require environment variables (API keys, URLs, etc.). Warp will prompt you to fill in any required variables before activating the server.
4

Verify the connection

Once added, the server appears in the MCP servers list with a status indicator. A green dot means the server is running and its tools are available to the agent.
MCP servers you add in settings are available in all Agent Mode sessions, regardless of which repository you have open. Use file-based MCP configuration (see below) when you want a server scoped to a specific project.

​
File-based MCP configuration

Warp watches for MCP configuration files in your repository roots and home directory. When it finds one, it activates the servers defined in that file automatically — no settings UI required. This makes it easy to commit MCP configuration alongside your code so every contributor gets the same tools. The file-based MCP feature (FileBasedMcp) must be enabled in your Warp account. When it is, Warp watches the following paths:
ProviderHome config pathProject config path
Warp~/.warp/.mcp.json.warp/.mcp.json
Claude~/.claude.json.mcp.json
Codex~/.codex/config.toml.codex/config.toml
Other agents~/.agents/.mcp.json.agents/.mcp.json
Warp re-reads these files whenever they change, so you can add or remove servers by editing the file directly.

​
Example .mcp.json

The repository root of the Warp client itself includes an .mcp.json that registers the official GitHub MCP server: 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ]
    }
  }
}
Save this file as .mcp.json in the root of your repository. Warp will pick it up the next time you open that project.

​
stdio server format

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./scripts/mcp-server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}
Use ${VARIABLE_NAME} syntax to forward environment variables from your shell to the server process without hard-coding secrets in the file.

​
HTTP server format

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
The MCP gallery is a curated list of popular MCP servers you can add to Warp with a single click. Open it from Settings → AI → MCP Servers → Browse gallery. The gallery includes servers for common tools like GitHub, Linear, Slack, Postgres, and browser automation. Each gallery entry includes a description of the tools it provides, installation requirements, and any variables you need to configure.

​
OAuth-authenticated MCP servers

Some MCP servers use OAuth to authenticate with third-party services (for example, a server that calls the GitHub API on your behalf). When the McpOauth feature is enabled, Warp handles the OAuth flow for you:
  1. When you add an OAuth MCP server, Warp opens a browser window to the provider’s authorization page.
  2. You grant the requested permissions.
  3. Warp stores the resulting token securely and injects it into the MCP connection automatically.
OAuth tokens are refreshed in the background. You will only be prompted to re-authorize if the token expires or the server’s required scopes change.

​
Managing MCP servers with oz mcp

The oz mcp CLI commands let you list and manage MCP servers without opening the settings UI. 
# List all configured MCP servers
oz mcp list

# Show details for a specific server
oz mcp get <server_name>

# Remove an MCP server
oz mcp remove <server_name>
Use oz mcp list --output-format json to get machine-readable output for scripting or CI pipelines.

​
Debugging MCP servers

If a server fails to start or its tools are not appearing, check the MCP server logs:
  • In the settings UI, click the server name and open the Logs tab.
  • From the CLI: oz mcp logs <server_name>
Common issues include missing environment variables, an incompatible Node.js version, or a network error when connecting to a remote URL.

​
Next steps

Skills

Package reusable prompt instructions that work alongside MCP tools.

Rules

Define project-level rules to guide how the agent uses its tools.

Agent Mode

Learn how to send prompts and review diffs in Agent Mode.

oz mcp reference

Full CLI reference for the oz mcp command group.

Build docs developers (and LLMs) love

Get started for freeTalk to us