feat: support mcp_servers in config.toml (#829)

This adds initial support for MCP servers in the style of Claude Desktop
and Cursor. Note this PR is the bare minimum to get things working end
to end: all configured MCP servers are launched every time Codex is run,
there is no recovery for MCP servers that crash, etc.

(Also, I took some shortcuts to change some fields of `Session` to be
`pub(crate)`, which also means there are circular deps between
`codex.rs` and `mcp_tool_call.rs`, but I will clean that up in a
subsequent PR.)

`codex-rs/README.md` is updated as part of this PR to explain how to use
this feature. There is a bit of plumbing to route the new settings from
`Config` to the business logic in `codex.rs`. The most significant
chunks for new code are in `mcp_connection_manager.rs` (which defines
the `McpConnectionManager` struct) and `mcp_tool_call.rs`, which is
responsible for tool calls.

This PR also introduces new `McpToolCallBegin` and `McpToolCallEnd`
event types to the protocol, but does not add any handlers for them.
(See https://github.com/openai/codex/pull/836 for initial usage.)

To test, I added the following to my `~/.codex/config.toml`:

```toml
# Local build of https://github.com/hideya/mcp-server-weather-js
[mcp_servers.weather]
command = "/Users/mbolin/code/mcp-server-weather-js/dist/index.js"
args = []
```

And then I ran the following:

```
codex-rs$ cargo run --bin codex exec 'what is the weather in san francisco'
[2025-05-06T22:40:05] Task started: 1
[2025-05-06T22:40:18] Agent message: Here’s the latest National Weather Service forecast for San Francisco (downtown, near 37.77° N, 122.42° W):

This Afternoon (Tue):
• Sunny, high near 69 °F
• West-southwest wind around 12 mph

Tonight:
• Partly cloudy, low around 52 °F
• SW wind 7–10 mph
...
```

Note that Codex itself is not able to make network calls, so it would
not normally be able to get live weather information like this. However,
the weather MCP is [currently] not run under the Codex sandbox, so it is
able to hit `api.weather.gov` and fetch current weather information.

---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/829).
* #836
* __->__ #829

codex-rs/core/src/mcp_connection_manager.rs

@@ -0,0 +1,162 @@
+//! Connection manager for Model Context Protocol (MCP) servers.
+//!
+//! The [`McpConnectionManager`] owns one [`codex_mcp_client::McpClient`] per
+//! configured server (keyed by the *server name*). It offers convenience
+//! helpers to query the available tools across *all* servers and returns them
+//! in a single aggregated map using the fully-qualified tool name
+//! `"<server><MCP_TOOL_NAME_DELIMITER><tool>"` as the key.
+
+use std::collections::HashMap;
+
+use anyhow::anyhow;
+use anyhow::Context;
+use anyhow::Result;
+use codex_mcp_client::McpClient;
+use mcp_types::Tool;
+use tokio::task::JoinSet;
+use tracing::info;
+
+use crate::mcp_server_config::McpServerConfig;
+
+/// Delimiter used to separate the server name from the tool name in a fully
+/// qualified tool name.
+///
+/// OpenAI requires tool names to conform to `^[a-zA-Z0-9_-]+$`, so we must
+/// choose a delimiter from this character set.
+const MCP_TOOL_NAME_DELIMITER: &str = "__OAI_CODEX_MCP__";
+
+fn fully_qualified_tool_name(server: &str, tool: &str) -> String {
+    format!("{server}{MCP_TOOL_NAME_DELIMITER}{tool}")
+}
+
+pub(crate) fn try_parse_fully_qualified_tool_name(fq_name: &str) -> Option<(String, String)> {
+    let (server, tool) = fq_name.split_once(MCP_TOOL_NAME_DELIMITER)?;
+    if server.is_empty() || tool.is_empty() {
+        return None;
+    }
+    Some((server.to_string(), tool.to_string()))
+}
+
+/// A thin wrapper around a set of running [`McpClient`] instances.
+#[derive(Default)]
+pub(crate) struct McpConnectionManager {
+    /// Server-name -> client instance.
+    ///
+    /// The server name originates from the keys of the `mcp_servers` map in
+    /// the user configuration.
+    clients: HashMap<String, std::sync::Arc<McpClient>>,
+
+    /// Fully qualified tool name -> tool instance.
+    tools: HashMap<String, Tool>,
+}
+
+impl McpConnectionManager {
+    /// Spawn a [`McpClient`] for each configured server.
+    ///
+    /// * `mcp_servers` – Map loaded from the user configuration where *keys*
+    ///   are human-readable server identifiers and *values* are the spawn
+    ///   instructions.
+    pub async fn new(mcp_servers: HashMap<String, McpServerConfig>) -> Result<Self> {
+        // Early exit if no servers are configured.
+        if mcp_servers.is_empty() {
+            return Ok(Self::default());
+        }
+
+        // Spin up all servers concurrently.
+        let mut join_set = JoinSet::new();
+
+        // Spawn tasks to launch each server.
+        for (server_name, cfg) in mcp_servers {
+            // TODO: Verify server name: require `^[a-zA-Z0-9_-]+$`?
+            join_set.spawn(async move {
+                let McpServerConfig { command, args, env } = cfg;
+                let client_res = McpClient::new_stdio_client(command, args, env).await;
+
+                (server_name, client_res)
+            });
+        }
+
+        let mut clients: HashMap<String, std::sync::Arc<McpClient>> =
+            HashMap::with_capacity(join_set.len());
+        while let Some(res) = join_set.join_next().await {
+            let (server_name, client_res) = res?;
+
+            let client = client_res
+                .with_context(|| format!("failed to spawn MCP server `{server_name}`"))?;
+
+            clients.insert(server_name, std::sync::Arc::new(client));
+        }
+
+        let tools = list_all_tools(&clients).await?;
+
+        Ok(Self { clients, tools })
+    }
+
+    /// Returns a single map that contains **all** tools. Each key is the
+    /// fully-qualified name for the tool.
+    pub fn list_all_tools(&self) -> HashMap<String, Tool> {
+        self.tools.clone()
+    }
+
+    /// Invoke the tool indicated by the (server, tool) pair.
+    pub async fn call_tool(
+        &self,
+        server: &str,
+        tool: &str,
+        arguments: Option<serde_json::Value>,
+    ) -> Result<mcp_types::CallToolResult> {
+        let client = self
+            .clients
+            .get(server)
+            .ok_or_else(|| anyhow!("unknown MCP server '{server}'"))?
+            .clone();
+
+        client
+            .call_tool(tool.to_string(), arguments)
+            .await
+            .with_context(|| format!("tool call failed for `{server}/{tool}`"))
+    }
+}
+
+/// Query every server for its available tools and return a single map that
+/// contains **all** tools. Each key is the fully-qualified name for the tool.
+pub async fn list_all_tools(
+    clients: &HashMap<String, std::sync::Arc<McpClient>>,
+) -> Result<HashMap<String, Tool>> {
+    let mut join_set = JoinSet::new();
+
+    // Spawn one task per server so we can query them concurrently. This
+    // keeps the overall latency roughly at the slowest server instead of
+    // the cumulative latency.
+    for (server_name, client) in clients {
+        let server_name_cloned = server_name.clone();
+        let client_clone = client.clone();
+        join_set.spawn(async move {
+            let res = client_clone.list_tools(None).await;
+            (server_name_cloned, res)
+        });
+    }
+
+    let mut aggregated: HashMap<String, Tool> = HashMap::with_capacity(join_set.len());
+
+    while let Some(join_res) = join_set.join_next().await {
+        let (server_name, list_result) = join_res?;
+        let list_result = list_result?;
+
+        for tool in list_result.tools {
+            // TODO(mbolin): escape tool names that contain invalid characters.
+            let fq_name = fully_qualified_tool_name(&server_name, &tool.name);
+            if aggregated.insert(fq_name.clone(), tool).is_some() {
+                panic!("tool name collision for '{fq_name}': suspicious");
+            }
+        }
+    }
+
+    info!(
+        "aggregated {} tools from {} servers",
+        aggregated.len(),
+        clients.len()
+    );
+
+    Ok(aggregated)
+}