Skip to content

docs(mcp): document well-known managed integration ids #599

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

Draft
hongyi-chen wants to merge 1 commit into
base: main
Choose a base branch
from
+21 −3
Draft

docs(mcp): document well-known managed integration ids #599

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 3 additions & 2 deletions src/content/docs/platform/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,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 | `warp_id` | Reference an MCP server already configured in Warp 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 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 (find UUIDs with `oz mcp list` or from **Settings** > **Agents** > **MCP servers**), 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`)
Expand Down Expand Up @@ -108,6 +108,7 @@ oz agent run-cloud --environment <ENV_ID> -f my-agent-config.json --prompt "Chec
* 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.
* A `warp_id` that names a Warp-managed integration server (`linear`, `slack`, or `jira`) resolves against your team's [integration](/platform/integrations/) connection when the run starts. If that integration isn't connected, the server is skipped and the run continues without it.

## Limitations

Expand Down
19 changes: 18 additions & 1 deletion src/content/docs/reference/cli/mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,10 @@ For help choosing between local, cloud, and shared MCP workflows, see [Connect d

## Using the `--mcp` flag

The `--mcp` flag accepts three formats:
The `--mcp` flag accepts four formats:

* **UUID** — reference a Warp-shared MCP server by its UUID (find UUIDs with `oz mcp list`)
* **Managed integration id** — reference a Warp-managed integration MCP server by its short id, such as `linear` (see [Passing Warp-managed integration servers by id](#passing-warp-managed-integration-servers-by-id))
* **Inline JSON** — pass a full MCP JSON configuration directly as a string
* **File path** — path to a JSON file containing the MCP configuration

Expand Down Expand Up @@ -58,6 +59,22 @@ $ oz mcp list
$ oz agent run --mcp "1deb1b14-b6e5-4996-ae99-233b7555d2d0" --prompt "who last updated the README?"
```

### Passing Warp-managed integration servers by id

Some MCP servers are hosted by Warp and backed by an [integration](/platform/integrations/) your team has already connected, so they have no UUID of their own. Reference them by their short id instead:

```sh
$ oz agent run --mcp linear --prompt "summarize the tickets assigned to me"
```

Warp recognizes these managed integration ids:

* `linear` — the hosted [Linear](/platform/integrations/linear/) MCP server
* `slack` — the hosted [Slack](/platform/integrations/slack/) MCP server
* `jira` — the hosted [Jira](/platform/integrations/jira/) MCP server

The id is resolved when the run starts, using the integration connection that belongs to your team. If the integration isn't connected, or the id isn't one Warp recognizes, the server is skipped and the run continues without it.

### Passing MCP servers as inline JSON or a file

You can pass MCP configuration inline or via a file:
Expand Down
Loading