Connect developer tools to agents with MCP workflows

MCP servers let Warp agents use external tools and data sources through a standard interface. Add an MCP server when an agent needs to read issues, inspect pull requests, query incidents, fetch design context, call internal APIs, or update systems outside the terminal.

Warp supports MCP in two places:

• Local agents in the Warp app use MCP servers configured in Settings > Agents > MCP servers, Warp Drive, or file-based config.
• Cloud agents use MCP servers passed through the Oz CLI, agent config files, or Warp-shared MCP server UUIDs.

Use this guide to choose the right setup path, then jump to the source docs for exact configuration syntax.

Choose local or cloud MCP

Workflow	Use it when	Configure MCP with	Source docs
Local Warp agent	You are working interactively in Warp and want the agent to use tools from your machine or desktop-authenticated services.	Warp MCP settings, Warp Drive MCP servers, .warp/.mcp.json, or provider config files.	Model Context Protocol (MCP)
Third-party CLI agent in Warp	You run Claude Code, Codex, OpenCode, or another CLI agent in Warp and want shared MCP config across tools.	File-based MCP config that Warp can detect and approve.	File-based MCP servers
Cloud agent run	The agent runs in a cloud environment from Slack, Linear, schedules, GitHub Actions, the CLI, or the API.	--mcp, an agent config file, or a Warp-shared MCP UUID.	MCP Servers for cloud agents
Repeatable automation	You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs.	Agent config files plus Agent Secrets for credentials.	MCP servers (CLI reference)

Common MCP workflows

Pull GitHub or Linear context into a local coding session

Use local MCP when you want an interactive agent to understand an issue, PR, or ticket while you work in Warp.

Example workflow:

1. In the Warp app, add a GitHub or Linear MCP server from Settings > Agents > MCP servers.
2. Start a local agent conversation in the repo.
3. Ask the agent to fetch the issue, inspect linked context, and make a plan.
4. Review changes in the Code Review panel.
5. Use Agent Session Sharing if teammates need to inspect the agent context.

For setup details, see Model Context Protocol (MCP).

Give cloud agents access to developer tools

Use cloud MCP when an unattended or remote agent needs tool access while it runs away from your machine.

Example workflow:

1. Create or identify the MCP server the cloud agent should use.
2. Store required credentials as Agent Secrets instead of hardcoding tokens in config files.
3. Attach the MCP server with --mcp, a config file, or a Warp-shared MCP UUID.
4. Run the cloud agent from the Oz CLI, Slack, Linear, GitHub Actions, a schedule, or the API.
5. Inspect the run in the Oz web app or Cloud agent session sharing.

For schema and cloud-specific limitations, see MCP Servers for cloud agents.

Share an MCP server with a team

Use shared MCP servers when multiple teammates or workflows need the same tool connection.

For local agents, share the server from the MCP settings page. Warp scrubs sensitive environment values and prompts teammates to provide their own values when they install it.

For cloud agents, reference a Warp-shared MCP server by UUID with the Oz CLI:

oz mcp list

Then pass the UUID to an agent run:

oz agent run-cloud --mcp "<MCP_SERVER_UUID>" --prompt "Summarize the latest production incidents"

See MCP servers (CLI reference) for all --mcp formats.

Local MCP setup paths

For local agents, choose one of these paths:

• Warp settings - Best for one-off setup and interactive use. In the Warp app, add servers from Settings > Agents > MCP servers.
• Warp Drive - Best for MCP servers you want to manage as Warp Drive objects.
• File-based config - Best when MCP config should live with a repo or follow you across Warp, Claude Code, Codex, and other agent tools.
• /agent-add-mcp skill - Best when you want Warp’s agent to create or update .warp/.mcp.json with your approval.

File-based MCP is useful for teams because config can be versioned with a project, but it also needs review. Warp requires approval before project-scoped servers start so cloned repos cannot silently launch commands.

Cloud MCP setup paths

For cloud agents, choose one of these paths:

• Warp-shared MCP UUID - Best when a server is already configured and shared in Warp.
• Inline JSON - Best for quick experiments.
• JSON file - Best for reusable scripts.
• Agent config file - Best for production workflows where model, environment, prompt, and MCP servers should live together.

Cloud agents run away from your desktop. Any secrets required by MCP tools should be available in the cloud run through Agent Secrets or the execution environment, not only in your local shell.

Caution

OAuth-based MCP servers are not currently supported directly for cloud agents. If a server requires browser-based OAuth, use it with a local agent, choose a token-based/server-side configuration if the provider supports it, or pass the relevant artifact as context another way.

Example tools MCP can connect

Warp supports MCP servers for many developer tools, including:

• GitHub - Read issues, PRs, files, and repository metadata.
• Linear - Fetch issues, update tickets, and reason over project context.
• Sentry - Inspect errors, traces, and release context.
• Figma - Pull design context for UI work.
• Notion - Retrieve docs, specs, and project notes.
• Internal tools - Expose your own APIs through a custom MCP server.

For example configurations and demos, see the MCP server examples in Model Context Protocol (MCP) and the MCP guides listed on the Guides page.

Security checklist

Before giving an agent tool access through MCP:

• Use the narrowest credentials and scopes that let the workflow run.
• Prefer service accounts for team or scheduled workflows.
• Store cloud-run credentials in Agent Secrets.
• Review file-based MCP config before approving it, especially commands, args, environment variables, and URLs.
• Treat MCP logs as sensitive if they contain API responses, tokens, request headers, or private data.
• For cloud agents, confirm whether the MCP server can be reached from the cloud environment or self-hosted worker.

Next steps

• Model Context Protocol (MCP) - Configure MCP servers for local agents in the Warp app.
• MCP Servers for cloud agents - Configure MCP servers for cloud runs and automation.
• MCP servers (CLI reference) - Use --mcp with UUIDs, inline JSON, or files.
• Agent Secrets - Store credentials for cloud agent runs.