MCP Servers for cloud agents

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

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.

Warp-managed integration tools in factories

When Slack, Linear, or Jira is connected for a factory, Warp automatically makes tools from that integration available to the factory's agents. These Warp-managed capabilities use the connected integration's authorization and don't require a separate MCP server installation.

Integration-provided tools are separate from the MCP servers you configure with mcp_servers or mcpServers. They may not appear alongside user-configured servers in the factory's MCP list, even though the agent can use them during a run. For example, a scheduled factory run can use the Slack tools to post a report to a channel without Slack triggering the run.

See posting a scheduled factory digest to Slack for a complete automation and prompt. If you need a different external service, configure its MCP server using the options below.

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.

For factory work, declare factory-wide or per-agent MCP servers in the factory definition. Use Factory MCP to connect an external coding agent to a factory.

Configuration schema

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

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), or the id of a Warp-managed integration server: linear, slack, or jira
• 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}}"
    }
  }
}

Connect directly by URL

Use url to connect the agent worker to an existing streamable HTTP or SSE MCP endpoint. A Warp-hosted worker requires a publicly reachable URL, while a self-hosted worker can reach a private endpoint available from its network. For credentials sent with headers, use HTTPS to protect them in transit.

Team-managed URL servers use Warp-managed by default. To use a direct connection, open MCPs and apps in the factory dashboard, click New, then click Custom MCP. Enter the configuration, then select Direct under "Connection mode."

{
  "internal-tools": {
    "url": "https://mcp.internal.example/mcp",
    "headers": {
      "Authorization": "Bearer {{INTERNAL_MCP_TOKEN}}"
    }
  }
}

Store INTERNAL_MCP_TOKEN as a managed secret. Warp resolves the placeholder in the agent runtime before it connects.

For a self-hosted worker, see managed self-hosting. For a managed MCP server with a private endpoint, use private networking onboarding.

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 user-configured MCP servers enabled. Factory runs can still receive Warp-managed integration tools.
• 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.
• A warp_id that names a Warp-managed integration server (linear, slack, or jira) resolves against your team's integration connection, but only for a run executing inside a factory (jira also resolves for a run triggered directly by a Jira event). Outside those cases, or when the integration isn't connected, the server is skipped and the run continues without it.

OAuth authentication

Cloud agents support OAuth-protected MCP servers through a managed MCP installation — a cloud run can't complete an interactive browser login, so authorization happens 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 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 then use the stored credentials automatically, with no browser interaction. This is the supported path for hosted OAuth servers such as Figma's remote MCP server.

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

Learn more

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