> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# Extend Warp with MCP servers

> Connect Model Context Protocol servers to give Warp's AI agent new tools — database queries, GitHub APIs, browser automation, and more.

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:

| Transport             | How it works                                                                                                                 |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **stdio**             | Warp 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.

<Steps>
  <Step title="Open MCP settings">
    Go to **Settings → AI → MCP Servers**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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:

| Provider         | Home config path       | Project 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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

## The MCP gallery

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.

```bash theme={null}
# 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>
```

<Tip>
  Use `oz mcp list --output-format json` to get machine-readable output for scripting or CI pipelines.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Skills" icon="book-open" href="/agent/skills">
    Package reusable prompt instructions that work alongside MCP tools.
  </Card>

  <Card title="Rules" icon="shield" href="/agent/rules">
    Define project-level rules to guide how the agent uses its tools.
  </Card>

  <Card title="Agent Mode" icon="robot" href="/agent/agent-mode">
    Learn how to send prompts and review diffs in Agent Mode.
  </Card>

  <Card title="oz mcp reference" icon="code" href="/cli/mcp">
    Full CLI reference for the oz mcp command group.
  </Card>
</CardGroup>