> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# MCP servers (CLI reference)

Connect agents to external tools like GitHub, Linear, and Sentry by passing MCP servers to the --mcp flag as a UUID, inline JSON, or file path.

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](/agents/cli/) for the replacement.

MCP servers connect agents to external systems like GitHub, Linear, or Sentry. To use a [Model Context Protocol (MCP)](/agents/capabilities/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](/guides/external-tools/using-mcp-servers-with-warp/). For a conceptual overview of MCP with cloud agents — including configuration schema, full agent config examples, and limitations — see [MCP Servers](/platform/mcp/) 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](#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](/_astro/mcp-server-id.L5Kbd7FO_Z2wXS2o.webp?dpl=dpl_5xPK1pz5MHmis4iiaD9eSPKxt1j9)

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](/platform/integrations/) 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](/platform/integrations/linear/) MCP server
-   `slack` — the hosted [Slack](/platform/integrations/slack/) MCP server
-   `jira` — the hosted [Jira](/platform/integrations/jira/) MCP server

The id is resolved when the run starts, using the integration connection that belongs to your team. If the integration isn’t connected, or the id isn’t one Warp recognizes, the server is skipped and the run continues without it.

### 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](/platform/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`](https://developer.1password.com/docs/cli/get-started/), [`pass`](https://www.passwordstore.org/), or [`gcloud secrets versions access`](https://cloud.google.com/secret-manager/docs/create-secret-quickstart#secretmanager-quickstart-gcloud) can fetch secrets on remote hosts without exposing them in your shell history.

* * *

## Learn more

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