# MCP Servers for cloud agents

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

- 网址：https://funcoding.ai/agents/warp/platform/mcp/
- 来源：Warp 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.warp.dev/platform/mcp/

---
Cloud agents can call external tools through [Model Context Protocol (MCP) servers](https://funcoding.ai/agents/warp/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.

## 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](https://funcoding.ai/agents/warp/factories/integrations/slack/#post-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](https://funcoding.ai/agents/warp/agents/cli/oz-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.

For factory work, declare factory-wide or per-agent MCP servers in the [factory definition](https://funcoding.ai/agents/warp/factories/factory-as-code/#mcpservers). Use [Factory MCP](https://funcoding.ai/agents/warp/factories/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:

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

### 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](https://funcoding.ai/agents/warp/platform/oz-web-app/#integrations) **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

```json
{
  "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}}"
    }
  }
}
```

<div class="callout callout-note">

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

</div>

### 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](https://funcoding.ai/agents/warp/factories/factory-dashboard/), click **New**, then click **Custom MCP**. Enter the configuration, then select **Direct** under "Connection mode."

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

Store `INTERNAL_MCP_TOKEN` as a [managed secret](https://funcoding.ai/agents/warp/platform/secrets/). Warp resolves the placeholder in the agent runtime before it connects.

For a self-hosted worker, see [managed self-hosting](https://funcoding.ai/agents/warp/factories/self-hosting/). For a managed MCP server with a private endpoint, use [private networking onboarding](https://funcoding.ai/agents/warp/enterprise/enterprise-features/private-networking/).

## 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`:

```json
{
  "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:

```sh
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](#warp-managed-integration-tools-in-factories).
* 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](https://funcoding.ai/agents/warp/platform/integrations/) connection, but only for a run executing inside a [factory](https://funcoding.ai/agents/warp/factories/) (`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](https://funcoding.ai/agents/warp/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 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

<div class="callout callout-warning">

A direct `url` MCP server that requires OAuth and has no `Authorization` header can't be used by cloud agents. Set it up as a [managed MCP installation](#oauth-authentication) instead, then reference it by `warp_id`.

</div>

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](https://funcoding.ai/agents/warp/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths
* [MCP Servers (CLI reference)](https://funcoding.ai/agents/warp/agents/cli/oz-cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag
* [Model Context Protocol (MCP)](https://funcoding.ai/agents/warp/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents
* [Environments](https://funcoding.ai/agents/warp/platform/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks
* [Secrets](https://funcoding.ai/agents/warp/platform/secrets/) — store and inject credentials into agent runs safely