[connectors] Support connectors part 1 - App server & MCP (#9667)

In order to make Codex work with connectors, we add a built-in gateway
MCP that acts as a transparent proxy between the client and the
connectors. The gateway MCP collects actions that are accessible to the
user and sends them down to the user, when a connector action is chosen
to be called, the client invokes the action through the gateway MCP as
well.

 - [x] Add the system built-in gateway MCP to list and run connectors.
 - [x] Add the app server methods and protocol

codex-rs/app-server/Cargo.toml

@@ -22,6 +22,7 @@ codex-common = { workspace = true, features = ["cli"] }
 codex-core = { workspace = true }
 codex-backend-client = { workspace = true }
 codex-file-search = { workspace = true }
+codex-chatgpt = { workspace = true }
 codex-login = { workspace = true }
 codex-protocol = { workspace = true }
 codex-app-server-protocol = { workspace = true }
@@ -48,11 +49,20 @@ uuid = { workspace = true, features = ["serde", "v7"] }
 
 [dev-dependencies]
 app_test_support = { workspace = true }
+axum = { workspace = true, default-features = false, features = [
+    "http1",
+    "json",
+    "tokio",
+] }
 base64 = { workspace = true }
 core_test_support = { workspace = true }
 mcp-types = { workspace = true }
 os_info = { workspace = true }
 pretty_assertions = { workspace = true }
+rmcp = { workspace = true, default-features = false, features = [
+    "server",
+    "transport-streamable-http-server",
+] }
 serial_test = { workspace = true }
 wiremock = { workspace = true }
 shlex = { workspace = true }

codex-rs/app-server/README.md

@@ -89,6 +89,7 @@ Example (from OpenAI's official VSCode extension):
 - `model/list` — list available models (with reasoning effort options).
 - `collaborationMode/list` — list available collaboration mode presets (experimental, no pagination).
 - `skills/list` — list skills for one or more `cwd` values (optional `forceReload`).
+- `app/list` — list available apps.
 - `skills/config/write` — write user-level skill config by path.
 - `mcpServer/oauth/login` — start an OAuth login for a configured MCP server; returns an `authorization_url` and later emits `mcpServer/oauthLogin/completed` once the browser flow finishes.
 - `tool/requestUserInput` — prompt the user with 1–3 short questions for a tool call and return their answers (experimental).

codex-rs/app-server/src/codex_message_processor.rs

@@ -13,6 +13,9 @@ use codex_app_server_protocol::AccountLoginCompletedNotification;
 use codex_app_server_protocol::AccountUpdatedNotification;
 use codex_app_server_protocol::AddConversationListenerParams;
 use codex_app_server_protocol::AddConversationSubscriptionResponse;
+use codex_app_server_protocol::AppInfo as ApiAppInfo;
+use codex_app_server_protocol::AppsListParams;
+use codex_app_server_protocol::AppsListResponse;
 use codex_app_server_protocol::ArchiveConversationParams;
 use codex_app_server_protocol::ArchiveConversationResponse;
 use codex_app_server_protocol::AskForApproval;
@@ -122,6 +125,7 @@ use codex_app_server_protocol::UserInput as V2UserInput;
 use codex_app_server_protocol::UserSavedConfig;
 use codex_app_server_protocol::build_turns_from_event_msgs;
 use codex_backend_client::Client as BackendClient;
+use codex_chatgpt::connectors;
 use codex_core::AuthManager;
 use codex_core::CodexThread;
 use codex_core::Cursor as RolloutCursor;
@@ -411,6 +415,9 @@ impl CodexMessageProcessor {
             ClientRequest::SkillsList { request_id, params } => {
                 self.skills_list(request_id, params).await;
             }
+            ClientRequest::AppsList { request_id, params } => {
+                self.apps_list(request_id, params).await;
+            }
             ClientRequest::SkillsConfigWrite { request_id, params } => {
                 self.skills_config_write(request_id, params).await;
             }
@@ -3406,6 +3413,102 @@ impl CodexMessageProcessor {
             .await;
     }
 
+    async fn apps_list(&self, request_id: RequestId, params: AppsListParams) {
+        let AppsListParams { cursor, limit } = params;
+        let config = match self.load_latest_config().await {
+            Ok(config) => config,
+            Err(error) => {
+                self.outgoing.send_error(request_id, error).await;
+                return;
+            }
+        };
+
+        if !config.features.enabled(Feature::Connectors) {
+            self.outgoing
+                .send_response(
+                    request_id,
+                    AppsListResponse {
+                        data: Vec::new(),
+                        next_cursor: None,
+                    },
+                )
+                .await;
+            return;
+        }
+
+        let connectors = match connectors::list_connectors(&config).await {
+            Ok(connectors) => connectors,
+            Err(err) => {
+                self.send_internal_error(request_id, format!("failed to list apps: {err}"))
+                    .await;
+                return;
+            }
+        };
+
+        let total = connectors.len();
+        if total == 0 {
+            self.outgoing
+                .send_response(
+                    request_id,
+                    AppsListResponse {
+                        data: Vec::new(),
+                        next_cursor: None,
+                    },
+                )
+                .await;
+            return;
+        }
+
+        let effective_limit = limit.unwrap_or(total as u32).max(1) as usize;
+        let effective_limit = effective_limit.min(total);
+        let start = match cursor {
+            Some(cursor) => match cursor.parse::<usize>() {
+                Ok(idx) => idx,
+                Err(_) => {
+                    self.send_invalid_request_error(
+                        request_id,
+                        format!("invalid cursor: {cursor}"),
+                    )
+                    .await;
+                    return;
+                }
+            },
+            None => 0,
+        };
+
+        if start > total {
+            self.send_invalid_request_error(
+                request_id,
+                format!("cursor {start} exceeds total apps {total}"),
+            )
+            .await;
+            return;
+        }
+
+        let end = start.saturating_add(effective_limit).min(total);
+        let data = connectors[start..end]
+            .iter()
+            .cloned()
+            .map(|connector| ApiAppInfo {
+                id: connector.connector_id,
+                name: connector.connector_name,
+                description: connector.connector_description,
+                logo_url: connector.logo_url,
+                install_url: connector.install_url,
+                is_accessible: connector.is_accessible,
+            })
+            .collect();
+
+        let next_cursor = if end < total {
+            Some(end.to_string())
+        } else {
+            None
+        };
+        self.outgoing
+            .send_response(request_id, AppsListResponse { data, next_cursor })
+            .await;
+    }
+
     async fn skills_list(&self, request_id: RequestId, params: SkillsListParams) {
         let SkillsListParams { cwds, force_reload } = params;
         let cwds = if cwds.is_empty() {

codex-rs/app-server/tests/common/auth_fixtures.rs

@@ -49,6 +49,16 @@ impl ChatGptAuthFixture {
         self
     }
 
+    pub fn chatgpt_user_id(mut self, chatgpt_user_id: impl Into<String>) -> Self {
+        self.claims.chatgpt_user_id = Some(chatgpt_user_id.into());
+        self
+    }
+
+    pub fn chatgpt_account_id(mut self, chatgpt_account_id: impl Into<String>) -> Self {
+        self.claims.chatgpt_account_id = Some(chatgpt_account_id.into());
+        self
+    }
+
     pub fn email(mut self, email: impl Into<String>) -> Self {
         self.claims.email = Some(email.into());
         self
@@ -69,6 +79,8 @@ impl ChatGptAuthFixture {
 pub struct ChatGptIdTokenClaims {
     pub email: Option<String>,
     pub plan_type: Option<String>,
+    pub chatgpt_user_id: Option<String>,
+    pub chatgpt_account_id: Option<String>,
 }
 
 impl ChatGptIdTokenClaims {
@@ -85,6 +97,16 @@ impl ChatGptIdTokenClaims {
         self.plan_type = Some(plan_type.into());
         self
     }
+
+    pub fn chatgpt_user_id(mut self, chatgpt_user_id: impl Into<String>) -> Self {
+        self.chatgpt_user_id = Some(chatgpt_user_id.into());
+        self
+    }
+
+    pub fn chatgpt_account_id(mut self, chatgpt_account_id: impl Into<String>) -> Self {
+        self.chatgpt_account_id = Some(chatgpt_account_id.into());
+        self
+    }
 }
 
 pub fn encode_id_token(claims: &ChatGptIdTokenClaims) -> Result<String> {
@@ -93,10 +115,20 @@ pub fn encode_id_token(claims: &ChatGptIdTokenClaims) -> Result<String> {
     if let Some(email) = &claims.email {
         payload.insert("email".to_string(), json!(email));
     }
+    let mut auth_payload = serde_json::Map::new();
     if let Some(plan_type) = &claims.plan_type {
+        auth_payload.insert("chatgpt_plan_type".to_string(), json!(plan_type));
+    }
+    if let Some(chatgpt_user_id) = &claims.chatgpt_user_id {
+        auth_payload.insert("chatgpt_user_id".to_string(), json!(chatgpt_user_id));
+    }
+    if let Some(chatgpt_account_id) = &claims.chatgpt_account_id {
+        auth_payload.insert("chatgpt_account_id".to_string(), json!(chatgpt_account_id));
+    }
+    if !auth_payload.is_empty() {
         payload.insert(
             "https://api.openai.com/auth".to_string(),
-            json!({ "chatgpt_plan_type": plan_type }),
+            serde_json::Value::Object(auth_payload),
         );
     }
     let payload = serde_json::Value::Object(payload);

codex-rs/app-server/tests/common/mcp_process.rs

@@ -12,6 +12,7 @@ use tokio::process::ChildStdout;
 
 use anyhow::Context;
 use codex_app_server_protocol::AddConversationListenerParams;
+use codex_app_server_protocol::AppsListParams;
 use codex_app_server_protocol::ArchiveConversationParams;
 use codex_app_server_protocol::CancelLoginAccountParams;
 use codex_app_server_protocol::CancelLoginChatGptParams;
@@ -409,6 +410,12 @@ impl McpProcess {
         self.send_request("model/list", params).await
     }
 
+    /// Send an `app/list` JSON-RPC request.
+    pub async fn send_apps_list_request(&mut self, params: AppsListParams) -> anyhow::Result<i64> {
+        let params = Some(serde_json::to_value(params)?);
+        self.send_request("app/list", params).await
+    }
+
     /// Send a `collaborationMode/list` JSON-RPC request.
     pub async fn send_list_collaboration_modes_request(
         &mut self,

codex-rs/app-server/tests/suite/v2/app_list.rs

@@ -0,0 +1,381 @@
+use std::borrow::Cow;
+use std::sync::Arc;
+use std::time::Duration;
+
+use anyhow::Result;
+use app_test_support::ChatGptAuthFixture;
+use app_test_support::McpProcess;
+use app_test_support::to_response;
+use app_test_support::write_chatgpt_auth;
+use axum::Json;
+use axum::Router;
+use axum::extract::State;
+use axum::http::HeaderMap;
+use axum::http::StatusCode;
+use axum::http::header::AUTHORIZATION;
+use axum::routing::post;
+use codex_app_server_protocol::AppInfo;
+use codex_app_server_protocol::AppsListParams;
+use codex_app_server_protocol::AppsListResponse;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::RequestId;
+use codex_core::auth::AuthCredentialsStoreMode;
+use codex_core::connectors::ConnectorInfo;
+use pretty_assertions::assert_eq;
+use rmcp::handler::server::ServerHandler;
+use rmcp::model::JsonObject;
+use rmcp::model::ListToolsResult;
+use rmcp::model::Meta;
+use rmcp::model::ServerCapabilities;
+use rmcp::model::ServerInfo;
+use rmcp::model::Tool;
+use rmcp::model::ToolAnnotations;
+use rmcp::transport::StreamableHttpServerConfig;
+use rmcp::transport::StreamableHttpService;
+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
+use serde_json::json;
+use tempfile::TempDir;
+use tokio::net::TcpListener;
+use tokio::task::JoinHandle;
+use tokio::time::timeout;
+
+const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
+
+#[tokio::test]
+async fn list_apps_returns_empty_when_connectors_disabled() -> Result<()> {
+    let codex_home = TempDir::new()?;
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+
+    timeout(DEFAULT_TIMEOUT, mcp.initialize()).await??;
+
+    let request_id = mcp
+        .send_apps_list_request(AppsListParams {
+            limit: Some(50),
+            cursor: None,
+        })
+        .await?;
+
+    let response: JSONRPCResponse = timeout(
+        DEFAULT_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+
+    let AppsListResponse { data, next_cursor } = to_response(response)?;
+
+    assert!(data.is_empty());
+    assert!(next_cursor.is_none());
+    Ok(())
+}
+
+#[tokio::test]
+async fn list_apps_returns_connectors_with_accessible_flags() -> Result<()> {
+    let connectors = vec![
+        ConnectorInfo {
+            connector_id: "alpha".to_string(),
+            connector_name: "Alpha".to_string(),
+            connector_description: Some("Alpha connector".to_string()),
+            logo_url: Some("https://example.com/alpha.png".to_string()),
+            install_url: None,
+            is_accessible: false,
+        },
+        ConnectorInfo {
+            connector_id: "beta".to_string(),
+            connector_name: "beta".to_string(),
+            connector_description: None,
+            logo_url: None,
+            install_url: None,
+            is_accessible: false,
+        },
+    ];
+
+    let tools = vec![connector_tool("beta", "Beta App")?];
+    let (server_url, server_handle) = start_apps_server(connectors.clone(), tools).await?;
+
+    let codex_home = TempDir::new()?;
+    write_connectors_config(codex_home.path(), &server_url)?;
+    write_chatgpt_auth(
+        codex_home.path(),
+        ChatGptAuthFixture::new("chatgpt-token")
+            .account_id("account-123")
+            .chatgpt_user_id("user-123")
+            .chatgpt_account_id("account-123"),
+        AuthCredentialsStoreMode::File,
+    )?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_TIMEOUT, mcp.initialize()).await??;
+
+    let request_id = mcp
+        .send_apps_list_request(AppsListParams {
+            limit: None,
+            cursor: None,
+        })
+        .await?;
+
+    let response: JSONRPCResponse = timeout(
+        DEFAULT_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(request_id)),
+    )
+    .await??;
+
+    let AppsListResponse { data, next_cursor } = to_response(response)?;
+
+    let expected = vec![
+        AppInfo {
+            id: "beta".to_string(),
+            name: "Beta App".to_string(),
+            description: None,
+            logo_url: None,
+            install_url: Some("https://chatgpt.com/apps/beta/beta".to_string()),
+            is_accessible: true,
+        },
+        AppInfo {
+            id: "alpha".to_string(),
+            name: "Alpha".to_string(),
+            description: Some("Alpha connector".to_string()),
+            logo_url: Some("https://example.com/alpha.png".to_string()),
+            install_url: Some("https://chatgpt.com/apps/alpha/alpha".to_string()),
+            is_accessible: false,
+        },
+    ];
+
+    assert_eq!(data, expected);
+    assert!(next_cursor.is_none());
+
+    server_handle.abort();
+    Ok(())
+}
+
+#[tokio::test]
+async fn list_apps_paginates_results() -> Result<()> {
+    let connectors = vec![
+        ConnectorInfo {
+            connector_id: "alpha".to_string(),
+            connector_name: "Alpha".to_string(),
+            connector_description: Some("Alpha connector".to_string()),
+            logo_url: None,
+            install_url: None,
+            is_accessible: false,
+        },
+        ConnectorInfo {
+            connector_id: "beta".to_string(),
+            connector_name: "beta".to_string(),
+            connector_description: None,
+            logo_url: None,
+            install_url: None,
+            is_accessible: false,
+        },
+    ];
+
+    let tools = vec![connector_tool("beta", "Beta App")?];
+    let (server_url, server_handle) = start_apps_server(connectors.clone(), tools).await?;
+
+    let codex_home = TempDir::new()?;
+    write_connectors_config(codex_home.path(), &server_url)?;
+    write_chatgpt_auth(
+        codex_home.path(),
+        ChatGptAuthFixture::new("chatgpt-token")
+            .account_id("account-123")
+            .chatgpt_user_id("user-123")
+            .chatgpt_account_id("account-123"),
+        AuthCredentialsStoreMode::File,
+    )?;
+
+    let mut mcp = McpProcess::new(codex_home.path()).await?;
+    timeout(DEFAULT_TIMEOUT, mcp.initialize()).await??;
+
+    let first_request = mcp
+        .send_apps_list_request(AppsListParams {
+            limit: Some(1),
+            cursor: None,
+        })
+        .await?;
+    let first_response: JSONRPCResponse = timeout(
+        DEFAULT_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(first_request)),
+    )
+    .await??;
+    let AppsListResponse {
+        data: first_page,
+        next_cursor: first_cursor,
+    } = to_response(first_response)?;
+
+    let expected_first = vec![AppInfo {
+        id: "beta".to_string(),
+        name: "Beta App".to_string(),
+        description: None,
+        logo_url: None,
+        install_url: Some("https://chatgpt.com/apps/beta/beta".to_string()),
+        is_accessible: true,
+    }];
+
+    assert_eq!(first_page, expected_first);
+    let next_cursor = first_cursor.ok_or_else(|| anyhow::anyhow!("missing cursor"))?;
+
+    let second_request = mcp
+        .send_apps_list_request(AppsListParams {
+            limit: Some(1),
+            cursor: Some(next_cursor),
+        })
+        .await?;
+    let second_response: JSONRPCResponse = timeout(
+        DEFAULT_TIMEOUT,
+        mcp.read_stream_until_response_message(RequestId::Integer(second_request)),
+    )
+    .await??;
+    let AppsListResponse {
+        data: second_page,
+        next_cursor: second_cursor,
+    } = to_response(second_response)?;
+
+    let expected_second = vec![AppInfo {
+        id: "alpha".to_string(),
+        name: "Alpha".to_string(),
+        description: Some("Alpha connector".to_string()),
+        logo_url: None,
+        install_url: Some("https://chatgpt.com/apps/alpha/alpha".to_string()),
+        is_accessible: false,
+    }];
+
+    assert_eq!(second_page, expected_second);
+    assert!(second_cursor.is_none());
+
+    server_handle.abort();
+    Ok(())
+}
+
+#[derive(Clone)]
+struct AppsServerState {
+    expected_bearer: String,
+    expected_account_id: String,
+    response: serde_json::Value,
+}
+
+#[derive(Clone)]
+struct AppListMcpServer {
+    tools: Arc<Vec<Tool>>,
+}
+
+impl AppListMcpServer {
+    fn new(tools: Arc<Vec<Tool>>) -> Self {
+        Self { tools }
+    }
+}
+
+impl ServerHandler for AppListMcpServer {
+    fn get_info(&self) -> ServerInfo {
+        ServerInfo {
+            capabilities: ServerCapabilities::builder().enable_tools().build(),
+            ..ServerInfo::default()
+        }
+    }
+
+    fn list_tools(
+        &self,
+        _request: Option<rmcp::model::PaginatedRequestParam>,
+        _context: rmcp::service::RequestContext<rmcp::service::RoleServer>,
+    ) -> impl std::future::Future<Output = Result<ListToolsResult, rmcp::ErrorData>> + Send + '_
+    {
+        let tools = self.tools.clone();
+        async move {
+            Ok(ListToolsResult {
+                tools: (*tools).clone(),
+                next_cursor: None,
+                meta: None,
+            })
+        }
+    }
+}
+
+async fn start_apps_server(
+    connectors: Vec<ConnectorInfo>,
+    tools: Vec<Tool>,
+) -> Result<(String, JoinHandle<()>)> {
+    let state = AppsServerState {
+        expected_bearer: "Bearer chatgpt-token".to_string(),
+        expected_account_id: "account-123".to_string(),
+        response: json!({ "connectors": connectors }),
+    };
+    let state = Arc::new(state);
+    let tools = Arc::new(tools);
+
+    let listener = TcpListener::bind("127.0.0.1:0").await?;
+    let addr = listener.local_addr()?;
+
+    let mcp_service = StreamableHttpService::new(
+        {
+            let tools = tools.clone();
+            move || Ok(AppListMcpServer::new(tools.clone()))
+        },
+        Arc::new(LocalSessionManager::default()),
+        StreamableHttpServerConfig::default(),
+    );
+
+    let router = Router::new()
+        .route("/aip/connectors/list_accessible", post(list_connectors))
+        .with_state(state)
+        .nest_service("/api/codex/apps", mcp_service);
+
+    let handle = tokio::spawn(async move {
+        let _ = axum::serve(listener, router).await;
+    });
+
+    Ok((format!("http://{addr}"), handle))
+}
+
+async fn list_connectors(
+    State(state): State<Arc<AppsServerState>>,
+    headers: HeaderMap,
+) -> Result<impl axum::response::IntoResponse, StatusCode> {
+    let bearer_ok = headers
+        .get(AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(|value| value == state.expected_bearer);
+    let account_ok = headers
+        .get("chatgpt-account-id")
+        .and_then(|value| value.to_str().ok())
+        .is_some_and(|value| value == state.expected_account_id);
+
+    if bearer_ok && account_ok {
+        Ok(Json(state.response.clone()))
+    } else {
+        Err(StatusCode::UNAUTHORIZED)
+    }
+}
+
+fn connector_tool(connector_id: &str, connector_name: &str) -> Result<Tool> {
+    let schema: JsonObject = serde_json::from_value(json!({
+        "type": "object",
+        "additionalProperties": false
+    }))?;
+    let mut tool = Tool::new(
+        Cow::Owned(format!("connector_{connector_id}")),
+        Cow::Borrowed("Connector test tool"),
+        Arc::new(schema),
+    );
+    tool.annotations = Some(ToolAnnotations::new().read_only(true));
+
+    let mut meta = Meta::new();
+    meta.0
+        .insert("connector_id".to_string(), json!(connector_id));
+    meta.0
+        .insert("connector_name".to_string(), json!(connector_name));
+    tool.meta = Some(meta);
+    Ok(tool)
+}
+
+fn write_connectors_config(codex_home: &std::path::Path, base_url: &str) -> std::io::Result<()> {
+    let config_toml = codex_home.join("config.toml");
+    std::fs::write(
+        config_toml,
+        format!(
+            r#"
+chatgpt_base_url = "{base_url}"
+
+[features]
+connectors = true
+"#
+        ),
+    )
+}

codex-rs/app-server/tests/suite/v2/mod.rs

@@ -1,5 +1,6 @@
 mod account;
 mod analytics;
+mod app_list;
 mod collaboration_mode_list;
 mod config_rpc;
 mod initialize;