diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json index fb4fb4f1a4..e99d1e87ea 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json @@ -14581,6 +14581,13 @@ "$ref": "#/definitions/v2/Tool" }, "type": "object" + }, + "toolsError": { + "description": "Tool discovery failed and no catalog was returned. Null when a catalog is returned, including cached or empty catalogs.", + "type": [ + "string", + "null" + ] } }, "required": [ diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json index c3c4fc797e..d3965de508 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json @@ -10653,6 +10653,13 @@ "$ref": "#/definitions/Tool" }, "type": "object" + }, + "toolsError": { + "description": "Tool discovery failed and no catalog was returned. Null when a catalog is returned, including cached or empty catalogs.", + "type": [ + "string", + "null" + ] } }, "required": [ diff --git a/codex-rs/app-server-protocol/schema/json/v2/ListMcpServerStatusResponse.json b/codex-rs/app-server-protocol/schema/json/v2/ListMcpServerStatusResponse.json index 73be29100d..919cd571d8 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ListMcpServerStatusResponse.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ListMcpServerStatusResponse.json @@ -116,6 +116,13 @@ "$ref": "#/definitions/Tool" }, "type": "object" + }, + "toolsError": { + "description": "Tool discovery failed and no catalog was returned. Null when a catalog is returned, including cached or empty catalogs.", + "type": [ + "string", + "null" + ] } }, "required": [ diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst index 728f2888d8..5fb6058cd9 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differ diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst index 1ce21e841b..f1622fb5c8 100644 Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differ diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/McpServerStatus.ts b/codex-rs/app-server-protocol/schema/typescript/v2/McpServerStatus.ts index 9a95414428..e5dcd5dcbe 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/McpServerStatus.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/McpServerStatus.ts @@ -12,4 +12,9 @@ export type McpServerStatus = { name: string, /** * Current thread-runtime connection state; null when unavailable or the configuration changed. */ -runtimeStatus: McpServerConnectionStatus | null, pluginId: string | null, serverInfo: McpServerInfo | null, tools: { [key in string]?: Tool }, resources: Array, resourceTemplates: Array, authStatus: McpAuthStatus, }; +runtimeStatus: McpServerConnectionStatus | null, pluginId: string | null, serverInfo: McpServerInfo | null, tools: { [key in string]?: Tool }, +/** + * Tool discovery failed and no catalog was returned. + * Null when a catalog is returned, including cached or empty catalogs. + */ +toolsError: string | null, resources: Array, resourceTemplates: Array, authStatus: McpAuthStatus, }; diff --git a/codex-rs/app-server-protocol/src/protocol/v2/mcp.rs b/codex-rs/app-server-protocol/src/protocol/v2/mcp.rs index 7ab179cfd2..c1ec63c55f 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/mcp.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2/mcp.rs @@ -79,6 +79,9 @@ pub struct McpServerStatus { pub plugin_id: Option, pub server_info: Option, pub tools: std::collections::HashMap, + /// Tool discovery failed and no catalog was returned. + /// Null when a catalog is returned, including cached or empty catalogs. + pub tools_error: Option, pub resources: Vec, pub resource_templates: Vec, pub auth_status: McpAuthStatus, diff --git a/codex-rs/app-server-protocol/src/protocol/v2/tests.rs b/codex-rs/app-server-protocol/src/protocol/v2/tests.rs index 024b4e3e83..c3d8abe164 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/tests.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2/tests.rs @@ -2578,6 +2578,7 @@ fn mcp_server_elicitation_response_serializes_nullable_content() { fn mcp_server_status_serializes_absent_server_info_as_null() { let response = ListMcpServerStatusResponse { data: vec![McpServerStatus { + tools_error: None, name: "not-ready".to_string(), runtime_status: None, plugin_id: None, @@ -2599,6 +2600,7 @@ fn mcp_server_status_serializes_absent_server_info_as_null() { "pluginId": null, "serverInfo": null, "tools": {}, + "toolsError": null, "resources": [], "resourceTemplates": [], "authStatus": "unknown", @@ -2623,6 +2625,7 @@ fn mcp_server_status_accepts_older_inventory_without_runtime_status() { assert_eq!( status, McpServerStatus { + tools_error: None, name: "older-server".to_string(), runtime_status: None, plugin_id: None, @@ -2694,6 +2697,7 @@ fn mcp_server_status_updated_serializes_failure_reason() { fn mcp_server_status_serializes_absent_server_info_metadata_as_null() { let response = ListMcpServerStatusResponse { data: vec![McpServerStatus { + tools_error: None, name: "initialized".to_string(), runtime_status: None, plugin_id: Some("lookup@test".to_string()), @@ -2729,6 +2733,7 @@ fn mcp_server_status_serializes_absent_server_info_metadata_as_null() { "websiteUrl": null, }, "tools": {}, + "toolsError": null, "resources": [], "resourceTemplates": [], "authStatus": "unsupported", diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md index 39e3809c3e..27f6c4b58b 100644 --- a/codex-rs/app-server/README.md +++ b/codex-rs/app-server/README.md @@ -300,7 +300,7 @@ Example with notification opt-out: - `mcpServer/oauth/login` — start an OAuth login for a configured MCP server; pass `threadId` to resolve servers from that thread's selected plugins and executor, optionally pass `clientRegistration` (`auto`, `cimd`, or `dcr`) to override client registration for this login only, and receive an `authorization_url` followed by `mcpServer/oauthLogin/completed` once the browser flow finishes. Omitting `clientRegistration` automatically discovers the authorization server's supported registration methods; the override is never persisted in server configuration. - `tool/requestUserInput` — prompt the user with 1–3 short questions for a tool call and return their answers (experimental). - `config/mcpServer/reload` — reload MCP server config from disk and queue a refresh for loaded threads (applied on each thread's next active turn); returns `{}`. Use this after editing `config.toml` without restarting the server. -- `mcpServerStatus/list` — enumerate configured MCP servers with their tools, auth status, server info, owning `pluginId` (`null` for servers not contributed by a plugin), and nullable `runtimeStatus` from the current thread’s published connections, plus resources/resource templates for `full` detail; supports optional `threadId` and cursor+limit pagination. If `threadId` is omitted, the server reads from the latest global config directly and `runtimeStatus` is `null`. Runtime status is also `null` when the latest server registration differs from the thread’s published configuration. Runtime status is observed without starting or reconnecting the thread’s servers; it can be `notStarted`, `starting`, `connected`, `authenticationRequired`, `failed`, `cancelled`, or `disabled`. Inventory may be cached or collected separately and does not prove that the thread is connected. Older servers omit `runtimeStatus`; clients should treat that as unknown. If `detail` is omitted, the server defaults to `full`. An `unknown` auth status means OAuth support could not be determined; `unsupported` means OAuth is known not to be supported. +- `mcpServerStatus/list` — enumerate configured MCP servers with their tools, auth status, server info, owning `pluginId` (`null` for servers not contributed by a plugin), and nullable `runtimeStatus` from the current thread’s published connections, plus resources/resource templates for `full` detail; supports optional `threadId` and cursor+limit pagination. If `threadId` is omitted, the server reads from the latest global config directly and `runtimeStatus` is `null`. Runtime status is also `null` when the latest server registration differs from the thread’s published configuration. Runtime status is observed without starting or reconnecting the thread’s servers; it can be `notStarted`, `starting`, `connected`, `authenticationRequired`, `failed`, `cancelled`, or `disabled`. Inventory may be cached or collected separately and does not prove that the thread is connected. Each server also includes nullable `toolsError`: a startup or tool-list discovery failure is reported when no catalog is returned. Returned catalogs, including cached or empty catalogs, have no error. Healthy servers are returned even when another server fails. Older servers omit `toolsError`; clients must preserve their existing behavior when it is absent. Older servers omit `runtimeStatus`; clients should treat that as unknown. If `detail` is omitted, the server defaults to `full`. An `unknown` auth status means OAuth support could not be determined; `unsupported` means OAuth is known not to be supported. - `mcpServer/resource/read` — read a resource from a configured MCP server by optional `threadId`, `server`, and `uri`, returning text/blob resource `contents`. Pass `originCallId` with `threadId` to scope a Codex app widget to the app and account of the completed tool call that produced it; successful scoped reads return the same `originCallId`. Optional `connectorId` restricts other hosted app resources to their originating connector. If `threadId` is omitted, the server reads from the latest MCP config directly. - `mcpServer/event/stream/start` (experimental) — subscribe to an MCP event by `threadId`, `server`, `subscriptionId`, event `name`, `arguments`, and optional `_meta`. - `mcpServer/event/stream/stop` (experimental) — stop the caller's event subscription by `subscriptionId`. diff --git a/codex-rs/app-server/src/request_processors/mcp_processor.rs b/codex-rs/app-server/src/request_processors/mcp_processor.rs index 405a1fe8c3..e9acd1cc18 100644 --- a/codex-rs/app-server/src/request_processors/mcp_processor.rs +++ b/codex-rs/app-server/src/request_processors/mcp_processor.rs @@ -343,6 +343,7 @@ impl McpRequestProcessor { let McpServerStatusSnapshot { server_infos, tools_by_server, + tools_errors, resources, resource_templates, auth_statuses, @@ -396,6 +397,7 @@ impl McpRequestProcessor { ), server_info: server_infos.get(name).cloned(), tools: tools_by_server.get(name).cloned().unwrap_or_default(), + tools_error: tools_errors.get(name).cloned(), resources: resources.get(name).cloned().unwrap_or_default(), resource_templates: resource_templates.get(name).cloned().unwrap_or_default(), auth_status: auth_statuses diff --git a/codex-rs/app-server/tests/suite/v2/mcp_server_status.rs b/codex-rs/app-server/tests/suite/v2/mcp_server_status.rs index 4dc085b63e..48ab1f2b99 100644 --- a/codex-rs/app-server/tests/suite/v2/mcp_server_status.rs +++ b/codex-rs/app-server/tests/suite/v2/mcp_server_status.rs @@ -531,7 +531,15 @@ async fn mcp_server_status_list_returns_raw_server_and_tool_names() -> Result<() let codex_home = TempDir::new()?; mock_responses_config(&server.uri()) .with_extra_config(&format!( - "[mcp_servers.some-server]\nurl = \"{mcp_server_url}/mcp\"" + "[mcp_servers.some-server]\nurl = \"{mcp_server_url}/mcp\"\n\ + [mcp_servers.broken-server]\ncommand = {}", + toml::Value::String( + codex_home + .path() + .join("missing-mcp-server") + .display() + .to_string() + ) )) .write(codex_home.path())?; @@ -553,8 +561,25 @@ async fn mcp_server_status_list_returns_raw_server_and_tool_names() -> Result<() .await?; assert_eq!(response.next_cursor, None); - assert_eq!(response.data.len(), 1); - let status = &response.data[0]; + assert_eq!(response.data.len(), 2); + let failed = response + .data + .iter() + .find(|status| status.name == "broken-server") + .unwrap(); + assert!(failed.tools.is_empty()); + assert!( + failed + .tools_error + .as_deref() + .is_some_and(|error| error.contains("MCP startup failed")) + ); + let status = response + .data + .iter() + .find(|status| status.name == "some-server") + .unwrap(); + assert_eq!(status.tools_error, None); assert_eq!(status.name, "some-server"); assert_eq!(status.runtime_status, None); assert_eq!(status.plugin_id, None); diff --git a/codex-rs/codex-mcp/src/connection_manager.rs b/codex-rs/codex-mcp/src/connection_manager.rs index f6d0c7ec70..b211631aff 100644 --- a/codex-rs/codex-mcp/src/connection_manager.rs +++ b/codex-rs/codex-mcp/src/connection_manager.rs @@ -171,10 +171,10 @@ impl McpServerView { async fn listed_tools( &self, tool_plugin_provenance: &ToolPluginProvenance, - ) -> Option> { + ) -> Result, StartupOutcomeError> { let tools = self.connection.client.listed_tools().await?; let tools = filter_tools(tools, &self.tool_filter); - Some(if self.connection.client.is_codex_apps_mcp_server { + Ok(if self.connection.client.is_codex_apps_mcp_server { prepare_codex_apps_tools_for_model(tools, tool_plugin_provenance) } else { prepare_regular_mcp_tools_for_model(tools, tool_plugin_provenance) 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 616ec1729f..d944eec810 100644 --- a/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs +++ b/codex-rs/codex-mcp/src/connection_manager/tool_catalog.rs @@ -1,3 +1,4 @@ +use std::collections::HashMap; use std::collections::HashSet; use std::sync::Arc; use std::sync::atomic::Ordering; @@ -83,9 +84,14 @@ impl McpConnectionSet { } /// Returns all tools with model-visible names normalized. - #[instrument(level = "trace", skip_all, fields(mcp_server_count = self.servers.len()))] pub async fn list_all_tools(&self) -> Vec { + self.list_tools_with_errors().await.0 + } + + #[instrument(level = "trace", skip_all, fields(mcp_server_count = self.servers.len()))] + pub(crate) async fn list_tools_with_errors(&self) -> (Vec, HashMap) { let mut tools = Vec::new(); + let mut errors = HashMap::new(); let mut available_server_count = 0; let mut unavailable_server_count = 0; let server_results = join_all(self.servers.iter().map(|(server_name, view)| async move { @@ -105,7 +111,7 @@ impl McpConnectionSet { match catalog_override { Some(tools) => { let tools = filter_tools(tools, &view.tool_filter); - Some(prepare_codex_apps_tools_for_model( + Ok(prepare_codex_apps_tools_for_model( tools, &self.tool_plugin_provenance, )) @@ -120,32 +126,34 @@ impl McpConnectionSet { startup_complete )) .await; - match server_tools { - Some(server_tools) => Some( - server_tools - .into_iter() - .map(|tool| Self::with_server_metadata(tool, &view.metadata)) - .collect::>(), - ), - None => { + let result = match server_tools { + Ok(server_tools) => Ok(server_tools + .into_iter() + .map(|tool| Self::with_server_metadata(tool, &view.metadata)) + .collect::>()), + Err(error) => { trace!( server_name = %server_name, has_cached_tools, startup_complete, "MCP server tools unavailable while building tool list" ); - None + Err(error) } - } + }; + (server_name, result) })) .await; - for server_tools in server_results { + for (server_name, server_tools) in server_results { match server_tools { - Some(server_tools) => { + Ok(server_tools) => { available_server_count += 1; tools.extend(server_tools); } - None => unavailable_server_count += 1, + Err(error) => { + unavailable_server_count += 1; + errors.insert(server_name.clone(), error.to_string()); + } } } let tools = normalize_tools_for_model_with_prefix( @@ -159,7 +167,7 @@ impl McpConnectionSet { tool_count = tools.len(), "built MCP tool list" ); - tools + (tools, errors) } #[expect( diff --git a/codex-rs/codex-mcp/src/mcp/mod.rs b/codex-rs/codex-mcp/src/mcp/mod.rs index 783a116615..b6d6ff9bef 100644 --- a/codex-rs/codex-mcp/src/mcp/mod.rs +++ b/codex-rs/codex-mcp/src/mcp/mod.rs @@ -459,6 +459,7 @@ pub async fn read_mcp_resource( pub struct McpServerStatusSnapshot { pub server_infos: HashMap, pub tools_by_server: HashMap>, + pub tools_errors: HashMap, pub resources: HashMap>, pub resource_templates: HashMap>, pub auth_statuses: HashMap, @@ -479,6 +480,7 @@ pub async fn collect_mcp_server_status_snapshot_with_detail( return McpServerStatusSnapshot { server_infos: HashMap::new(), tools_by_server: HashMap::new(), + tools_errors: HashMap::new(), resources: HashMap::new(), resource_templates: HashMap::new(), auth_statuses: HashMap::new(), @@ -761,10 +763,10 @@ async fn collect_mcp_server_status_snapshot_from_manager( server_names: Vec, detail: McpSnapshotDetail, ) -> McpServerStatusSnapshot { - let ((server_infos, tools), resources, resource_templates) = tokio::join!( + let ((server_infos, (tools, tools_errors)), resources, resource_templates) = tokio::join!( async { let server_infos = mcp_connection_manager.list_available_server_infos().await; - let tools = mcp_connection_manager.list_all_tools().await; + let tools = mcp_connection_manager.list_tools_with_errors().await; (server_infos, tools) }, async { @@ -801,6 +803,7 @@ async fn collect_mcp_server_status_snapshot_from_manager( McpServerStatusSnapshot { server_infos, tools_by_server, + tools_errors, resources: convert_mcp_resources(resources), resource_templates: convert_mcp_resource_templates(resource_templates), auth_statuses: auth_statuses_from_entries(&auth_status_entries), diff --git a/codex-rs/codex-mcp/src/rmcp_client.rs b/codex-rs/codex-mcp/src/rmcp_client.rs index 49010cc98b..9a1cb073ba 100644 --- a/codex-rs/codex-mcp/src/rmcp_client.rs +++ b/codex-rs/codex-mcp/src/rmcp_client.rs @@ -577,17 +577,17 @@ impl AsyncManagedClient { }) } - pub(crate) async fn listed_tools(&self) -> Option> { + pub(crate) async fn listed_tools(&self) -> Result, StartupOutcomeError> { // Plugin provenance is resolved per-session rather than stored in shared cache payloads. if !self.startup_complete.load(Ordering::Acquire) && let Some(startup_tools) = self.cached_tools() { - Some(startup_tools) + Ok(startup_tools) } else { match self.client().await { - Ok(client) => Some(client.listed_tools()), - Err(_) if self.is_codex_apps_mcp_server => self.cached_tools(), - Err(_) => None, + Ok(client) => Ok(client.listed_tools()), + Err(error) if self.is_codex_apps_mcp_server => self.cached_tools().ok_or(error), + Err(error) => Err(error), } } } diff --git a/codex-rs/tui/src/app/background_requests.rs b/codex-rs/tui/src/app/background_requests.rs index 6ce76cebb1..b48aa9c01b 100644 --- a/codex-rs/tui/src/app/background_requests.rs +++ b/codex-rs/tui/src/app/background_requests.rs @@ -1591,6 +1591,7 @@ mod tests { fn mcp_inventory_maps_prefix_tool_names_by_server() { let statuses = vec![ McpServerStatus { + tools_error: None, name: "docs".to_string(), runtime_status: None, plugin_id: None, @@ -1613,6 +1614,7 @@ mod tests { auth_status: codex_app_server_protocol::McpAuthStatus::Unsupported, }, McpServerStatus { + tools_error: None, name: "disabled".to_string(), runtime_status: None, plugin_id: None, diff --git a/codex-rs/tui/src/app/tests.rs b/codex-rs/tui/src/app/tests.rs index e9568aa87f..795bc65af1 100644 --- a/codex-rs/tui/src/app/tests.rs +++ b/codex-rs/tui/src/app/tests.rs @@ -278,6 +278,7 @@ async fn handle_mcp_inventory_result_respects_origin_thread() { app.handle_mcp_inventory_result( Ok(vec![McpServerStatus { + tools_error: None, name: "docs".to_string(), runtime_status: None, plugin_id: None, diff --git a/codex-rs/tui/src/history_cell/mcp_tests.rs b/codex-rs/tui/src/history_cell/mcp_tests.rs index c4598f255f..cc360f4403 100644 --- a/codex-rs/tui/src/history_cell/mcp_tests.rs +++ b/codex-rs/tui/src/history_cell/mcp_tests.rs @@ -28,6 +28,7 @@ fn mcp_inventory_connection_states() { plugin_id: None, server_info: None, tools: HashMap::new(), + tools_error: None, resources: Vec::new(), resource_templates: Vec::new(), auth_status: McpAuthStatus::Unknown, diff --git a/codex-rs/tui/src/history_cell/tests.rs b/codex-rs/tui/src/history_cell/tests.rs index f4a009e958..97669e8a0d 100644 --- a/codex-rs/tui/src/history_cell/tests.rs +++ b/codex-rs/tui/src/history_cell/tests.rs @@ -987,6 +987,7 @@ async fn mcp_tools_output_lists_tools_for_hyphenated_server_names() { #[test] fn mcp_tools_output_from_statuses_renders_status_only_servers() { let statuses = vec![McpServerStatus { + tools_error: None, name: "plugin_docs".to_string(), runtime_status: None, plugin_id: None, @@ -1019,6 +1020,7 @@ fn mcp_tools_output_from_statuses_renders_status_only_servers() { #[test] fn mcp_tools_output_from_statuses_renders_verbose_inventory() { let statuses = vec![McpServerStatus { + tools_error: None, name: "plugin_docs".to_string(), runtime_status: None, plugin_id: None,