diff --git a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx
index 554c71d1..6d9bc892 100644
--- a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx
+++ b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx
@@ -10,6 +10,7 @@ tags:
featured: true
---
import VideoEmbed from '@components/VideoEmbed.astro';
+import { VARS } from '@data/vars';
@@ -104,7 +105,7 @@ For cloud agents, choose one of these paths:
Cloud agents run away from your desktop. Any secrets required by MCP tools should be available in the cloud run through [Agent Secrets](/platform/secrets/) or the execution environment, not only in your local shell.
:::caution
-OAuth-based MCP servers are not currently supported directly for cloud agents. If a server requires browser-based OAuth, use it with a local agent, choose a token-based/server-side configuration if the provider supports it, or pass the relevant artifact as context another way.
+A cloud agent can't complete a browser-based OAuth login mid-run, so a raw `url` MCP config that requires OAuth isn't supported directly. Set it up as a managed MCP installation instead: authorize it once from the [{VARS.WEB_APP}](/platform/oz-web-app/#integrations) **Integrations** page, then reference the installation by `warp_id`. See [OAuth authentication](/platform/mcp/#oauth-authentication) for the setup steps.
:::
## Example tools MCP can connect
diff --git a/src/content/docs/platform/mcp.mdx b/src/content/docs/platform/mcp.mdx
index 6340c539..5219f06c 100644
--- a/src/content/docs/platform/mcp.mdx
+++ b/src/content/docs/platform/mcp.mdx
@@ -6,6 +6,7 @@ description: >-
sidebar:
label: "MCP servers"
---
+import { VARS } from '@data/vars';
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.
@@ -32,13 +33,13 @@ Each MCP server entry is keyed by a name you choose. A server config must have *
| Transport | Field(s) | When to use |
|-----------|----------|-------------|
-| Warp-shared server | `warp_id` | Reference an MCP server already configured in Warp by its UUID |
+| 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 (find UUIDs with `oz mcp list` or from **Settings** > **Agents** > **MCP servers**)
+* **`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 [{VARS.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`)
@@ -108,14 +109,26 @@ oz agent run-cloud --environment -f my-agent-config.json --prompt "Chec
* 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 [{VARS.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
-Warp does not currently support OAuth-based MCP servers for cloud agents. This means MCP servers that require browser-based authentication, like some hosted Figma configurations, cannot be used directly.
-
-As a workaround, you can pass Figma mockups as **image context** to the agent, which can then build and test UI against those images.
+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