Warp Terminal & Oz

Appearance

SOP 005: MCP Servers ​

Fresh
FieldValue
SOP IDSOP-005
Version1.0
StatusActive
Sourcedocs.warp.dev/agent-platform/capabilities/mcp

Overview ​

MCP (Model Context Protocol) servers connect agents to external tools and data sources like GitHub, Linear, and Sentry. This enables agents to interact with your development ecosystem.

Prerequisites ​

  • Oz CLI installed and authenticated
  • Agent profile that allows MCP server usage
  • Authentication tokens for external services

Procedure ​

Step 1: Add an MCP Server ​

GitHub (built-in):

bash
oz mcp add github

You'll be prompted to authorize the Warp GitHub App if needed.

Step 2: List Available MCP Servers ​

bash
oz mcp list

Example output:

+--------------------------------------+--------+
| UUID                                 | Name   |
+===============================================+
| 1deb1b14-b6e5-4996-ae99-233b7555d2d0 | github |
| 65450c32-9eb1-4c57-8804-0861737acbc4 | linear |
| d94ade64-0e73-47a6-b3ee-14e5afec3d90 | Sentry |
+--------------------------------------+--------+

Step 3: Use MCP Servers with Agent Runs ​

bash
# Use specific MCP server by UUID
oz agent run \
  --mcp-server "1deb1b14-b6e5-4996-ae99-233b7555d2d0" \
  --prompt "who last updated the README?"

Step 4: Configure Agent Profile for MCP ​

Two approaches:

  1. Specific MCP servers - Profile allows only listed servers (auto-start)
  2. Any MCP server - Profile allows any server (must specify with --mcp-server)

Configure profiles in Warp: Settings > AI > Agent Profiles

Step 5: Set Environment Variables for Remote Execution ​

MCP server config syncs between hosts, but environment variables do not.

bash
# Set auth tokens on remote machines
export MY_MCP_SERVER_ACCESS_TOKEN="..."
oz agent run \
  --mcp-server "UUID" \
  --prompt "check for errors"

TIP

Use a secret manager CLI (op, pass, gcloud secrets) to fetch MCP secrets on remote hosts.

Step 6: Configure MCP for Cloud Agents ​

MCP servers work with cloud agents via the Oz CLI and web app. Configure centrally so the same workflow works across all triggers (Slack, CI, schedules).

Finding MCP Server IDs ​

CLI:

bash
oz mcp list

Warp Settings:

  1. Click profile photo > Settings
  2. Sidebar > MCP Servers
  3. Copy the UUID

Verification Checklist ​

  • [ ] MCP server added successfully with oz mcp add
  • [ ] oz mcp list shows the server with UUID
  • [ ] Agent can use MCP server tools in conversation
  • [ ] Auth tokens set correctly for remote execution

Troubleshooting ​

IssueSolution
MCP server not startingCheck agent profile allows the server
Auth errorsVerify environment variables are set correctly
Server not listedRe-add with oz mcp add
Remote execution failsSet env vars on remote host (they don't sync)

See Also ​