Reuse MCP connections across runtime refreshes (#34952)

## Why

Refreshing MCP runtime state should not restart an unchanged, ready server or
relist its tools.

## What changed

- Reconcile refreshed MCP configuration against the published connection set
  and reuse connections whose transport, environment, authentication, OAuth
  credentials, and client capabilities are unchanged.
- Keep tool filters, timeouts, metadata, and plugin provenance in the published
  server view so those settings can change without reconnecting.
- Update elicitation authority in place for reused connections, and reconnect
  when connection-defining inputs or live OAuth credentials change.

## Testing

Added coverage for unchanged-server reuse, view-only and elicitation-policy
updates, connection identity changes, OAuth credential changes, and avoiding
redundant tool listing.

GitOrigin-RevId: f04f5db5fbdde127b6a14f6aa9673112c0b557e7
This commit is contained in:
jif authored and copyberry committed 2026-07-23 14:55:31 +00:00
1 parent 808d3c2702
commit e19e65317a
26 files changed
+1954 -811

No files matched your search

@@ -16,7 +16,7 @@ impl McpConnectionSet {
let failures = async {
let mut failures = Vec::new();
for server_name in &self.required_servers {
let Some(async_managed_client) = self.clients.get(server_name).cloned() else {
let Some(view) = self.servers.get(server_name) else {
failures.push(McpStartupFailure {
server: server_name.clone(),
error: format!("required MCP server `{server_name}` was not initialized"),
@@ -24,7 +24,7 @@ impl McpConnectionSet {
continue;
};
match async_managed_client.client().await {
match view.connection.client().await {
Ok(_) => {}
Err(error) => failures.push(McpStartupFailure {
server: server_name.clone(),
@@ -0,0 +1,183 @@
use std::collections::HashMap;
use std::time::Duration;
use anyhow::Context;
use anyhow::Result;
use anyhow::anyhow;
use rmcp::model::ListResourcesResult;
use rmcp::model::PaginatedRequestParams;
use rmcp::model::ReadResourceRequestParams;
use rmcp::model::ReadResourceResult;
use rmcp::model::Resource;
use rmcp::model::ResourceTemplate;
use tokio::task::JoinSet;
use tracing::warn;
use super::McpConnectionSet;
use crate::rmcp_client::ManagedClient;
impl McpConnectionSet {
/// Returns resources from servers selected by `include_server`.
pub async fn list_all_resources(
&self,
include_server: impl Fn(&str) -> bool,
) -> HashMap<String, Vec<Resource>> {
let mut join_set = JoinSet::new();
for (server_name, view) in self
.servers
.iter()
.filter(|(server_name, _)| include_server(server_name))
{
let server_name = server_name.clone();
let Ok(managed_client) = view.connection.client().await else {
continue;
};
let timeout = view.tool_timeout;
let client = managed_client.client;
join_set.spawn(async move {
let mut resources = Vec::new();
let mut cursor: Option<String> = None;
loop {
let params = cursor.as_ref().map(|next| {
PaginatedRequestParams::default().with_cursor(Some(next.clone()))
});
let response = match client.list_resources(params, timeout).await {
Ok(result) => result,
Err(error) => return (server_name, Err(error)),
};
resources.extend(response.resources);
match response.next_cursor {
Some(next) if cursor.as_ref() == Some(&next) => {
return (
server_name,
Err(anyhow!("resources/list returned duplicate cursor")),
);
}
Some(next) => cursor = Some(next),
None => return (server_name, Ok(resources)),
}
}
});
}
let mut resources = HashMap::new();
while let Some(result) = join_set.join_next().await {
match result {
Ok((server_name, Ok(server_resources))) => {
resources.insert(server_name, server_resources);
}
Ok((server_name, Err(error))) => {
warn!("Failed to list resources for MCP server '{server_name}': {error:#}");
}
Err(error) => {
warn!("Task panic when listing resources for MCP server: {error:#}");
}
}
}
resources
}
/// Returns resource templates from servers selected by `include_server`.
pub async fn list_all_resource_templates(
&self,
include_server: impl Fn(&str) -> bool,
) -> HashMap<String, Vec<ResourceTemplate>> {
let mut join_set = JoinSet::new();
for (server_name, view) in self
.servers
.iter()
.filter(|(server_name, _)| include_server(server_name))
{
let server_name = server_name.clone();
let Ok(managed_client) = view.connection.client().await else {
continue;
};
let timeout = view.tool_timeout;
let client = managed_client.client;
join_set.spawn(async move {
let mut templates = Vec::new();
let mut cursor: Option<String> = None;
loop {
let params = cursor.as_ref().map(|next| {
PaginatedRequestParams::default().with_cursor(Some(next.clone()))
});
let response = match client.list_resource_templates(params, timeout).await {
Ok(result) => result,
Err(error) => return (server_name, Err(error)),
};
templates.extend(response.resource_templates);
match response.next_cursor {
Some(next) if cursor.as_ref() == Some(&next) => {
return (
server_name,
Err(anyhow!(
"resources/templates/list returned duplicate cursor"
)),
);
}
Some(next) => cursor = Some(next),
None => return (server_name, Ok(templates)),
}
}
});
}
let mut templates = HashMap::new();
while let Some(result) = join_set.join_next().await {
match result {
Ok((server_name, Ok(server_templates))) => {
templates.insert(server_name, server_templates);
}
Ok((server_name, Err(error))) => {
warn!(
"Failed to list resource templates for MCP server '{server_name}': {error:#}"
);
}
Err(error) => {
warn!("Task panic when listing resource templates for MCP server: {error:#}");
}
}
}
templates
}
pub async fn list_resources(
&self,
server: &str,
params: Option<PaginatedRequestParams>,
) -> Result<ListResourcesResult> {
let (managed, timeout) = self.client_by_name(server).await?;
managed
.client
.list_resources(params, timeout)
.await
.with_context(|| format!("resources/list failed for `{server}`"))
}
pub async fn read_resource(
&self,
server: &str,
params: ReadResourceRequestParams,
) -> Result<ReadResourceResult> {
let (managed, timeout) = self.client_by_name(server).await?;
let uri = params.uri.clone();
managed
.client
.read_resource(params, timeout)
.await
.with_context(|| format!("resources/read failed for `{server}` ({uri})"))
}
async fn client_by_name(&self, name: &str) -> Result<(ManagedClient, Option<Duration>)> {
let view = self
.servers
.get(name)
.ok_or_else(|| anyhow!("unknown MCP server '{name}'"))?;
let client = view
.connection
.client()
.await
.context("failed to get client")?;
Ok((client, view.tool_timeout))
}
}
@@ -0,0 +1,115 @@
use std::collections::HashMap;
use anyhow::Result;
use async_channel::Sender;
use codex_api::SharedAuthProvider;
use codex_config::McpServerAuth;
use codex_config::McpServerConfig;
use codex_config::McpServerTransportConfig;
use codex_protocol::protocol::Event;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::McpStartupFailureReason;
use codex_protocol::protocol::McpStartupUpdateEvent;
use codex_rmcp_client::McpAuthState;
use codex_rmcp_client::McpLoginRequirement;
use crate::mcp::CODEX_APPS_MCP_SERVER_NAME;
use crate::rmcp_client::DEFAULT_STARTUP_TIMEOUT;
use crate::rmcp_client::StartupOutcomeError;
use crate::server::EffectiveMcpServer;
/// Makes ChatGPT authentication available to servers that explicitly opt in.
pub(super) fn chatgpt_auth_provider_for_server(
server: &EffectiveMcpServer,
chatgpt_auth_provider: Option<SharedAuthProvider>,
) -> Option<SharedAuthProvider> {
if !matches!(&server.config().auth, McpServerAuth::ChatGpt) {
return None;
}
chatgpt_auth_provider
}
pub(super) fn should_share_codex_apps_tools_cache(
server_name: &str,
uses_env_bearer_token: bool,
) -> bool {
server_name == CODEX_APPS_MCP_SERVER_NAME && !uses_env_bearer_token
}
pub(super) async fn emit_update(
submit_id: &str,
tx_event: &Sender<Event>,
update: McpStartupUpdateEvent,
) -> Result<(), async_channel::SendError<Event>> {
tx_event
.send(Event {
id: submit_id.to_string(),
msg: EventMsg::McpStartupUpdate(update),
})
.await
}
pub(super) fn mcp_startup_failure_reason(
auth_state: Option<McpAuthState>,
error: &StartupOutcomeError,
) -> Option<McpStartupFailureReason> {
if !error.is_authentication_required() {
return None;
}
match auth_state {
Some(McpAuthState::LoggedOut(McpLoginRequirement::Reauthentication)) => {
Some(McpStartupFailureReason::ReauthenticationRequired)
}
Some(
McpAuthState::Unsupported
| McpAuthState::LoggedOut(McpLoginRequirement::Login)
| McpAuthState::BearerToken
| McpAuthState::OAuth,
)
| None => None,
}
}
pub(super) fn mcp_init_error_display(
server_name: &str,
config: Option<&McpServerConfig>,
error: &StartupOutcomeError,
) -> String {
if let Some(McpServerTransportConfig::StreamableHttp {
url,
bearer_token_env_var,
http_headers,
..
}) = config.map(|config| &config.transport)
&& url == "https://api.githubcopilot.com/mcp/"
&& bearer_token_env_var.is_none()
&& http_headers.as_ref().map(HashMap::is_empty).unwrap_or(true)
{
format!(
"GitHub MCP does not support OAuth. Log in by adding a personal access token (https://github.com/settings/personal-access-tokens) to your environment and config.toml:\n[mcp_servers.{server_name}]\nbearer_token_env_var = CODEX_GITHUB_PERSONAL_ACCESS_TOKEN"
)
} else if matches!(
error,
StartupOutcomeError::Failed { error, .. } if error.contains("Auth required")
) {
format!(
"The {server_name} MCP server is not logged in. Run `codex mcp login {server_name}`."
)
} else if matches!(
error,
StartupOutcomeError::Failed { error, .. }
if error.contains("request timed out")
|| error.contains("timed out handshaking with MCP server")
|| error.contains("MCP client startup timed out")
) {
let startup_timeout_secs = config
.and_then(|config| config.startup_timeout_sec)
.unwrap_or(DEFAULT_STARTUP_TIMEOUT)
.as_secs();
format!(
"MCP client for `{server_name}` timed out after {startup_timeout_secs} seconds. Add or adjust `startup_timeout_sec` in your config.toml:\n[mcp_servers.{server_name}]\nstartup_timeout_sec = XX"
)
} else {
format!("MCP client for `{server_name}` failed to start: {error:#}")
}
}
@@ -12,31 +12,63 @@ use tracing::trace;
use tracing::trace_span;
use super::McpConnectionSet;
use super::McpServerMetadata;
use crate::binding::McpBinding;
use crate::binding::PreparedMcpCall;
use crate::binding_clients::McpBindingClients;
use crate::codex_apps::prepare_openai_file_params_for_model;
use crate::mcp::CODEX_APPS_MCP_SERVER_NAME;
use crate::rmcp_client::CODEX_APPS_REFRESH_DURATION_METRIC;
use crate::rmcp_client::MCP_TOOLS_LIST_DURATION_METRIC;
use crate::rmcp_client::ManagedClient;
use crate::rmcp_client::list_tools_for_client_uncached;
use crate::rmcp_client::prepare_codex_apps_tools_for_model;
use crate::runtime::emit_duration;
use crate::tools::ToolInfo;
use crate::tools::filter_tools;
use crate::tools::normalize_tools_for_model_with_prefix;
const MCP_UI_META_KEY: &str = "ui";
const MCP_UI_VISIBILITY_META_KEY: &str = "visibility";
const MCP_UI_MODEL_VISIBILITY: &str = "model";
/// Returns whether a tool may be included in model-facing tool declarations.
///
/// Tools without visibility metadata remain visible. Tools with visibility
/// metadata are hidden unless they explicitly include `model`.
///
/// <https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx#resource-discovery>
pub fn tool_is_model_visible(tool: &ToolInfo) -> bool {
let Some(visibility) = tool
.tool
.meta
.as_deref()
.and_then(|meta| meta.get(MCP_UI_META_KEY))
.and_then(serde_json::Value::as_object)
.and_then(|ui| ui.get(MCP_UI_VISIBILITY_META_KEY))
.and_then(serde_json::Value::as_array)
else {
return true;
};
visibility
.iter()
.any(|target| target.as_str() == Some(MCP_UI_MODEL_VISIBILITY))
}
impl McpConnectionSet {
/// Returns all tools with model-visible names normalized.
#[instrument(level = "trace", skip_all, fields(mcp_server_count = self.clients.len()))]
#[instrument(level = "trace", skip_all, fields(mcp_server_count = self.servers.len()))]
pub async fn list_all_tools(&self) -> Vec<ToolInfo> {
let mut tools = Vec::new();
let mut available_server_count = 0;
let mut unavailable_server_count = 0;
for (server_name, managed_client) in &self.clients {
managed_client.reconnect_failed_startup().await;
let has_cached_tools = managed_client.has_cached_tools();
let startup_complete = managed_client.startup_complete.load(Ordering::Acquire);
for (server_name, view) in &self.servers {
view.connection.client.reconnect_failed_startup().await;
let has_cached_tools = view.connection.client.has_cached_tools();
let startup_complete = view
.connection
.client
.startup_complete
.load(Ordering::Acquire);
let catalog_override = if server_name == CODEX_APPS_MCP_SERVER_NAME {
self.codex_apps_tools_override.read().await.clone()
} else {
@@ -44,8 +76,14 @@ impl McpConnectionSet {
};
let Some(server_tools) = async {
match catalog_override {
Some(tools) => Some(managed_client.prepare_tools(tools)),
None => managed_client.listed_tools().await,
Some(tools) => {
let tools = filter_tools(tools, &view.tool_filter);
Some(prepare_codex_apps_tools_for_model(
tools,
&self.tool_plugin_provenance,
))
}
None => view.listed_tools(&self.tool_plugin_provenance).await,
}
}
.instrument(trace_span!(
@@ -69,7 +107,7 @@ impl McpConnectionSet {
tools.extend(
server_tools
.into_iter()
.map(|tool| self.with_server_metadata(tool)),
.map(|tool| Self::with_server_metadata(tool, &view.metadata)),
);
}
let tools = normalize_tools_for_model_with_prefix(tools, self.prefix_mcp_tool_names);
@@ -94,27 +132,41 @@ impl McpConnectionSet {
let revision = self.tool_catalog_revision.read().await;
let mut listed_tools = Vec::new();
let mut clients = std::collections::HashMap::new();
for (server_name, managed_client) in &self.clients {
for (server_name, view) in &self.servers {
if !view
.connection
.client
.startup_complete
.load(Ordering::Acquire)
{
let _ = view.connection.client.client().await;
}
view.connection.client.reconnect_failed_startup().await;
let Ok(mut client) = view.connection.client.client().await else {
trace!(server_name = %server_name, "omitting MCP server without an exact ready client");
continue;
};
client.tool_timeout = view.tool_timeout;
let catalog_override = if server_name == CODEX_APPS_MCP_SERVER_NAME {
self.codex_apps_tools_override.read().await.clone()
} else {
None
};
let Some((client, server_tools)) = managed_client
.capture_ready_client_and_tools(catalog_override)
.await
else {
trace!(
server_name = %server_name,
"omitting MCP server without an exact ready client"
);
continue;
let server_tools = catalog_override.unwrap_or_else(|| client.tools.clone());
let server_tools = filter_tools(server_tools, &view.tool_filter);
let server_tools = if server_name == CODEX_APPS_MCP_SERVER_NAME {
prepare_codex_apps_tools_for_model(server_tools, &self.tool_plugin_provenance)
} else {
crate::rmcp_client::prepare_regular_mcp_tools_for_model(
server_tools,
&self.tool_plugin_provenance,
)
};
clients.insert(server_name.clone(), client);
clients.insert(server_name.clone(), Arc::new(client));
listed_tools.extend(
server_tools
.into_iter()
.map(|tool| self.with_server_metadata(tool)),
.map(|tool| Self::with_server_metadata(tool, &view.metadata)),
);
}
let clients = Arc::new(McpBindingClients::new(clients));
@@ -165,6 +217,7 @@ impl McpConnectionSet {
tool_catalog_revision: u64,
) -> Option<PreparedMcpCall> {
let server_name = &tool_info.server_name;
let view = self.servers.get(server_name)?;
Some(PreparedMcpCall::new(
Arc::clone(self),
client,
@@ -172,7 +225,7 @@ impl McpConnectionSet {
tool_catalog_revision,
Arc::clone(&self.tool_catalog_revision),
tool_info.clone(),
self.server_metadata.get(server_name)?.clone(),
view.metadata.clone(),
self.plugin_id_for_mcp_server_name(server_name)
.map(str::to_string),
self.is_selected_plugin_mcp_server(server_name),
@@ -184,13 +237,15 @@ impl McpConnectionSet {
clippy::await_holding_invalid_type,
reason = "catalog publication must remain serialized with captured tool calls"
)]
pub(crate) async fn hard_refresh_codex_apps_tools_cache(&self) -> Result<Vec<ToolInfo>> {
pub async fn hard_refresh_codex_apps_tools_cache(&self) -> Result<Vec<ToolInfo>> {
let _refresh = self.codex_apps_refresh_lock.lock().await;
let refresh_start = Instant::now();
let managed_client = self
.clients
let view = self
.servers
.get(CODEX_APPS_MCP_SERVER_NAME)
.ok_or_else(|| anyhow!("unknown MCP server '{CODEX_APPS_MCP_SERVER_NAME}'"))?
.ok_or_else(|| anyhow!("unknown MCP server '{CODEX_APPS_MCP_SERVER_NAME}'"))?;
let managed_client = view
.connection
.client()
.await
.context("failed to get client")?;
@@ -208,7 +263,7 @@ impl McpConnectionSet {
/*is_codex_apps_mcp_server*/ true,
/*codex_apps_refresh_trigger*/ "explicit",
&managed_client.client,
managed_client.tool_timeout,
view.tool_timeout,
managed_client.server_instructions.as_deref(),
)
.await
@@ -237,12 +292,12 @@ impl McpConnectionSet {
list_start.elapsed(),
&[("cache", "miss")],
);
let tools = filter_tools(tools, &managed_client.tool_filter)
.into_iter()
.map(|mut tool| {
prepare_openai_file_params_for_model(&mut tool);
self.with_server_metadata(tool)
});
let tools = prepare_codex_apps_tools_for_model(
filter_tools(tools, &view.tool_filter),
&self.tool_plugin_provenance,
)
.into_iter()
.map(|tool| Self::with_server_metadata(tool, &view.metadata));
let tools = normalize_tools_for_model_with_prefix(tools, self.prefix_mcp_tool_names);
emit_duration(
CODEX_APPS_REFRESH_DURATION_METRIC,
@@ -252,13 +307,7 @@ impl McpConnectionSet {
Ok(tools)
}
fn with_server_metadata(&self, mut tool: ToolInfo) -> ToolInfo {
let Some(metadata) = self.server_metadata.get(&tool.server_name) else {
tool.supports_parallel_tool_calls = false;
tool.server_origin = None;
return tool;
};
fn with_server_metadata(mut tool: ToolInfo, metadata: &McpServerMetadata) -> ToolInfo {
tool.supports_parallel_tool_calls = metadata.supports_parallel_tool_calls;
tool.server_origin = metadata
.origin