Skip to content
Warp

Oz > Extending agents

MCP Servers for cloud agents

Open in ChatGPT ↗
Ask ChatGPT about this page
Open in Claude ↗
Ask Claude about this page
Copied!

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. 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

Section titled “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

Section titled “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 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

Section titled “Configuration schema”

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

TransportField(s)When to use
Warp-shared server or managed MCP installwarp_idReference an MCP server already configured in Warp — including an OAuth-authorized managed MCP installation — by its UUID
Stdio (local process)command, argsLaunch a local executable as an MCP server
Streamable HTTP / SSEurlConnect to a remote or locally hosted MCP endpoint

Supported fields

Section titled “Supported fields”
  • warp_id — UUID of a Warp-shared MCP server or a managed MCP installation (find UUIDs with oz mcp list, from Settings > Agents > MCP servers, or from the Oz web app 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

Section titled “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}}"
    }
  }
}

Using MCP servers in an agent config file

Section titled “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:

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

Requirements and defaults

Section titled “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

Section titled “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, 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

Section titled “Limitations”

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

Section titled “Learn more”