Skip to content

Update MCP docs to reflect current OAuth MCP support for cloud agents #504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
warp-agent-staging wants to merge 2 commits into
base: main
Choose a base branch
from
+20 −6
Open

Update MCP docs to reflect current OAuth MCP support for cloud agents #504

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3954f9d
docs: clarify OAuth MCP support for cloud agents
warp-agent Aug 11, 2026
4725c8e
Revert incidental package-lock.json drift from local npm install
warp-agent Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ tags:
featured: true
---
import VideoEmbed from '@components/VideoEmbed.astro';
import { VARS } from '@data/vars';

<VideoEmbed url="https://www.youtube.com/watch?v=8vn2brhJrF8" title="Using MCP servers with Warp agents video" />

Expand Down Expand Up @@ -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
Expand Down
23 changes: 18 additions & 5 deletions src/content/docs/platform/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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`)
Expand Down Expand Up @@ -108,14 +109,26 @@ oz agent run-cloud --environment <ENV_ID> -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
Expand Down
Loading