MCP servers (CLI reference)

Caution

The Oz CLI (the oz binary) is being deprecated in favor of the Warp Agent CLI (the warp binary). See the Warp Agent CLI docs for the replacement.

MCP servers connect agents to external systems like GitHub, Linear, or Sentry. To use a Model Context Protocol (MCP) server from the CLI, use the --mcp flag with oz agent run or oz agent run-cloud.

For help choosing between local, cloud, and shared MCP workflows, see Connect developer tools to agents with MCP workflows. For a conceptual overview of MCP with cloud agents — including configuration schema, full agent config examples, and limitations — see MCP Servers in the Cloud Agents docs.

---

Using the --mcp flag

The --mcp flag accepts four formats:

• UUID — reference a Warp-shared MCP server by its UUID (find UUIDs with oz mcp list)
• Well-known id — a short identifier like linear, resolved server-side against a set of managed MCP servers
• Inline JSON — pass a full MCP JSON configuration directly as a string
• File path — path to a JSON file containing the MCP configuration

You can repeat --mcp to include multiple servers.

Passing MCP servers by UUID

1. Locate the MCP server UUID using oz mcp list. This command lists all MCP servers configured in your Warp account, including team-shared ones:

$ oz mcp list
+--------------------------------------+--------+
| UUID                                 | Name   |
+===============================================+
| 1deb1b14-b6e5-4996-ae99-233b7555d2d0 | github |
|--------------------------------------+--------|
| 65450c32-9eb1-4c57-8804-0861737acbc4 | linear |
|--------------------------------------+--------|
| d94ade64-0e73-47a6-b3ee-14e5afec3d90 | Sentry |
+--------------------------------------+--------+

Alternatively, copy the UUID from Warp in Settings > Agents > MCP servers.

MCP servers page, showing a server with its UUID.

2. Pass the UUID to --mcp:

$ oz agent run --mcp "1deb1b14-b6e5-4996-ae99-233b7555d2d0" --prompt "who last updated the README?"

Passing MCP servers by well-known id

A bare identifier made up of letters, digits, -, or _ — such as linear — is treated as a well-known managed MCP id rather than a UUID or JSON. Warp resolves it server-side at run setup, so you don’t need to look up a UUID first:

$ oz agent run --mcp linear --prompt "list my assigned issues"

The server owns the set of recognized well-known ids. An id it doesn’t recognize is skipped at run setup rather than failing the run, so new managed servers can become available without a client update.

Passing MCP servers as inline JSON or a file

You can pass MCP configuration inline or via a file:

# Inline JSON
$ oz agent run --mcp '{"github": {"url": "https://api.githubcopilot.com/mcp/"}}' --prompt "list open issues"

# From a file
$ oz agent run --mcp ./my-mcp-config.json --prompt "list open issues"

The file must contain a valid MCP JSON object. For example:

{
  "github": {
    "url": "https://api.githubcopilot.com/mcp/"
  },
  "sentry": {
    "command": "npx",
    "args": ["-y", "mcp-remote@latest", "https://mcp.sentry.dev/mcp"]
  }
}

Combining multiple servers

Pass --mcp multiple times to combine UUID references, inline JSON, and file-based configs in a single run:

$ oz agent run \
  --mcp "1deb1b14-b6e5-4996-ae99-233b7555d2d0" \
  --mcp '{"sentry": {"url": "https://mcp.sentry.dev/mcp"}}' \
  --prompt "open a PR that fixes the top Sentry error"

---

Environment variables on remote machines

Warp syncs MCP server configuration between machines logged in with your Warp account, but does not sync the environment variables used in that configuration. When running on a remote machine, set any required secrets manually before running the agent:

export MY_MCP_SERVER_ACCESS_TOKEN="..."
$ oz agent run --mcp "904a8936-fa82-4571-b1d6-166c26197981" --prompt "use my MCP server to check for errors"

Note

For cloud agent workflows, use Automation Platform-managed secrets to store and inject credentials safely — secrets are stored in the cloud and referenced by name in your config. For local runs, a secrets manager CLI such as op, pass, or gcloud secrets versions access can fetch secrets on remote hosts without exposing them in your shell history.

---

Learn more

• MCP Servers (cloud agents) — configuration schema, full agent config file examples, and cloud agent limitations
• Model Context Protocol (MCP) — configuring MCP servers in Warp for local agents
• Connect developer tools to agents with MCP workflows — choose the setup path for local sessions, cloud runs, team sharing, and repeatable automation
• Secrets — store credentials in Warp so agents can access them at run time without exposing them in config files