Support MCP servers for third-party harnesses. (#10341)

## Description
<!-- Please remember to add your design buddy onto the PR for review, if
it contains any UI changes! -->
This PR adds support for MCP servers for third-party harnesses with
cloud agents.

When setting up the driver for a third-party task, we add a new step
`resolve_mcp_specs_to_json`, which converts MCP server config data from
the task into a JSON format by applying any secret values to the
templated MCP.

We thread this list of `JSONMCPServer`s into each harness's environment
setup, where:
- Claude writes them to a temp file, which we pass a path to via
`--mcp-config` flag
- Codex writes them to a section of `config.toml`

In this PR, I also remove `prepare_environment_config` from the
`ThirdPartyHarness` trait and move its implementation into
`build_runner`. Across Claude Code and Codex we started to do different
parts of the environment setup process in each place (e.g. Codex would
seed the system prompt in `prepare_environment_config`, while CC needed
to do it in `build_runner` so we could hold onto the temp file), which
resulted in adding the params to both functions that each harness would
ignore in one place and user in the other. We always call
`prepare_environment_config`, and `build_runner` back to back; now we
fold `prepare_environment_config` responsibilities within
`build_runner`.

## Testing
<!--
How did you test this change? What automated tests did you add? If you
didn't add any new tests, what's your justification for not adding any?

Manual testing is required for changes that can be manually tested, and
almost all changes can be manually tested. If your change can be
manually tested, please include screenshots or a screen recording that
show it working end to end.

You can run the app locally using `./script/run` - see WARP.md for more
details on how to get set up.
-->

Tested locally for both `codex` and `claude` with `./script/oz-local`,
Loom available in Slack.
- [x] Just Linear (single MCP, stdio)
- [x] Linear and Sentry (multiple MCP servers, stdio)
- [x] Context7 (single MCP, http)

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

Author: liliwilson

app/src/ai/agent_sdk/driver.rs

@@ -17,7 +17,7 @@ use std::{
 use crate::ai::blocklist::task_status_sync_model::TaskStatusSyncModel;
 use crate::ai::document::ai_document_model::{AIDocumentModel, AIDocumentModelEvent};
 use crate::ai::llms::{LLMId, LLMPreferences};
-use crate::ai::mcp::MCPServerState;
+use crate::ai::mcp::{JSONMCPServer, MCPServerState};
 use crate::ai::skills::{SkillManager, SkillWatcher};
 use crate::ai::{
     agent::conversation::AIConversationId,
@@ -53,7 +53,7 @@ use crate::{
         execution_profiles::profiles::AIExecutionProfilesModel,
         mcp::{
             file_based_manager::{FileBasedMCPManager, FileBasedMCPManagerEvent},
-            parsing::{normalize_mcp_json, ParsedTemplatableMCPServerResult},
+            parsing::{normalize_mcp_json, resolve_json, ParsedTemplatableMCPServerResult},
             templatable_manager::TemplatableMCPServerManagerEvent,
             TemplatableMCPServerInstallation, TemplatableMCPServerManager,
         },
@@ -260,9 +260,9 @@ pub struct AgentDriver {
     secrets: Arc<HashMap<String, ManagedSecretValue>>,
 
     /// Env vars passed to the terminal session, including resolved secrets, cloud
-    /// provider vars, task vars, and sandbox flags. Shared with
-    /// `prepare_environment_config` so harnesses can look up resolved secret
-    /// values without re-deriving precedence.
+    /// provider vars, task vars, and sandbox flags. Passed to
+    /// `build_runner` so harnesses can look up resolved secret values
+    /// without re-deriving precedence.
     resolved_env_vars: Arc<HashMap<OsString, OsString>>,
 
     output_format: OutputFormat,
@@ -790,6 +790,44 @@ impl AgentDriver {
         }
     }
 
+    /// Resolve MCP specs into a map of MCP name to `JSONMCPServer` for use in
+    /// third-party harnesses. Each spec is fully resolved (secrets applied, templates
+    /// rendered) so harnesses can serialize directly into their native config format.
+    fn resolve_mcp_specs_to_json(
+        specs: &[MCPSpec],
+        secrets: &HashMap<String, ManagedSecretValue>,
+        ctx: &ModelContext<Self>,
+    ) -> Result<HashMap<String, JSONMCPServer>, AgentDriverError> {
+        let (existing_uuids, mut ephemeral_installations) = Self::resolve_mcp_specs(specs)?;
+        let mut result = HashMap::new();
+
+        // Resolve UUID-referenced servers from the TemplatableMCPServerManager.
+        let manager = TemplatableMCPServerManager::as_ref(ctx);
+        for uuid in &existing_uuids {
+            let installation = manager
+                .get_installed_server(uuid)
+                .ok_or(AgentDriverError::MCPServerNotFound(*uuid))?
+                .clone();
+            let mut installation = installation;
+            installation.apply_secrets(secrets);
+            let resolved = resolve_json(&installation);
+            let servers: HashMap<String, JSONMCPServer> = serde_json::from_str(&resolved)
+                .map_err(|e| AgentDriverError::MCPJsonParseError(e.to_string()))?;
+            result.extend(servers);
+        }
+
+        // Resolve ephemeral (inline JSON) servers.
+        for installation in ephemeral_installations.iter_mut() {
+            installation.apply_secrets(secrets);
+            let resolved = resolve_json(installation);
+            let servers: HashMap<String, JSONMCPServer> = serde_json::from_str(&resolved)
+                .map_err(|e| AgentDriverError::MCPJsonParseError(e.to_string()))?;
+            result.extend(servers);
+        }
+
+        Ok(result)
+    }
+
     /// Resolve MCP specs into UUIDs for existing servers and ephemeral installations for inline specs.
     ///
     /// Returns (existing_server_uuids, ephemeral_installations)
@@ -1451,8 +1489,13 @@ impl AgentDriver {
             }
             HarnessKind::ThirdParty(harness) => {
                 let harness_exit_rx = Self::setup_harness(harness.as_ref(), &foreground).await?;
-                let runner =
-                    Self::prepare_harness(&task.prompt, harness.as_ref(), &foreground).await?;
+                let runner = Self::prepare_harness(
+                    &task.prompt,
+                    &task.mcp_specs,
+                    harness.as_ref(),
+                    &foreground,
+                )
+                .await?;
 
                 if let Some(task_id) = task_id_for_refresh {
                     let harness_fut =
@@ -1514,6 +1557,7 @@ impl AgentDriver {
     /// return a handle to the harness runner.
     async fn prepare_harness(
         prompt: &AgentRunPrompt,
+        mcp_specs: &[MCPSpec],
         harness: &dyn ThirdPartyHarness,
         foreground: &ModelSpawner<Self>,
     ) -> Result<Arc<dyn harness::HarnessRunner>, AgentDriverError> {
@@ -1570,18 +1614,29 @@ impl AgentDriver {
             }
         };
 
-        // Prepare harness config files (onboarding, trust dialog, API-key approval, etc.).
-        // Pass the terminal env vars (which include the resolved secrets) so harnesses
-        // can look up auth keys without re-deriving precedence.
+        let secrets = foreground
+            .spawn(|me, _| Arc::clone(&me.secrets))
+            .await
+            .map_err(|_| AgentDriverError::InvalidRuntimeState)?;
+
+        // Resolve MCP specs into harness-native JSON format.
+        let mcp_specs = mcp_specs.to_vec();
+        let resolved_mcp_servers = foreground
+            .spawn(move |_, ctx| Self::resolve_mcp_specs_to_json(&mcp_specs, &secrets, ctx))
+            .await
+            .map_err(|_| AgentDriverError::InvalidRuntimeState)?;
+        let resolved_mcp_servers = resolved_mcp_servers?;
+        if !resolved_mcp_servers.is_empty() {
+            log::info!(
+                "Resolved {} MCP server(s) for third-party harness",
+                resolved_mcp_servers.len()
+            );
+        }
+
         let resolved_env_vars = foreground
             .spawn(|me, _| Arc::clone(&me.resolved_env_vars))
             .await
             .map_err(|_| AgentDriverError::InvalidRuntimeState)?;
-        harness.prepare_environment_config(
-            &working_dir,
-            system_prompt.as_deref(),
-            &resolved_env_vars,
-        )?;
         let resume = foreground
             .spawn(|me, _| me.resume_payload.take())
             .await
@@ -1597,6 +1652,8 @@ impl AgentDriver {
                 server_api,
                 terminal_driver,
                 resume,
+                &resolved_env_vars,
+                &resolved_mcp_servers,
             )?
             .into();
 

app/src/ai/agent_sdk/driver/harness/claude_code.rs

@@ -16,6 +16,7 @@ use warpui::{ModelHandle, ModelSpawner};
 
 use crate::ai::agent::conversation::AIConversationId;
 use crate::ai::ambient_agents::AmbientAgentTaskId;
+use crate::ai::mcp::JSONTransportType;
 use crate::server::server_api::harness_support::{upload_to_target, HarnessSupportClient};
 use crate::server::server_api::ServerApi;
 use crate::terminal::model::block::BlockId;
@@ -31,7 +32,7 @@ use super::claude_transcript::{
 use super::json_utils::{read_json_file_or_default, write_json_file};
 use super::{
     cli_agent_session_status, write_temp_file, HarnessCleanupDisposition, HarnessRunner,
-    ResumePayload, SavePoint, ThirdPartyHarness,
+    JSONMCPServer, ResumePayload, SavePoint, ThirdPartyHarness,
 };
 mod parent_bridge;
 mod wake_driver;
@@ -70,20 +71,6 @@ impl ThirdPartyHarness for ClaudeHarness {
         Some("https://code.claude.com/docs/en/quickstart")
     }
 
-    fn prepare_environment_config(
-        &self,
-        working_dir: &Path,
-        _system_prompt: Option<&str>,
-        resolved_env_vars: &HashMap<OsString, OsString>,
-    ) -> Result<(), AgentDriverError> {
-        prepare_claude_environment_config(working_dir, resolved_env_vars).map_err(|error| {
-            AgentDriverError::HarnessConfigSetupFailed {
-                harness: self.cli_agent().command_prefix().to_owned(),
-                error,
-            }
-        })
-    }
-
     /// Fetch the Claude Code transcript for the current task's conversation and wrap it
     /// into a [`ResumePayload::Claude`]. Maps a server 404 to
     /// [`AgentDriverError::ConversationResumeStateMissing`] tagged as the `claude` harness
@@ -114,7 +101,17 @@ impl ThirdPartyHarness for ClaudeHarness {
         server_api: Arc<ServerApi>,
         terminal_driver: ModelHandle<TerminalDriver>,
         resume: Option<ResumePayload>,
+        resolved_env_vars: &HashMap<OsString, OsString>,
+        resolved_mcp_servers: &HashMap<String, JSONMCPServer>,
     ) -> Result<Box<dyn HarnessRunner>, AgentDriverError> {
+        // Prepare the environment config files.
+        prepare_claude_environment_config(working_dir, resolved_env_vars).map_err(|error| {
+            AgentDriverError::HarnessConfigSetupFailed {
+                harness: self.cli_agent().command_prefix().to_owned(),
+                error,
+            }
+        })?;
+
         // The ResumePayload shouldn't contain non-Claude information, error if it does.
         let claude_resume = resume.map(ClaudeResumeInfo::try_from).transpose()?;
         // Claude treats the user-turn message as immediate intent, so the resumption preamble
@@ -132,6 +129,7 @@ impl ThirdPartyHarness for ClaudeHarness {
             server_api,
             terminal_driver,
             claude_resume,
+            resolved_mcp_servers,
         )?))
     }
 }
@@ -153,13 +151,17 @@ fn claude_command(
     session_id: &Uuid,
     prompt_path: &str,
     system_prompt_path: Option<&str>,
+    mcp_config_path: Option<&str>,
     resuming: bool,
 ) -> String {
     let flag = if resuming { "--resume" } else { "--session-id" };
     let mut cmd = format!("{cli_name} {flag} {session_id} --dangerously-skip-permissions");
     if let Some(sp_path) = system_prompt_path {
         let _ = write!(cmd, " --append-system-prompt-file '{sp_path}'");
     }
+    if let Some(mcp_path) = mcp_config_path {
+        let _ = write!(cmd, " --mcp-config '{mcp_path}'");
+    }
     format!("{cmd} < '{prompt_path}'")
 }
 
@@ -182,6 +184,8 @@ struct ClaudeHarnessRunner {
     _temp_prompt_file: NamedTempFile,
     /// Held so the system prompt temp file is cleaned up when the runner is dropped.
     _temp_system_prompt_file: Option<NamedTempFile>,
+    /// Held so the MCP config temp file lives until the CLI exits.
+    _temp_mcp_config_file: Option<NamedTempFile>,
     client: Arc<dyn HarnessSupportClient>,
     server_api: Arc<ServerApi>,
     terminal_driver: ModelHandle<TerminalDriver>,
@@ -208,10 +212,11 @@ impl ClaudeHarnessRunner {
         server_api: Arc<ServerApi>,
         terminal_driver: ModelHandle<TerminalDriver>,
         resume: Option<ClaudeResumeInfo>,
+        resolved_mcp_servers: &HashMap<String, JSONMCPServer>,
     ) -> Result<Self, AgentDriverError> {
         // Write the prompt to a temp file so we can feed it via stdin redirect,
         // avoiding shell-quoting issues with complex content (e.g. skill instructions).
-        let temp_file = write_temp_file("oz_prompt_", prompt)?;
+        let temp_file = write_temp_file("oz_prompt_", prompt, ".txt")?;
         let prompt_path = temp_file.path().display().to_string();
 
         let (session_id, preexisting_conversation_id) = match resume {
@@ -246,11 +251,23 @@ impl ClaudeHarnessRunner {
         };
 
         let temp_system_prompt_file = system_prompt
-            .map(|sp| write_temp_file("oz_system_prompt_", sp))
+            .map(|sp| write_temp_file("oz_system_prompt_", sp, ".txt"))
             .transpose()?;
         let system_prompt_path = temp_system_prompt_file
             .as_ref()
             .map(|f| f.path().display().to_string());
+
+        let temp_mcp_config_file = (!resolved_mcp_servers.is_empty())
+            .then(|| {
+                let mcp_json = serialize_claude_mcp_config(resolved_mcp_servers)
+                    .map_err(AgentDriverError::ConfigBuildFailed)?;
+                write_temp_file("oz_mcp_config_", &mcp_json, ".json")
+            })
+            .transpose()?;
+        let mcp_config_path = temp_mcp_config_file
+            .as_ref()
+            .map(|f| f.path().display().to_string());
+
         let parent_bridge = task_id
             .map(|task_id| MessageBridge::new(task_id.to_string(), session_id))
             .transpose()
@@ -263,11 +280,13 @@ impl ClaudeHarnessRunner {
                 &session_id,
                 &prompt_path,
                 system_prompt_path.as_deref(),
+                mcp_config_path.as_deref(),
                 preexisting_conversation_id.is_some(),
             ),
             cli_name: cli_command.to_string(),
             _temp_prompt_file: temp_file,
             _temp_system_prompt_file: temp_system_prompt_file,
+            _temp_mcp_config_file: temp_mcp_config_file,
             client,
             server_api,
             terminal_driver,
@@ -541,7 +560,7 @@ async fn upload_transcript(
         .with_context(|| format!("Failed to get transcript upload target for {conversation_id}"))?;
     upload_to_target(client.http_client(), &target, body).await
 }
-fn prepare_claude_environment_config(
+pub(crate) fn prepare_claude_environment_config(
     working_dir: &Path,
     resolved_env_vars: &HashMap<OsString, OsString>,
 ) -> Result<()> {
@@ -679,6 +698,74 @@ fn suffix_of(key: &str) -> Option<&str> {
     }
 }
 
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ClaudeMcpConfig {
+    mcp_servers: HashMap<String, ClaudeMcpServerEntry>,
+}
+
+#[derive(Serialize)]
+#[serde(tag = "type")]
+enum ClaudeMcpServerEntry {
+    #[serde(rename = "stdio")]
+    Stdio {
+        command: String,
+        args: Vec<String>,
+        #[serde(skip_serializing_if = "HashMap::is_empty")]
+        env: HashMap<String, String>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        cwd: Option<String>,
+    },
+    #[serde(rename = "http")]
+    Http {
+        url: String,
+        #[serde(skip_serializing_if = "HashMap::is_empty")]
+        headers: HashMap<String, String>,
+    },
+}
+
+impl ClaudeMcpServerEntry {
+    fn from_json_mcp_server(server: &JSONMCPServer) -> Self {
+        match &server.transport_type {
+            JSONTransportType::CLIServer {
+                command,
+                args,
+                env,
+                working_directory,
+            } => Self::Stdio {
+                command: command.clone(),
+                args: args.clone(),
+                env: env.clone(),
+                cwd: working_directory.clone(),
+            },
+            JSONTransportType::SSEServer { url, headers } => Self::Http {
+                url: url.clone(),
+                headers: headers.clone(),
+            },
+        }
+    }
+}
+
+/// Serialize resolved MCP servers into Claude Code's `--mcp-config` JSON format.
+///
+/// Produces `{ "mcpServers": { "name": { "type": "stdio"|"http", ... }, ... } }`.
+pub(crate) fn serialize_claude_mcp_config(
+    servers: &HashMap<String, JSONMCPServer>,
+) -> Result<String> {
+    let config = ClaudeMcpConfig {
+        mcp_servers: servers
+            .iter()
+            .map(|(name, server)| {
+                (
+                    name.clone(),
+                    ClaudeMcpServerEntry::from_json_mcp_server(server),
+                )
+            })
+            .collect(),
+    };
+    serde_json::to_string_pretty(&config).context("Failed to serialize Claude MCP config")
+}
+
 #[cfg(test)]
 #[path = "claude_code_tests.rs"]
 mod tests;

app/src/ai/agent_sdk/driver/harness/claude_code/wake_driver.rs

@@ -218,6 +218,7 @@ impl ClaudeHarness {
             &remote.session_id,
             &prompt_path.display().to_string(),
             None,
+            None,
             true,
         );
         let env_vars = local_wake_task_env_vars(Some(&task_id), parent_run_id.as_deref());