openai/codex · error

MCP server '{server}' is not registered by the hosted runtim

Error message

MCP server '{server}' is not registered by the hosted runtime

What it means

latest_connections_for_event_server gates event-stream access (list_events / open_event_stream) for the reserved name codex_apps: it only succeeds when the published catalog holds a host-owned apps registration under that exact name. The bail fires when that name is requested but no host-owned registration exists - typically a user-defined server shadowing the reserved name, or the hosted registration not yet published.

Source

Thrown at codex-rs/codex-mcp/src/runtime.rs:562

    pub(crate) fn latest_connections_for_event_server(
        &self,
        server: &str,
    ) -> anyhow::Result<(Arc<McpConnectionSet>, watch::Receiver<()>)> {
        let hosted_event_server_removals = self.hosted_event_server_removals.subscribe();
        let current = self.current.load();
        if server == CODEX_APPS_MCP_SERVER_NAME
            && !current
                .config
                .as_ref()
                .and_then(|config| config.mcp_server_catalog.server(server))
                .is_some_and(|registration| {
                    registration
                        .source()
                        .is_host_owned_apps(server, registration.config())
                })
        {
            anyhow::bail!("MCP server '{server}' is not registered by the hosted runtime");
        }
        Ok((
            Arc::clone(&current.connections),
            hosted_event_server_removals,
        ))
    }

    pub async fn shutdown(&self) {
        self.latest_connections().shutdown().await;
    }
}

#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SandboxState {
    pub permission_profile: PermissionProfile,
    pub codex_linux_sandbox_exe: Option<PathBuf>,
    pub sandbox_cwd: PathUri,

View on GitHub (pinned to 339751715c)

Solutions

1. Rename the user-defined server in config.toml from codex_apps to anything else and restart
2. Remove the conflicting [mcp_servers.codex_apps] entry so only the hosted registration owns the name
3. If it is a startup race, retry after the runtime publishes registrations (await the ready signal before opening the stream)

Example fix

# before: user server shadows the reserved hosted name
[mcp_servers.codex_apps]
url = "https://my-server.example/mcp"

# after
[mcp_servers.my_apps_bridge]
url = "https://my-server.example/mcp"

match runtime.latest_connections_for_event_server(server) {
    Ok((connections, removals)) => { /* open the event stream */ }
    Err(err) if err.to_string().contains("not registered by the hosted runtime") => { /* rename the conflicting config entry or skip the stream */ }
    Err(err) => return Err(err),
}

When it happens

Trigger: Calling list_events or open_event_stream with server = "codex_apps" while config.toml also defines a user-level [mcp_servers.codex_apps] entry (so the catalog entry is not host-owned), or before the hosted runtime has published its apps registration after startup or a config replace.

Common situations: Users naming their own server 'codex_apps' not realizing it is reserved; opening the apps event stream immediately at startup before publication completes.

Related errors

• Environment variable {env_var} for MCP server '{server_name}
• Invalid MCP server name '{server_name}': must match pattern
• executor-owned MCP server `{server_name}` cannot use hosted
• codex_apps MCP server is unavailable
• failed to read MCP config for selected plugin `{plugin_id}`

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/cceedcb3456f7ac5. Report an issue: GitHub.