> 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 for cloud agents

Connect cloud agents to external tools, APIs, and internal services using MCP servers.

Cloud agents can call external tools through [Model Context Protocol (MCP) servers](/agents/capabilities/mcp/). This lets agents reach beyond the terminal to automatically interact with systems like GitHub, dbt, Sentry, or any custom internal service, whenever the workflow requires it.

## When to use MCP servers

Add MCP servers to a cloud agent when it needs to:

-   Read from or write to an external API (issue trackers, monitoring tools, cloud services)
-   Call local processes that expose MCP endpoints
-   Use internal developer tools that you’ve wrapped in an MCP interface

The agent calls MCP tools automatically based on what the task requires, without the need for explicit instruction.

## How MCP configuration works

You can supply MCP configuration in two ways:

-   **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/reference/cli/mcp-servers/) in the CLI reference for the full syntax.
-   **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows.

## Configuration schema

Each MCP server entry is keyed by a name you choose. A server config must have **exactly one** transport type:

| Transport | Field(s) | When to use |
| --- | --- | --- |
| Warp-shared server or managed MCP install | `warp_id` | Reference an MCP server already configured in Warp — including an OAuth-authorized [managed MCP installation](#oauth-authentication) — by its UUID |
| Stdio (local process) | `command`, `args` | Launch a local executable as an MCP server |
| Streamable HTTP / SSE | `url` | Connect to a remote or locally hosted MCP endpoint |

### Supported fields

-   **`warp_id`** — UUID of a Warp-shared MCP server or a [managed MCP installation](#oauth-authentication) (find UUIDs with `oz mcp list`, from **Settings** > **Agents** > **MCP servers**, or from the [Oz web app](/platform/oz-web-app/#integrations) **Integrations** page)
-   **`command`** — Executable to launch (stdio transport)
-   **`args`** — Arguments passed to `command` (only valid with `command`)
-   **`env`** — Environment variables passed to the process (only valid with `command`)
-   **`url`** — HTTP or HTTPS endpoint URL (streamable HTTP or SSE transport)
-   **`headers`** — HTTP headers sent with requests (only valid with `url`)

You can define any number of MCP servers in a single config.

### Example configuration

```
{  "github": {    "url": "https://mcp.example.com/github"  },  "dbt": {    "command": "uvx",    "args": ["dbt-mcp"],    "env": {      "DBT_HOST": "https://example.us1.dbt.com",      "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}"    }  }}
```

Note

If the config passes through a system that pre-processes `{{...}}` before it reaches Oz (for example, Jira/Atlassian Automation), use JSON unicode escapes for the braces: `\u007b\u007bMY_SECRET\u007d\u007d` decodes to `{{MY_SECRET}}`, which Oz resolves normally.

## Using MCP servers in an agent config file

For repeatable cloud agent workflows, declare your MCP servers inside the agent config file passed to `-f / --file`:

```
{  "name": "my-production-agent",  "model_id": "claude-sonnet-4",  "system_prompt": "You are a helpful assistant focused on backend development.",  "environment_id": "SVhg783GBFQHk1OfdPfFU9",  "mcp_servers": {    "github": {      "url": "https://mcp.example.com/github"    },    "dbt": {      "command": "uvx",      "args": ["dbt-mcp"],      "env": {        "DBT_HOST": "https://example.us1.dbt.com",        "DBT_SERVICE_TOKEN": "{{DBT_SERVICE_TOKEN}}"      }    }  }}
```

Pass this file when running a cloud agent:

```
oz agent run-cloud --environment <ENV_ID> -f my-agent-config.json --prompt "Check for regressions in the last deploy"
```

## Requirements and defaults

-   MCP configuration must be valid JSON, or YAML when embedded in a broader agent config file.
-   If `mcp_servers` is omitted, the agent runs with no MCP servers enabled.
-   Each server name must be unique and non-empty.
-   The `warp_id` transport is validated against your Warp account. Referenced servers must be accessible to you.

## OAuth authentication

Cloud agents support OAuth-protected MCP servers, but only through a **managed MCP installation** — not a raw `url` config. An unattended cloud run can’t complete the interactive browser login a direct OAuth handshake needs, so authorization has to happen ahead of time instead.

To use an OAuth-gated server with a cloud agent:

1.  In the [Oz web app](/platform/oz-web-app/#integrations), open **Integrations** and add the server as a managed MCP server.
2.  Authorize it once. Warp completes the OAuth flow in a browser and stores the resulting credentials.
3.  Reference the installation’s UUID as `warp_id` in your `--mcp` flag or agent config, the same way you’d reference any Warp-shared server.

Cloud agent runs use the stored credentials automatically — no browser interaction happens during the run. This is the supported path for hosted OAuth servers such as Figma’s remote MCP server.

## Limitations

Caution

A direct `url` MCP server that requires OAuth and has no `Authorization` header can’t be used as-is by cloud agents. Set it up as a [managed MCP installation](#oauth-authentication) first so authorization happens ahead of time, then reference it by `warp_id`.

Token- or header-based authentication on a `url` server, `env`\-based secrets on a `command` server, and `warp_id` references to a Warp-shared or managed server all work without any additional setup.

## Learn more

-   [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths
-   [MCP Servers (CLI reference)](/reference/cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag
-   [Model Context Protocol (MCP)](/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents
-   [Environments](/platform/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks
-   [Secrets](/platform/secrets/) — store and inject credentials into agent runs safely