Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Honor MCP tool-list changes within a turn (#54656)

jif0df4aa67781a
diff --git a/codex-rs/codex-mcp/src/client_tool_catalog.rs b/codex-rs/codex-mcp/src/client_tool_catalog.rs
index 0501f1c782..233d835256 100644
--- a/codex-rs/codex-mcp/src/client_tool_catalog.rs
+++ b/codex-rs/codex-mcp/src/client_tool_catalog.rs
@@ -4,21 +4,32 @@
//! Only active readers, calls, and frozen model bindings pin earlier snapshots.
//! Explicit refreshes publish after calls using this client's current revision finish.
//! Equivalent shared publications preserve calls, but explicit refreshes invalidate them.
+//! Ordinary servers coalesce list-change notifications and publish only a stable listing.
+//! Notifications update discovery without waiting for admitted calls to finish.
+//! Failed refreshes retain the last catalog and share a short retry cooldown.
use std::collections::HashSet;
use std::future::Future;
use std::sync::Arc;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+use anyhow::Context;
use anyhow::Result;
+use anyhow::bail;
use codex_connectors::ConnectorRuntimeSnapshot;
+use codex_rmcp_client::ToolListRevision;
use tokio::sync::Mutex;
use tokio::sync::RwLock;
use tokio::sync::RwLockReadGuard;
use tokio::sync::watch;
+use tokio::time::Instant;
use crate::tools::ToolInfo;
type ToolCatalogUpdates = watch::Receiver<Option<Arc<ConnectorRuntimeSnapshot<ToolInfo>>>>;
+const NOTIFICATION_REFRESH_COOLDOWN: Duration = Duration::from_secs(5);
/// The exact Apps catalog returned by an awaited refresh of one published runtime.
pub struct CodexAppsToolSnapshot {
@@ -31,8 +42,12 @@ pub struct CodexAppsToolSnapshot {
pub(crate) struct ClientToolCatalog {
current: RwLock<CatalogState>,
- /// Serialize fetches without blocking calls against the current catalog.
- refresh_lock: Mutex<()>,
+ /// Explicit refreshes still wait for call preparation and execution.
+ calls: RwLock<()>,
+ /// Serialize fetches and retain the next retry time after failure or cancellation.
+ refresh_lock: Mutex<Option<Instant>>,
+ /// Starts at zero so notifications during the initial listing stay pending.
+ listed_notification_revision: AtomicU64,
}
struct CatalogState {
@@ -81,7 +96,9 @@ impl ClientToolCatalog {
last_refresh_revision: 0,
source,
}),
- refresh_lock: Mutex::new(()),
+ refresh_lock: Mutex::new(None),
+ calls: RwLock::new(()),
+ listed_notification_revision: AtomicU64::new(0),
}
}
@@ -139,6 +156,66 @@ impl ClientToolCatalog {
}
}
+ pub(crate) fn notifications_current(&self, notifications: &ToolListRevision) -> bool {
+ self.listed_notification_revision.load(Ordering::Acquire) == notifications.current()
+ }
+
+ /// Refresh ordinary server catalogs, coalescing concurrent readers. Never mark a
+ /// listing current if another notification arrived while fetching its pages.
+ /// Retry once; persistent churn stays pending until the retry cooldown expires.
+ #[expect(
+ clippy::await_holding_invalid_type,
+ reason = "refreshes must remain serialized through fetching and catalog publication"
+ )]
+ pub(crate) async fn refresh_after_notifications<F, Fut>(
+ &self,
+ notifications: &ToolListRevision,
+ timeout: Duration,
+ mut fetch: F,
+ ) -> Result<()>
+ where
+ F: FnMut() -> Fut,
+ Fut: Future<Output = Result<Vec<ToolInfo>>>,
+ {
+ if self.notifications_current(notifications) {
+ return Ok(());
+ }
+ let deadline = Instant::now() + timeout;
+ let mut retry_after = tokio::time::timeout_at(deadline, self.refresh_lock.lock())
+ .await
+ .context("MCP tool catalog refresh timed out")?;
+ if self.notifications_current(notifications)
+ || retry_after.is_some_and(|deadline| Instant::now() < deadline)
+ {
+ return Ok(());
+ }
+ // Also bound retries if the caller cancels this future during the fetch.
+ *retry_after = Some(deadline + NOTIFICATION_REFRESH_COOLDOWN);
+ let result = tokio::time::timeout_at(deadline, async {
+ for _ in 0..2 {
+ let revision = notifications.current();
+ let tools = fetch().await;
+ let mut current = self.current.write().await;
+ if notifications.current() != revision {
+ continue;
+ }
+ current.source = CatalogSource::Local(tools?.into());
+ current.revision += 1;
+ self.listed_notification_revision
+ .store(revision, Ordering::Release);
+ return Ok(());
+ }
+ bail!("MCP tool list changed during catalog refresh")
+ })
+ .await
+ .context("MCP tool catalog refresh timed out")
+ .and_then(std::convert::identity);
+ *retry_after = result
+ .is_err()
+ .then(|| Instant::now() + NOTIFICATION_REFRESH_COOLDOWN);
+ result
+ }
+
/// Serialize fetching and publication, leaving the current catalog usable during the fetch.
/// The publication callback runs alongside the exact-client update under the write lock.
#[expect(
@@ -153,6 +230,7 @@ impl ClientToolCatalog {
{
let _refresh = self.refresh_lock.lock().await;
let (tools, context) = fetch().await?;
+ let _calls = self.calls.write().await;
let mut current = self.current.write().await;
let result = publish(&tools, context);
match &mut current.source {
@@ -172,7 +250,8 @@ impl ClientToolCatalog {
Ok(result)
}
- /// Reject stale calls before preparation and hold catalog authority until execution finishes.
+ /// Reject stale calls before preparation. Explicit refreshes wait for execution;
+ /// ordinary list-change notifications may publish while an admitted call runs.
#[expect(
clippy::await_holding_invalid_type,
reason = "catalog publication must wait for call preparation and execution"
@@ -186,6 +265,7 @@ impl ClientToolCatalog {
F: FnOnce() -> Fut,
Fut: Future<Output = R>,
{
+ let _calls = self.calls.read().await;
let (current, snapshot) = self.read_current().await;
if current.last_refresh_revision > expected.revision
|| (snapshot.revision != expected.revision
@@ -193,6 +273,13 @@ impl ClientToolCatalog {
{
return None;
}
+ let current = match current.source {
+ CatalogSource::Local(_) => {
+ drop(current);
+ None
+ }
+ CatalogSource::Live { .. } => Some(current),
+ };
let result = run().await;
drop(current);
Some(result)
diff --git a/codex-rs/codex-mcp/src/connection_manager.rs b/codex-rs/codex-mcp/src/connection_manager.rs
index 0f70d060bd..8d2c471252 100644
--- a/codex-rs/codex-mcp/src/connection_manager.rs
+++ b/codex-rs/codex-mcp/src/connection_manager.rs
@@ -185,6 +185,8 @@ struct McpServerView {
tool_filter: ToolFilter,
tool_timeout: Option<Duration>,
catalog_item_limit: usize,
+ refresh_tool_list: bool,
+ refresh_timeout: Duration,
}
impl McpServerView {
@@ -210,11 +212,44 @@ impl McpServerView {
}
}
+ async fn refresh_notified_catalog(&self, server_name: &str, client: &ManagedClient) {
+ if !self.refresh_tool_list || self.connection.client.is_codex_apps_mcp_server {
+ return;
+ }
+ let timeout = self.refresh_timeout;
+ let result = client
+ .tool_catalog
+ .refresh_after_notifications(&client.client.tool_list_revision(), timeout, || {
+ crate::rmcp_client::list_tools_for_client_uncached(
+ server_name,
+ /*is_codex_apps_mcp_server*/ false,
+ "list_changed",
+ &client.client,
+ Some(timeout),
+ self.catalog_item_limit,
+ client.server_instructions.as_deref(),
+ )
+ })
+ .await;
+ if result.is_err() {
+ tracing::warn!(
+ server_name,
+ "MCP tool catalog refresh failed; retaining the previous catalog"
+ );
+ }
+ }
+
async fn listed_tools(
&self,
+ server_name: &str,
tool_plugin_context: &ToolPluginContext,
) -> Result<Vec<ToolInfo>, StartupOutcomeError> {
- let tools = self.connection.client.listed_tools().await?;
+ let tools = if let Some(client) = self.connection.client.ready_client() {
+ self.refresh_notified_catalog(server_name, &client).await;
+ client.listed_tools().await
+ } else {
+ self.connection.client.listed_tools().await?
+ };
let tools = filter_tools(tools, &self.tool_filter);
Ok(if self.connection.client.is_codex_apps_mcp_server {
prepare_codex_apps_tools_for_model(tools, tool_plugin_context)
@@ -494,6 +529,7 @@ impl McpConnectionSet {
};
if let Some(previous_view) =
reusable_previous.and_then(|previous| previous.servers.get(&server_name))
+ && previous_view.refresh_tool_list == config.mcp_tool_list_changed
{
let connection = Arc::clone(&previous_view.connection);
let reusable_pending_startup = connection.identity.as_ref()
@@ -539,6 +575,8 @@ impl McpConnectionSet {
connection,
protocol_mode,
startup_readiness: configured_config.startup_readiness,
+ refresh_tool_list: config.mcp_tool_list_changed,
+ refresh_timeout: startup_timeout,
metadata,
tool_filter: configured_tool_filter,
tool_timeout: configured_tool_timeout,
@@ -597,7 +635,7 @@ impl McpConnectionSet {
}
}
let cancel_token = startup_cancellation_token.child_token();
- let tool_catalog_cache_context = if server_name == CODEX_APPS_MCP_SERVER_NAME
+ let mut tool_catalog_cache_context = if server_name == CODEX_APPS_MCP_SERVER_NAME
|| server.requires_read_only_mcp_tools()
{
None
@@ -617,6 +655,9 @@ impl McpConnectionSet {
} else {
None
};
+ if let Some(context) = &mut tool_catalog_cache_context {
+ context.track_tool_list_changes = config.mcp_tool_list_changed;
+ }
let has_runtime_auth = runtime_auth_provider.is_some();
let async_managed_client = AsyncManagedClient::new(
server_name.clone(),
@@ -677,6 +718,8 @@ impl McpConnectionSet {
}),
protocol_mode,
startup_readiness: configured_config.startup_readiness,
+ refresh_tool_list: config.mcp_tool_list_changed,
+ refresh_timeout: startup_timeout,
metadata,
tool_filter: configured_tool_filter,
tool_timeout: configured_tool_timeout,
diff --git a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs
index 45cea49bb0..711e747fba 100644
--- a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs
+++ b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs
@@ -171,7 +171,13 @@ impl McpConnectionSet {
}
return None;
};
- if client.client.is_closed().await {
+ if client.client.is_closed().await
+ || (view.refresh_tool_list
+ && !view.connection.client.is_codex_apps_mcp_server
+ && !client
+ .tool_catalog
+ .notifications_current(&client.client.tool_list_revision()))
+ {
return None;
}
let revision = client.tool_catalog.read(|catalog| catalog.revision).await;
@@ -213,7 +219,7 @@ impl McpConnectionSet {
.startup_complete
.load(Ordering::Acquire);
let server_tools = view
- .listed_tools(&self.tool_plugin_context)
+ .listed_tools(server_name, &self.tool_plugin_context)
.instrument(trace_span!(
"list_tools_for_server",
server_name = %server_name,
@@ -392,6 +398,7 @@ impl McpConnectionSet {
trace!(server_name = %server_name, "omitting MCP server without an exact ready client");
return None;
};
+ view.refresh_notified_catalog(server_name, &client).await;
client.tool_timeout = view.tool_timeout;
let snapshot = client.tool_catalog.read(Arc::new).await;
let server_tools = snapshot.tools.to_vec();
diff --git a/codex-rs/codex-mcp/src/connection_manager_tests.rs b/codex-rs/codex-mcp/src/connection_manager_tests.rs
index 482f346557..758e6419dc 100644
--- a/codex-rs/codex-mcp/src/connection_manager_tests.rs
+++ b/codex-rs/codex-mcp/src/connection_manager_tests.rs
@@ -134,6 +134,8 @@ impl McpConnectionSet {
self.servers.insert(
name,
McpServerView {
+ refresh_tool_list: true,
+ refresh_timeout: DEFAULT_STARTUP_TIMEOUT,
tool_filter: ToolFilter::default(),
protocol_mode: crate::McpProtocolMode::Legacy,
startup_readiness: Default::default(),
@@ -339,7 +341,25 @@ struct MutableToolsServer {
impl ServerHandler for MutableToolsServer {
fn get_info(&self) -> ServerConfig {
- ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
+ ServerConfig::new(
+ ServerCapabilities::builder()
+ .enable_tools()
+ .enable_tool_list_changed()
+ .build(),
+ )
+ }
+
+ async fn call_tool(
+ &self,
+ _request: rmcp::model::CallToolRequestParams,
+ context: RequestContext<RoleServer>,
+ ) -> Result<rmcp::model::CallToolResponse, rmcp::ErrorData> {
+ context
+ .peer
+ .notify_tool_list_changed()
+ .await
+ .map_err(|error| McpError::internal_error(error.to_string(), None))?;
+ Ok(rmcp::model::CallToolResult::success(Vec::new()).into())
}
async fn list_tools(
@@ -2632,6 +2652,16 @@ async fn tool_catalog_cache_sanitizes_tools_and_tracks_environment_generation()
None
);
+ let fallback = first_context.current_tools();
+ let mut tracking_context = first_context.clone();
+ tracking_context.track_tool_list_changes = true;
+ assert!(!tracking_context.has_tools());
+ assert_eq!(tracking_context.current_tools_or(fallback), None);
+ assert!(
+ first_context.has_tools(),
+ "disabled refresh preserves cached startup"
+ );
+
drop(first_environment);
replace_environment("ws://127.0.0.1:2");
assert!(first_environment_weak.upgrade().is_none());
@@ -5235,6 +5265,8 @@ async fn manager_with_reusable_ready_server(
manager.servers.insert(
"docs".to_string(),
McpServerView {
+ refresh_tool_list: true,
+ refresh_timeout: DEFAULT_STARTUP_TIMEOUT,
protocol_mode: crate::McpProtocolMode::Legacy,
startup_readiness: Default::default(),
connection: Arc::new(McpServerConnection {
@@ -5591,7 +5623,7 @@ async fn refreshed_catalog_follows_reused_client_without_mutating_old_bindings()
Ok(())
}
-#[tokio::test]
+#[tokio::test(start_paused = true)]
async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> anyhow::Result<()> {
let tools = Arc::new(tokio::sync::RwLock::new(vec![Tool::new(
"old_search",
@@ -5640,7 +5672,7 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a
.await?;
let managed_client = ManagedClient {
_auth_change_notifications: None,
- client,
+ client: Arc::clone(&client),
server_info: create_test_server_info("Mutable tools"),
tool_catalog: Arc::new(ClientToolCatalog::new(initial_tools, /*updates*/ None)),
tool_timeout: None,
@@ -5649,7 +5681,7 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a
codex_apps_tools_cache_context: None,
};
let runtime_context = reusable_server_runtime_context();
- let config = reusable_server_config("http://127.0.0.1:1");
+ let mut config = reusable_server_config("http://127.0.0.1:1");
let approval_policy = Constrained::allow_any(AskForApproval::OnRequest);
let permission_profile = Constrained::allow_any(PermissionProfile::default());
let mut previous = McpConnectionSet::new_uninitialized(
@@ -5661,6 +5693,8 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a
previous.servers.insert(
"docs".to_string(),
McpServerView {
+ refresh_tool_list: true,
+ refresh_timeout: DEFAULT_STARTUP_TIMEOUT,
protocol_mode: crate::McpProtocolMode::Legacy,
startup_readiness: Default::default(),
connection: Arc::new(McpServerConnection {
@@ -5690,6 +5724,35 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a
);
let previous = Arc::new(previous);
let old_step = capture_binding(&previous).await;
+ let cache = McpToolCatalogCache::default();
+ let mut cache = cache
+ .context(
+ "docs",
+ &config,
+ &runtime_context,
+ /*resolved_environment*/ None,
+ (
+ &ElicitationCapability::default(),
+ &ClientMcpExtensions::default(),
+ ),
+ Some((
+ previous.servers["docs"]
+ .connection
+ .identity
+ .as_ref()
+ .unwrap(),
+ crate::McpProtocolMode::Legacy,
+ /*agent_plugin*/ false,
+ )),
+ )
+ .expect("cache context");
+ cache.track_tool_list_changes = true;
+ let mut ticket = cache.begin_fetch();
+ ticket.tool_list_revision = Some(client.tool_list_revision());
+ cache.publish_if_newest(ticket, old_step.tools());
+ assert!(cache.has_tools());
+ // Reused connections must use the new view's timeout, not their startup timeout.
+ config.startup_timeout_sec = Some(Duration::from_secs(1));
*tools.write().await = vec![Tool::new(
"new_search",
"new search",
@@ -5724,6 +5787,91 @@ async fn reconciliation_reuses_connection_without_relisting_regular_tools() -> a
.collect::<Vec<_>>(),
vec!["old_search".to_string()]
);
+ let prepared = old_step
+ .prepare_call("docs", "old_search")
+ .expect("prepared call");
+ let (entered, started) = tokio::sync::oneshot::channel();
+ let (release, resumed) = tokio::sync::oneshot::channel();
+ let call = tokio::spawn(async move {
+ prepared
+ .call_with_preparation(/*requested_timeout*/ None, || async {
+ entered.send(()).unwrap();
+ resumed.await?;
+ anyhow::bail!("stop after preparation")
+ })
+ .await
+ });
+ started.await?;
+ // Refresh must not wait for this admitted call or lose healthy resource endpoints.
+ client
+ .call_tool(
+ "notify".into(),
+ /*arguments*/ None,
+ /*meta*/ None,
+ /*timeout*/ None,
+ )
+ .await?;
+ assert!(
+ reconciled
+ .stable_catalog_revisions(&[], &HashSet::new())
+ .await
+ .is_none()
+ );
+ assert!(!cache.has_tools());
+ assert_eq!(
+ cache.current_tools_or(Some(old_step.tools().to_vec())),
+ None
+ );
+ let failed = tokio::time::timeout(Duration::from_secs(3), capture_binding(&reconciled))
+ .await
+ .expect("refresh must use the reconciled timeout");
+ assert_eq!(failed.tools(), old_step.tools());
+ assert_eq!(
+ failed.list_all_resources(|_| true).await,
+ HashMap::from([("docs".to_string(), vec![])])
+ );
+ assert_eq!(
+ failed.list_all_resource_templates(|_| true).await,
+ HashMap::from([("docs".to_string(), vec![])])
+ );
+ let retry_started = tokio::time::Instant::now();
+ let retry = capture_binding(&reconciled).await;
+ assert_eq!(retry.tools(), old_step.tools());
+ assert_eq!(retry_started.elapsed(), Duration::ZERO);
+ block_tool_listing.store(false, Ordering::Release);
+ tokio::time::advance(Duration::from_secs(5)).await;
+ let (first, second) = tokio::time::timeout(Duration::from_secs(1), async {
+ tokio::join!(capture_binding(&previous), capture_binding(&reconciled))
+ })
+ .await
+ .expect("notification refresh must not wait for a running call");
+ release.send(()).unwrap();
+ call.await?.expect_err("test stops before dispatch");
+ assert_eq!(first.tools(), second.tools());
+ assert_eq!(
+ model_tool_names(first.tools()),
+ HashSet::from([ToolName::namespaced("mcp__docs", "new_search"),])
+ );
+ assert_eq!(
+ old_step.tools(),
+ new_step.tools(),
+ "old bindings remain immutable"
+ );
+ assert!(
+ reconciled
+ .prepare_call_for_tool(Arc::clone(old_step.config()), &old_step.tools()[0],)
+ .await
+ .is_none()
+ );
+ let refreshed = previous.test_client("docs").client().await?;
+ assert_eq!(
+ refreshed
+ .tool_catalog
+ .read(|catalog| catalog.revision)
+ .await,
+ 1,
+ "concurrent readers publish one refresh on their shared client"
+ );
Ok(())
}
diff --git a/codex-rs/codex-mcp/src/mcp/mod.rs b/codex-rs/codex-mcp/src/mcp/mod.rs
index 137f1bff04..ba791d514f 100644
--- a/codex-rs/codex-mcp/src/mcp/mod.rs
+++ b/codex-rs/codex-mcp/src/mcp/mod.rs
@@ -186,6 +186,8 @@ pub struct McpConfig {
pub non_prefixed_mcp_tool_servers: Vec<String>,
/// Protocol mode for servers other than the host-owned Codex Apps registration.
pub protocol_mode: McpProtocolMode,
+ /// Refresh ordinary server catalogs after tools/list_changed notifications.
+ pub mcp_tool_list_changed: bool,
/// Independent protocol mode for the trusted, HTTP Codex Apps registration.
pub host_owned_apps_protocol_mode: McpProtocolMode,
/// Client-side elicitation capabilities advertised during MCP initialization.
diff --git a/codex-rs/codex-mcp/src/mcp/mod_tests.rs b/codex-rs/codex-mcp/src/mcp/mod_tests.rs
index 8332b18048..b0bea88b78 100644
--- a/codex-rs/codex-mcp/src/mcp/mod_tests.rs
+++ b/codex-rs/codex-mcp/src/mcp/mod_tests.rs
@@ -113,6 +113,7 @@ pub(crate) fn test_mcp_config(codex_home: PathBuf) -> McpConfig {
prefix_mcp_tool_names: true,
non_prefixed_mcp_tool_servers: Vec::new(),
protocol_mode: McpProtocolMode::Legacy,
+ mcp_tool_list_changed: true,
host_owned_apps_protocol_mode: McpProtocolMode::Legacy,
client_elicitation_capability: ElicitationCapability::default(),
mcp_server_catalog: ResolvedMcpCatalog::default(),
diff --git a/codex-rs/codex-mcp/src/rmcp_client.rs b/codex-rs/codex-mcp/src/rmcp_client.rs
index ae46bd180a..7e9f4964ff 100644
--- a/codex-rs/codex-mcp/src/rmcp_client.rs
+++ b/codex-rs/codex-mcp/src/rmcp_client.rs
@@ -1046,10 +1046,15 @@ async fn start_server_task(
(None, None) => tools.into(),
_ => unreachable!("Codex Apps fetch ticket requires cache context"),
};
- if let (Some(cache_context), Some(fetch_ticket)) = (
+ if let (Some(cache_context), Some(mut fetch_ticket)) = (
tool_catalog_cache_context.as_ref(),
tool_catalog_fetch_ticket,
) {
+ if cache_context.track_tool_list_changes {
+ // A notification makes this session's startup catalog ineligible for reuse.
+ // Discovery can be session-specific, so do not cache later live catalogs.
+ fetch_ticket.tool_list_revision = Some(client.tool_list_revision());
+ }
cache_context.publish_if_newest(fetch_ticket, &client_tools);
}
if is_codex_apps_mcp_server || tool_catalog_cache_context.is_some() {
diff --git a/codex-rs/codex-mcp/src/tool_catalog_cache.rs b/codex-rs/codex-mcp/src/tool_catalog_cache.rs
index d3608afe98..60989beb4b 100644
--- a/codex-rs/codex-mcp/src/tool_catalog_cache.rs
+++ b/codex-rs/codex-mcp/src/tool_catalog_cache.rs
@@ -17,6 +17,7 @@ use codex_config::McpServerConfig;
use codex_config::McpServerTransportConfig;
use codex_exec_server::Environment;
use codex_protocol::mcp::ClientMcpExtensions;
+use codex_rmcp_client::ToolListRevision;
use lru::LruCache;
use rmcp::model::ElicitationCapability;
use sha1::Digest;
@@ -70,14 +71,17 @@ struct OptionalStartupDeadline {
struct ToolCatalogSnapshot {
tools: Vec<ToolInfo>,
published_at: Instant,
+ tool_list_revision: Option<ToolListRevision>,
}
#[derive(Clone)]
pub(crate) struct McpToolCatalogCacheContext {
+ pub(crate) track_tool_list_changes: bool,
entry: Arc<ToolCatalogCacheEntry>,
}
pub(crate) struct McpToolCatalogFetchTicket {
+ pub(crate) tool_list_revision: Option<ToolListRevision>,
generation: u64,
}
@@ -102,7 +106,10 @@ impl McpToolCatalogCache {
let entry = lock_unpoisoned(&self.entries)
.get_or_insert(identity, || Arc::new(ToolCatalogCacheEntry::default()))
.clone();
- Some(McpToolCatalogCacheContext { entry })
+ Some(McpToolCatalogCacheContext {
+ entry,
+ track_tool_list_changes: false,
+ })
}
}
@@ -116,6 +123,16 @@ impl Default for ToolCatalogCacheEntry {
}
impl McpToolCatalogCacheContext {
+ fn accepts_snapshot(&self, snapshot: &ToolCatalogSnapshot) -> bool {
+ // Enabling refresh must not reuse a catalog published without notification tracking.
+ snapshot
+ .tool_list_revision
+ .as_ref()
+ .map_or(!self.track_tool_list_changes, |revision| {
+ revision.current() == 0
+ })
+ }
+
pub(crate) fn has_tools(&self) -> bool {
self.current_revision_if(|_| true).is_some()
}
@@ -129,6 +146,7 @@ impl McpToolCatalogCacheContext {
let state = lock_unpoisoned(&self.entry.state);
let snapshot = state.snapshot.as_ref()?;
(!state.disabled_by_server
+ && self.accepts_snapshot(snapshot)
&& !snapshot.tools.is_empty()
&& snapshot.published_at.elapsed() <= TOOL_CATALOG_CACHE_TTL
&& accepts_tools(&snapshot.tools))
@@ -142,10 +160,10 @@ impl McpToolCatalogCacheContext {
) -> Instant {
let mut state = lock_unpoisoned(&self.entry.state);
if state.disabled_by_server
- || state
- .snapshot
- .as_ref()
- .is_some_and(|snapshot| snapshot.published_at.elapsed() <= TOOL_CATALOG_CACHE_TTL)
+ || state.snapshot.as_ref().is_some_and(|snapshot| {
+ self.accepts_snapshot(snapshot)
+ && snapshot.published_at.elapsed() <= TOOL_CATALOG_CACHE_TTL
+ })
{
return default_deadline;
}
@@ -175,7 +193,12 @@ impl McpToolCatalogCacheContext {
fallback: Option<Vec<ToolInfo>>,
) -> Option<Vec<ToolInfo>> {
let state = lock_unpoisoned(&self.entry.state);
- if state.disabled_by_server {
+ if state.disabled_by_server
+ || state
+ .snapshot
+ .as_ref()
+ .is_some_and(|snapshot| !self.accepts_snapshot(snapshot))
+ {
return None;
}
state
@@ -188,6 +211,7 @@ impl McpToolCatalogCacheContext {
pub(crate) fn begin_fetch(&self) -> McpToolCatalogFetchTicket {
McpToolCatalogFetchTicket {
+ tool_list_revision: None,
generation: self
.entry
.next_fetch_generation
@@ -219,6 +243,7 @@ impl McpToolCatalogCacheContext {
state.snapshot = Some(ToolCatalogSnapshot {
tools,
published_at: Instant::now(),
+ tool_list_revision: ticket.tool_list_revision,
});
}
}
diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json
index 44f9a381b8..2331f64ed6 100644
--- a/codex-rs/core/config.schema.json
+++ b/codex-rs/core/config.schema.json
@@ -1039,6 +1039,9 @@
"mcp_oauth_refresh_coordination": {
"type": "boolean"
},
+ "mcp_tool_list_changed": {
+ "type": "boolean"
+ },
"memories": {
"type": "boolean"
},
@@ -7422,6 +7425,9 @@
"mcp_oauth_refresh_coordination": {
"type": "boolean"
},
+ "mcp_tool_list_changed": {
+ "type": "boolean"
+ },
"memories": {
"type": "boolean"
},
diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs
index 20939cf80b..2b99142597 100644
--- a/codex-rs/core/src/config/mod.rs
+++ b/codex-rs/core/src/config/mod.rs
@@ -1881,6 +1881,7 @@ impl Config {
xaa_enabled: self.features.enabled(Feature::UseXaa)
&& self.mcp_enterprise_managed_auth.is_some(),
mcp_oauth_credentials_store_mode: self.mcp_oauth_credentials_store_mode,
+ mcp_tool_list_changed: self.features.enabled(Feature::McpToolListChanged),
oauth_refresh_mode: if self.features.enabled(Feature::McpOAuthRefreshCoordination) {
McpOAuthRefreshMode::Coordinated
} else {
diff --git a/codex-rs/core/tests/suite/rmcp_client.rs b/codex-rs/core/tests/suite/rmcp_client.rs
index 2c0fcf270b..bd5592620f 100644
--- a/codex-rs/core/tests/suite/rmcp_client.rs
+++ b/codex-rs/core/tests/suite/rmcp_client.rs
@@ -1068,6 +1068,144 @@ async fn future_environment_mcp_policy_applies_on_the_next_turn() -> anyhow::Res
Ok(())
}
+#[test_case(Some("discovery"), true; "notification_during_listing")]
+#[test_case(Some("pagination"), true; "notification_invalidates_cursor")]
+#[test_case(None, false; "disabled")]
+#[test_case(Some("startup"), true; "notification_during_startup")]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn discovers_and_calls_new_mcp_tool_in_same_turn(
+ invalidation: Option<&'static str>,
+ enabled: bool,
+) -> anyhow::Result<()> {
+ skip_if_no_network!(Ok(()));
+ skip_if_wine_exec!(Ok(()), "requires a Windows test_stdio_server binary");
+ mcp_tool_discovery_scenario(ToolMode::Direct, invalidation, enabled)
+ .await
+ .map(|_| ())
+}
+
+pub(super) async fn mcp_tool_discovery_scenario(
+ tool_mode: ToolMode,
+ invalidation: Option<&'static str>,
+ enabled: bool,
+) -> anyhow::Result<Vec<responses::ResponsesRequest>> {
+ let server = responses::start_mock_server().await;
+ let command = remote_aware_stdio_server_bin()?;
+ let test = test_codex()
+ .with_config(move |config| {
+ config.code_mode.disable_in_process_fallback = true;
+ config
+ .features
+ .enable(Feature::CodeModeHost)
+ .expect("enable Code Mode host");
+ if enabled {
+ config
+ .features
+ .enable(Feature::McpToolListChanged)
+ .expect("enable tool-list refresh");
+ }
+ let mut env = HashMap::from([
+ ("MCP_TEST_DISCOVER_TOOLS".to_string(), "1".to_string()),
+ ("MCP_TEST_VALUE".to_string(), "discovered".to_string()),
+ ]);
+ if let Some(phase) = invalidation {
+ env.insert("MCP_TEST_INVALIDATE_LISTING".to_string(), phase.to_string());
+ }
+ insert_mcp_server(
+ config,
+ "discovery",
+ stdio_transport(command, Some(env), Vec::new()),
+ TestMcpServerOptions {
+ environment_id: remote_aware_environment_id(),
+ ..Default::default()
+ },
+ );
+ })
+ .with_model_info_override("gpt-5.5", move |model| {
+ model.tool_mode = Some(tool_mode);
+ model.supports_search_tool = false;
+ model.use_responses_lite = false;
+ })
+ .build_with_auto_env(&server)
+ .await?;
+ wait_for_mcp_server(&test.codex, "discovery").await?;
+ let mut mocks = Vec::new();
+ for (call_id, tool, arguments) in [
+ ("discover", "search_tools", r#"{"message":"find echo"}"#),
+ ("invoke", "echo", r#"{"message":"hello"}"#),
+ ] {
+ if !enabled && tool == "echo" {
+ break;
+ }
+ let call = if tool_mode == ToolMode::CodeModeOnly {
+ responses::ev_custom_tool_call(
+ call_id,
+ "exec",
+ &format!("text(await tools.mcp__discovery__{tool}({arguments}));"),
+ )
+ } else {
+ responses::ev_function_call_with_namespace(call_id, "mcp__discovery", tool, arguments)
+ };
+ mocks.push(
+ responses::mount_sse_once(
+ &server,
+ responses::sse(vec![
+ responses::ev_response_created(call_id),
+ call,
+ responses::ev_completed(call_id),
+ ]),
+ )
+ .await,
+ );
+ }
+ mocks.push(responses::mount_sse_once(&server, responses::sse_completed("done")).await);
+ test.submit_turn("Discover the echo tool, then call it with hello.")
+ .await?;
+ let requests = mocks
+ .iter()
+ .map(responses::ResponseMock::single_request)
+ .collect::<Vec<_>>();
+ if tool_mode == ToolMode::Direct {
+ assert!(
+ requests[0]
+ .tool_by_name("mcp__discovery", "search_tools")
+ .is_some()
+ );
+ assert_eq!(
+ requests[0].tool_by_name("mcp__discovery", "echo").is_some(),
+ invalidation == Some("startup")
+ );
+ if !enabled {
+ assert_eq!(
+ requests[1].body_json()["tools"],
+ requests[0].body_json()["tools"]
+ );
+ return Ok(requests);
+ }
+ assert!(requests[1].tool_by_name("mcp__discovery", "echo").is_some());
+ let output = requests[2]
+ .function_call_output_text("invoke")
+ .expect("echo output");
+ let (_, payload) = output
+ .split_once("\nOutput:\n")
+ .expect("wrapped MCP output");
+ assert_eq!(
+ serde_json::from_str::<Value>(payload)?,
+ json!({
+ "echo": "ECHOING: hello", "env": "discovered",
+ })
+ );
+ } else {
+ assert!(
+ requests[2]
+ .custom_tool_call_output("invoke")
+ .to_string()
+ .contains("ECHOING: hello")
+ );
+ }
+ Ok(requests)
+}
+
#[test_case("rmcp", "mcp__rmcp"; "simple name")]
#[test_case("npm:@scope/package.name", "mcp__npm__scope_package_name"; "npm name")]
#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rs
index 59894c49f8..d630531538 100644
--- a/codex-rs/core/tests/suite/scenarios.rs
+++ b/codex-rs/core/tests/suite/scenarios.rs
@@ -328,6 +328,58 @@ async fn code_mode_mcp_schema_limits_preserve_explicit_overrides() -> Result<()>
Ok(())
}
+#[test_case::test_case(ToolMode::Direct; "direct")]
+#[test_case::test_case(ToolMode::CodeModeOnly; "code_mode")]
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn mcp_tool_discovery_in_same_turn(tool_mode: ToolMode) -> Result<()> {
+ skip_if_no_network!(Ok(()));
+ skip_if_wine_exec!(Ok(()), "requires a Windows test_stdio_server binary");
+ let requests = super::rmcp_client::mcp_tool_discovery_scenario(
+ tool_mode, /*invalidation*/ None, /*enabled*/ true,
+ )
+ .await?;
+ let mut bodies = requests
+ .iter()
+ .map(core_test_support::responses::ResponsesRequest::body_json)
+ .collect::<Vec<_>>();
+ // Cargo and Bazel can serialize embedded JSON in different key orders.
+ // Normalize each output text before snapshot truncation and hashing.
+ for body in &mut bodies {
+ for item in body["input"].as_array_mut().expect("request input") {
+ if item["type"] != "function_call_output" && item["type"] != "custom_tool_call_output" {
+ continue;
+ }
+ let parts = match &mut item["output"] {
+ serde_json::Value::Array(parts) => parts
+ .iter_mut()
+ .map(|part| &mut part["text"])
+ .collect::<Vec<_>>(),
+ output => vec![output],
+ };
+ for part in parts {
+ let text = part.as_str().expect("text output");
+ let mut normalized = context_snapshot::normalize_json_lines(text);
+ if text.ends_with('\n') {
+ normalized.push('\n');
+ }
+ *part = normalized.into();
+ }
+ }
+ }
+ let entries = bodies.iter().map(SnapshotEntry::body).collect::<Vec<_>>();
+ insta::assert_snapshot!(
+ format!("mcp_tool_discovery_{tool_mode:?}"),
+ context_snapshot::format_context_snapshot(
+ "An MCP discovery call announces a new tool, which is called in the same turn.",
+ &entries,
+ &ContextSnapshotOptions::default()
+ .rewrite_known_segments()
+ .include_request_settings(),
+ )
+ );
+ Ok(())
+}
+
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn astra_asks_an_async_question_and_receives_the_answer_while_working() -> Result<()> {
skip_if_no_network!(Ok(()));
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap
new file mode 100644
index 0000000000..33f69ec0bf
--- /dev/null
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_CodeModeOnly.snap
@@ -0,0 +1,56 @@
+---
+source: core/tests/suite/scenarios.rs
+expression: "context_snapshot::format_context_snapshot(\"An MCP discovery call announces a new tool, which is called in the same turn.\",\n&entries,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"
+---
+Scenario: An MCP discovery call announces a new tool, which is called in the same turn.
+
+## Window 1
+Settings:
+ include: ["reasoning.encrypted_content"]
+ model: "gpt-5.5"
+ parallel_tool_calls: true
+ prompt_cache_key: "<PROMPT_CACHE_KEY 1>"
+ reasoning: {"effort":"medium"}
+ store: false
+ stream: true
+ text: {"verbosity":"low"}
+ tool_choice: "auto"
+ tools (4; hash=c0d891b72dfe19c6):
+ - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=5f9adb37c23e2085
+ - function/wait: Waits on a yielded `exec` cell and returns new output or completion. - Use `wait` only after `exe...; args=[cell_id, max_tokens, terminate, yield_time_ms]; hash=6692d8f6c55be489
+ - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6
+ - web_search; hash=e214d4db1bc49e89
+-- request 1 (request) --
+00:message/developer:
+ <MODEL_INSTRUCTIONS>
+01:message/developer:
+ <PERMISSIONS_INSTRUCTIONS>
+02:message/user:
+ <ENVIRONMENT_CONTEXT>
+03:message/user:
+ Discover the echo tool, then call it with hello.
+
+## Window 2 (after request 1)
+Settings: relative to window 1
+ tools (4; hash=f74ded0dd31e19a8):
+ ~ custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=f36b0269278fcd9d
+-- request 2 (request) --
+00:message/developer:
+ <MODEL_INSTRUCTIONS>
+01:message/developer:
+ <PERMISSIONS_INSTRUCTIONS>
+02:message/user:
+ <ENVIRONMENT_CONTEXT>
+03:message/user:
+ Discover the echo tool, then call it with hello.
+04:custom_tool_call/exec:text(await tools.mcp__discovery__search_tools({"message":"find echo"}));
+05:custom_tool_call_output:Script completed
+ Wall time <DURATION> seconds
+ Output:
+ | {"content":[],"isError":false,"structuredContent":{"tools":[{"annotations":{"readOnlyHint":true},"descri...l"}]}},"required":["echo","env"],"type":"object"}}]}} [hash=df19b4e245e07b80]
+-- request 3 (request) --
+06:custom_tool_call/exec:text(await tools.mcp__discovery__echo({"message":"hello"}));
+07:custom_tool_call_output:Script completed
+ Wall time <DURATION> seconds
+ Output:
+ | {"content":[],"isError":false,"structuredContent":{"echo":"ECHOING: hello","env":"discovered"}}
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap
new file mode 100644
index 0000000000..e91e191f32
--- /dev/null
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_tool_discovery_Direct.snap
@@ -0,0 +1,69 @@
+---
+source: core/tests/suite/scenarios.rs
+expression: "context_snapshot::format_context_snapshot(\"An MCP discovery call announces a new tool, which is called in the same turn.\",\n&entries,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"
+---
+Scenario: An MCP discovery call announces a new tool, which is called in the same turn.
+
+## Window 1
+Settings:
+ include: ["reasoning.encrypted_content"]
+ model: "gpt-5.5"
+ parallel_tool_calls: true
+ prompt_cache_key: "<PROMPT_CACHE_KEY 1>"
+ reasoning: {"effort":"medium"}
+ store: false
+ stream: true
+ text: {"verbosity":"low"}
+ tool_choice: "auto"
+ tools (11; hash=d2c3940ebd5ac02b):
+ - function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5
+ - function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2
+ - function/list_mcp_resources: Lists resources provided by MCP servers. Resources allow servers to share data that provides cont...; args=[cursor, server]; hash=6792edaff13561bd
+ - function/list_mcp_resource_templates: Lists resource templates provided by MCP servers. Parameterized resource templates allow servers ...; args=[cursor, server]; hash=60f17c90ef7a4ebb
+ - function/read_mcp_resource: Read a specific resource from an MCP server given the server name and resource URI.; args=[server, uri]; hash=24246896b39008ae
+ - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6
+ - custom/apply_patch: The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the pat...; hash=dea9f12b0111a4ba
+ - function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[detail, path]; hash=3b766d5bdec5d50e
+ - namespace/multi_agent_v1: Tools for spawning and managing sub-agents.; hash=2327142bda177c50
+ - function/close_agent
+ - function/resume_agent
+ - function/send_input
+ - function/spawn_agent
+ - function/wait_agent
+ - namespace/mcp__discovery: Use these tools to exercise the rmcp test server.; hash=55b000f43c815c1f
+ - function/search_tools
+ - web_search; hash=e214d4db1bc49e89
+-- request 1 (request) --
+00:message/developer:
+ <MODEL_INSTRUCTIONS>
+01:message/developer:
+ <PERMISSIONS_INSTRUCTIONS>
+02:message/user:
+ <ENVIRONMENT_CONTEXT>
+03:message/user:
+ Discover the echo tool, then call it with hello.
+
+## Window 2 (after request 1)
+Settings: relative to window 1
+ tools (11; hash=21579d54e22ad527):
+ ~ namespace/mcp__discovery: Use these tools to exercise the rmcp test server.; hash=66db79539eaf6be3
+ - function/echo
+ - function/search_tools
+-- request 2 (request) --
+00:message/developer:
+ <MODEL_INSTRUCTIONS>
+01:message/developer:
+ <PERMISSIONS_INSTRUCTIONS>
+02:message/user:
+ <ENVIRONMENT_CONTEXT>
+03:message/user:
+ Discover the echo tool, then call it with hello.
+04:function_call/mcp__discovery.search_tools:{"message":"find echo"}
+05:function_call_output:Wall time: <DURATION> seconds
+ Output:
+ {"tools":[{"annotations":{"readOnlyHint":true},"description":"Echo back the provided message and include...ll"}]}},"required":["echo","env"],"type":"object"}}]} [hash=ccb6ffb1e2ec3a2c]
+-- request 3 (request) --
+06:function_call/mcp__discovery.echo:{"message":"hello"}
+07:function_call_output:Wall time: <DURATION> seconds
+ Output:
+ {"echo":"ECHOING: hello","env":"discovered"}
diff --git a/codex-rs/features/src/lib.rs b/codex-rs/features/src/lib.rs
index 4030e8e4a6..edcaa6ffd7 100644
--- a/codex-rs/features/src/lib.rs
+++ b/codex-rs/features/src/lib.rs
@@ -249,6 +249,8 @@ pub enum Feature {
EnableMcpApps,
/// Enable MCP protocol version 2026-07-28 support.
Mcp20260728,
+ /// Honor ordinary MCP server tool-list notifications within a turn.
+ McpToolListChanged,
/// Enable MCP protocol version 2026-07-28 for the host-owned Codex Apps server.
CodexAppsMcp20260728,
/// Let RMCP coordinate OAuth refresh through the configured credential store.
@@ -1546,6 +1548,12 @@ pub const FEATURES: &[FeatureSpec] = &[
stage: Stage::UnderDevelopment,
default_enabled: false,
},
+ FeatureSpec {
+ id: Feature::McpToolListChanged,
+ key: "mcp_tool_list_changed",
+ stage: Stage::UnderDevelopment,
+ default_enabled: false,
+ },
FeatureSpec {
id: Feature::CodexAppsMcp20260728,
key: "codex_apps_mcp_2026_07_28",
diff --git a/codex-rs/rmcp-client/src/bin/test_stdio_server.rs b/codex-rs/rmcp-client/src/bin/test_stdio_server.rs
index 70a5476ee9..8ea0150268 100644
--- a/codex-rs/rmcp-client/src/bin/test_stdio_server.rs
+++ b/codex-rs/rmcp-client/src/bin/test_stdio_server.rs
@@ -43,6 +43,8 @@ struct TestToolServer {
resources: Arc<Vec<Resource>>,
resource_templates: Arc<Vec<ResourceTemplate>>,
supports_openai_form_elicitation: Arc<AtomicBool>,
+ tools_discovered: Arc<AtomicBool>,
+ invalidated_listing: Arc<AtomicBool>,
}
const MEMO_URI: &str = "memo://codex/example-note";
@@ -181,6 +183,8 @@ impl TestToolServer {
resources: Arc::new(resources),
resource_templates: Arc::new(resource_templates),
supports_openai_form_elicitation: Arc::new(AtomicBool::new(false)),
+ tools_discovered: Arc::default(),
+ invalidated_listing: Arc::default(),
}
}
@@ -559,7 +563,7 @@ impl ServerHandler for TestToolServer {
fn list_tools(
&self,
request: Option<PaginatedRequestParams>,
- _context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
+ context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
) -> impl std::future::Future<Output = Result<ListToolsResult, McpError>> + Send + '_ {
let tools = self.tools.clone();
async move {
@@ -572,6 +576,49 @@ impl ServerHandler for TestToolServer {
.get_or_insert_with(MetaObject::new)
.insert("ui".to_string(), json!({ "visibility": ["app"] }));
}
+ if std::env::var_os("MCP_TEST_DISCOVER_TOOLS").is_some() {
+ tools.retain(|tool| tool.name == "echo");
+ let mut search = tools[0].clone();
+ search.name = Cow::Borrowed("search_tools");
+ search.description = Some(Cow::Borrowed("Discover the echo tool."));
+ let discovered = self.tools_discovered.load(Ordering::Acquire);
+ if !discovered {
+ tools.clear();
+ }
+ let invalidation = std::env::var("MCP_TEST_INVALIDATE_LISTING");
+ let cursor = request.as_ref().and_then(|request| request.cursor.as_ref());
+ if invalidation.as_deref() == Ok("pagination")
+ && discovered
+ && !self.invalidated_listing.load(Ordering::Acquire)
+ && cursor.is_none()
+ {
+ return Ok(ListToolsResult {
+ tools: vec![search],
+ next_cursor: Some("stale".to_string()),
+ ..Default::default()
+ });
+ }
+ let invalidate = match invalidation.as_deref() {
+ Ok("startup") => !discovered,
+ Ok("discovery") => discovered,
+ Ok("pagination") => discovered && cursor.is_some(),
+ _ => false,
+ };
+ if invalidate && !self.invalidated_listing.swap(true, Ordering::AcqRel) {
+ self.tools_discovered.store(true, Ordering::Release);
+ // Invalidate an incomplete listing before returning its response.
+ tools.clear();
+ context
+ .peer
+ .notify_tool_list_changed()
+ .await
+ .map_err(|error| McpError::internal_error(error.to_string(), None))?;
+ if invalidation.as_deref() == Ok("pagination") {
+ return Err(McpError::invalid_params("expired tool-list cursor", None));
+ }
+ }
+ tools.insert(0, search);
+ }
let mut result = ListToolsResult::with_all_items(tools);
match (
std::env::var("MCP_TEST_TOOL_PAGINATION").as_deref(),
@@ -642,6 +689,14 @@ impl ServerHandler for TestToolServer {
context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
) -> Result<rmcp::model::CallToolResponse, McpError> {
match request.name.as_ref() {
+ "search_tools" if std::env::var_os("MCP_TEST_DISCOVER_TOOLS").is_some() => {
+ self.tools_discovered.store(true, Ordering::Release);
+ context.peer.notify_tool_list_changed().await
+ .map_err(|error| McpError::internal_error(error.to_string(), None))?;
+ Ok(Self::structured_result(json!({
+ "tools": self.tools.iter().filter(|tool| tool.name == "echo").collect::<Vec<_>>()
+ })))
+ }
"js" => {
let args = Self::parse_call_args::<JsArgs>(&request, "js")?;
if args.code == "nodeRepl.fail()" {
diff --git a/codex-rs/rmcp-client/src/lib.rs b/codex-rs/rmcp-client/src/lib.rs
index 54b46ef07c..615f64280e 100644
--- a/codex-rs/rmcp-client/src/lib.rs
+++ b/codex-rs/rmcp-client/src/lib.rs
@@ -31,6 +31,7 @@ mod service_error;
mod startup_error;
mod stdio_server_launcher;
mod tool_input;
+mod tool_list_changes;
mod trace_context;
mod user_verification;
mod utils;
@@ -103,4 +104,5 @@ pub use startup_error::is_authentication_required_error;
pub use stdio_server_launcher::ExecutorStdioServerLauncher;
pub use stdio_server_launcher::LocalStdioServerLauncher;
pub use stdio_server_launcher::StdioServerLauncher;
+pub use tool_list_changes::ToolListRevision;
pub use user_verification::UserVerificationReason;
diff --git a/codex-rs/rmcp-client/src/rmcp_client.rs b/codex-rs/rmcp-client/src/rmcp_client.rs
index 39dc2cdda4..552a80bc62 100644
--- a/codex-rs/rmcp-client/src/rmcp_client.rs
+++ b/codex-rs/rmcp-client/src/rmcp_client.rs
@@ -7,6 +7,7 @@ use std::sync::Arc;
use std::sync::Mutex as StdMutex;
use std::sync::OnceLock;
use std::sync::PoisonError;
+use std::sync::atomic::AtomicU64;
use std::sync::atomic::AtomicUsize;
use std::sync::atomic::Ordering;
use std::time::Duration;
@@ -99,6 +100,7 @@ use crate::stdio_server_launcher::StdioServerCommand;
use crate::stdio_server_launcher::StdioServerLauncher;
use crate::stdio_server_launcher::StdioServerProcessHandle;
use crate::stdio_server_launcher::StdioServerTransport;
+use crate::tool_list_changes::track_tool_list_changes;
use crate::utils::build_default_headers;
use codex_config::types::OAuthCredentialsStoreMode;
@@ -408,9 +410,15 @@ pub struct RmcpClient {
initialize_context: Mutex<Option<InitializeContext>>,
session_recovery_lock: Semaphore,
elicitation_pause_state: ElicitationPauseState,
+ tool_list_revision: Arc<AtomicU64>,
}
impl RmcpClient {
+ /// Tool catalog invalidation sequence, ordered before subsequent responses.
+ pub fn tool_list_revision(&self) -> crate::ToolListRevision {
+ crate::ToolListRevision(Arc::clone(&self.tool_list_revision))
+ }
+
/// Requests server-side read-only filtering and invocation checks for every tool request.
pub fn with_read_only_tools(mut self, requires_read_only_tools: bool) -> Self {
self.requires_read_only_tools = requires_read_only_tools;
@@ -448,6 +456,7 @@ impl RmcpClient {
initialize_context: Mutex::new(None),
session_recovery_lock: Semaphore::new(/*permits*/ 1),
elicitation_pause_state: ElicitationPauseState::new(),
+ tool_list_revision: Arc::default(),
})
}
@@ -522,6 +531,7 @@ impl RmcpClient {
requires_read_only_tools: false,
session_recovery_lock: Semaphore::new(/*permits*/ 1),
elicitation_pause_state: ElicitationPauseState::new(),
+ tool_list_revision: Arc::default(),
})
}
@@ -629,6 +639,7 @@ impl RmcpClient {
requires_read_only_tools: false,
session_recovery_lock: Semaphore::new(/*permits*/ 1),
elicitation_pause_state: ElicitationPauseState::new(),
+ tool_list_revision: Arc::default(),
})
}
@@ -1315,19 +1326,31 @@ impl RmcpClient {
let (transport, oauth_runtime) = match pending_transport {
PendingTransport::InProcess { transport } => (
client_service
- .serve_with_lifecycle(transport, lifecycle)
+ .serve_with_lifecycle(
+ track_tool_list_changes(transport, Arc::clone(&self.tool_list_revision)),
+ lifecycle,
+ )
.boxed(),
None,
),
PendingTransport::Stdio { transport } => (
client_service
- .serve_with_lifecycle(*transport, lifecycle)
+ .serve_with_lifecycle(
+ track_tool_list_changes(*transport, Arc::clone(&self.tool_list_revision)),
+ lifecycle,
+ )
.boxed(),
None,
),
PendingTransport::StreamableHttp { transport } => (
client_service
- .serve_with_lifecycle(capture_event_notifications(transport), lifecycle)
+ .serve_with_lifecycle(
+ track_tool_list_changes(
+ capture_event_notifications(transport),
+ Arc::clone(&self.tool_list_revision),
+ ),
+ lifecycle,
+ )
.boxed(),
None,
),
@@ -1336,13 +1359,19 @@ impl RmcpClient {
oauth_runtime,
} => (
client_service
- .serve_with_lifecycle(transport, lifecycle)
+ .serve_with_lifecycle(
+ track_tool_list_changes(transport, Arc::clone(&self.tool_list_revision)),
+ lifecycle,
+ )
.boxed(),
Some(oauth_runtime),
),
PendingTransport::StreamableHttpWithAccessTokenOnly { transport } => (
client_service
- .serve_with_lifecycle(transport, lifecycle)
+ .serve_with_lifecycle(
+ track_tool_list_changes(transport, Arc::clone(&self.tool_list_revision)),
+ lifecycle,
+ )
.boxed(),
None,
),
diff --git a/codex-rs/rmcp-client/src/tool_list_changes.rs b/codex-rs/rmcp-client/src/tool_list_changes.rs
new file mode 100644
index 0000000000..8f81a50714
--- /dev/null
+++ b/codex-rs/rmcp-client/src/tool_list_changes.rs
@@ -0,0 +1,73 @@
+//! Records catalog invalidations in transport order, before a later tool response can
+//! let inference continue. The SDK still receives and handles every message normally.
+
+use std::future::Future;
+use std::sync::Arc;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+
+use rmcp::model::JsonRpcMessage;
+use rmcp::model::ServerNotification;
+use rmcp::service::RoleClient;
+use rmcp::service::RxJsonRpcMessage;
+use rmcp::service::TxJsonRpcMessage;
+use rmcp::transport::IntoTransport;
+use rmcp::transport::Transport;
+
+/// Read-only observation of notifications received by one connection. Retaining this
+/// handle does not keep the connection alive.
+#[derive(Clone)]
+pub struct ToolListRevision(pub(crate) Arc<AtomicU64>);
+
+impl ToolListRevision {
+ pub fn current(&self) -> u64 {
+ self.0.load(Ordering::Acquire)
+ }
+}
+
+pub(crate) fn track_tool_list_changes<T, E, A>(
+ transport: T,
+ revision: Arc<AtomicU64>,
+) -> impl Transport<RoleClient, Error = E> + 'static
+where
+ T: IntoTransport<RoleClient, E, A>,
+ E: std::error::Error + Send + Sync + 'static,
+{
+ ToolListChanges {
+ inner: transport.into_transport(),
+ revision,
+ }
+}
+
+struct ToolListChanges<T> {
+ inner: T,
+ revision: Arc<AtomicU64>,
+}
+
+impl<T: Transport<RoleClient> + 'static> Transport<RoleClient> for ToolListChanges<T> {
+ type Error = T::Error;
+
+ fn send(
+ &mut self,
+ message: TxJsonRpcMessage<RoleClient>,
+ ) -> impl Future<Output = Result<(), Self::Error>> + Send + 'static {
+ self.inner.send(message)
+ }
+
+ async fn receive(&mut self) -> Option<RxJsonRpcMessage<RoleClient>> {
+ let message = self.inner.receive().await?;
+ if let JsonRpcMessage::Notification(notification) = &message
+ && matches!(
+ notification.notification,
+ ServerNotification::ToolListChangedNotification(_)
+ )
+ {
+ self.revision.fetch_add(1, Ordering::AcqRel);
+ }
+ Some(message)
+ }
+
+ fn close(&mut self) -> impl Future<Output = Result<(), Self::Error>> + Send {
+ self.inner.close()
+ }
+}