MCP servers (CLI reference)

Caution

The Oz CLI (the oz binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use Warp Factories. Warp will publish guidance before any support change.

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.

The CLI does not start every configured MCP server for every run. Explicit --mcp values start run-scoped servers. A selected agent profile can start installed servers on its MCP allowlist, while eligible file-based and global servers follow their own discovery path.

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)
• Managed integration id — reference a Warp-managed integration MCP server by its short id, such as linear (see Passing Warp-managed integration servers by id)
• 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 Warp-managed integration servers by id

Some MCP servers are hosted by Warp and backed by an integration your team has already connected, so they have no UUID of their own. Reference them by their short id instead:

$ oz agent run --mcp linear --prompt "summarize the tickets assigned to me"

Warp recognizes these managed integration ids:

• linear — the hosted Linear MCP server
• slack — the hosted Slack MCP server
• jira — the hosted Jira MCP server

Caution

linear and slack resolve only for runs executing inside a factory with that integration connected; jira also resolves for a run triggered directly by a Jira event. Outside those cases — including a plain oz agent run like the example above — the server is silently skipped and the run continues without it.

The id is resolved when the run starts, using the integration connection that belongs to the run’s team. If the id isn’t one Warp recognizes, the server is also skipped.

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