Warp

Warp uses a flat JSON format for MCP — no `mcpServers` wrapper. Add servers via Settings, the `--mcp` CLI flag, or a config file.

OVERVIEW

Warp is an AI-powered terminal that supports MCP servers for agent capabilities. The JSON format is flat: each server is a top-level key (not nested under `mcpServers`). You can pass configs via Settings → Agents → MCP Servers, inline JSON with `oz agent run --mcp '{...}'`, or a file path with `oz agent run --mcp ./file.json`.

CONFIG FILE LOCATION

Add via Settings → Agents → MCP Servers in the Warp UI. Or save to a JSON file and pass it with `--mcp ./mcp-config.json`.

PREREQUISITES

Warp terminal installed from warp.dev.
An active Zephex account and API key.
Node.js 18+ so `npx` is available on PATH.

CONFIG

Important: Warp uses a flat format. Server names are top-level keys — do NOT wrap them in a `mcpServers` object.

Replace `mcp_sk_your_key_here` with the real key from Dashboard → API Keys.

{  "zephex": {    "command": "npx",    "args": ["-y", "zephex"],    "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" }  }}

OZ CLI USAGE

Pass the MCP server to an agent run via the Oz CLI:

Inline: `oz agent run --mcp '{"zephex": {"command": "npx", "args": ["-y", "zephex"], "env": {"ZEPHEX_API_KEY": "mcp_sk_..."}}}' --prompt "your task"`
From file: `oz agent run --mcp ./mcp-config.json --prompt "your task"`
Combine multiple: repeat `--mcp` for each server.
List configured servers: `oz mcp list`.

VERIFY

Confirm the server is connected before running tasks.

In Settings → Agents → MCP Servers, check that Zephex shows as active.
Or run `oz mcp list` to see all configured servers.
Run an agent and ask it to use a Zephex tool.

COMMON ISSUES

Server not connecting

Warp uses a flat JSON format. If you wrapped servers in `mcpServers`, remove the wrapper. Each server name must be a top-level key.

Environment variables missing on remote machines

Warp syncs MCP config between machines but does NOT sync env vars. Set `ZEPHEX_API_KEY` manually on remote hosts, or use Oz-managed secrets.

Command not found

Warp inherits your shell PATH. Run `which npx` in a Warp terminal to verify. If using nvm, ensure the correct Node version is active.

Invalid JSON error

When passing inline JSON with `--mcp`, ensure proper shell escaping. Single-quote the outer string and use double quotes inside.

If the editor still does not connect, return to Quickstart or check Connection Issues.