Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(bridge): retire unsupported Codex MCP backend

Rudy Celeklia3563508159f
diff --git a/ruflo/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md b/ruflo/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md
index db70dfcb74..6793124bb8 100644
--- a/ruflo/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md
+++ b/ruflo/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md
@@ -1,4 +1,4 @@
-# ADR-034: Optional MCP Backends β€” Claude Code, Gemini, Codex
+# ADR-034: Optional MCP Backends β€” Claude Code and Gemini
**Status:** Accepted
**Date:** 2026-03-05
@@ -16,7 +16,7 @@ These require their own API keys and have different resource profiles, so they s
## Decision
-Add three optional MCP backends that can be enabled via environment variables. Unlike ruvector/ruflo (enabled by default), these are **disabled by default** and require explicit API keys.
+Claude Code and Gemini remain optional MCP backends. Codex was originally listed here, but current Codex CLI has no MCP server mode. As of #3509, the bridge leaves that group disabled and warns when `MCP_GROUP_CODEX=true` is requested. Ruflo's separate Codex dual-mode workers use `codex exec`; a future MCP adapter needs a separate execution and security design.
### Backend Configuration
@@ -26,7 +26,7 @@ Add three optional MCP backends that can be enabled via environment variables. U
| ruflo | `ENABLE_RUFLO` | None | `npx ruflo mcp start` | **enabled** |
| Claude Code | `ENABLE_CLAUDE_CODE` | `ANTHROPIC_API_KEY` | `claude mcp serve` | disabled |
| Gemini MCP | `ENABLE_GEMINI_MCP` | `GOOGLE_API_KEY` | `npx gemini-mcp-server` | disabled |
-| Codex | `ENABLE_CODEX` | `OPENAI_API_KEY` | `npx @openai/codex mcp serve` | disabled |
+| Codex | `MCP_GROUP_CODEX` | N/A | No supported MCP server mode | unavailable; opt-in warns |
### Architecture
@@ -37,7 +37,6 @@ ruvector__hooks_route β†’ ruvector MCP
ruflo__agent_spawn β†’ ruflo MCP
claude__Read β†’ Claude Code MCP
gemini__chat β†’ Gemini MCP
-codex__execute β†’ Codex MCP
```
```
@@ -52,10 +51,10 @@ codex__execute β†’ Codex MCP
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β”‚ β”‚
β”‚ Optional backends (API key required): β”‚
-β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
-β”‚ β”‚ Claude Code β”‚ β”‚ Gemini β”‚ β”‚ OpenAI Codex β”‚ β”‚
-β”‚ β”‚ (opt-in) β”‚ β”‚ (opt-in) β”‚ β”‚ (opt-in) β”‚ β”‚
-β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ Claude Code β”‚ β”‚ Gemini β”‚ β”‚
+β”‚ β”‚ (opt-in) β”‚ β”‚ (opt-in) β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```
@@ -69,10 +68,10 @@ ANTHROPIC_API_KEY=sk-ant-...
ENABLE_GEMINI_MCP=true
GOOGLE_API_KEY=AIzaSy... # already set for Gemini models
-ENABLE_CODEX=true
-OPENAI_API_KEY=sk-... # already set for OpenAI models
```
+`MCP_GROUP_CODEX=true` is not an enablement path: it produces an explicit warning and does not start a Codex child process.
+
### Security Considerations
1. **API keys stay server-side** β€” keys are only in the bridge container's env vars, never exposed to the browser
@@ -88,14 +87,13 @@ OPENAI_API_KEY=sk-... # already set for OpenAI models
| ruflo | ~50MB | Low | ~5s |
| Claude Code | ~100MB | Medium | ~5s |
| Gemini MCP | ~40MB | Low | ~4s |
-| Codex | ~80MB | Medium | ~5s |
-With all 5 backends enabled, the bridge container needs ~800MB memory.
+Resource estimates for the remaining backends require current deployment measurement.
## Consequences
### Positive
-- Users can access Claude, Gemini, and Codex capabilities directly from HF Chat UI
+- Users can access Claude and Gemini capabilities directly from HF Chat UI
- Single `/mcp` endpoint β€” no client-side config changes
- Opt-in model keeps default resource usage low
- API keys shared with the chat proxy (no additional secrets needed for Gemini/OpenAI)
diff --git a/ruflo/src/mcp-bridge/index.js b/ruflo/src/mcp-bridge/index.js
index a024b90589..88b846372e 100644
--- a/ruflo/src/mcp-bridge/index.js
+++ b/ruflo/src/mcp-bridge/index.js
@@ -106,14 +106,18 @@ const TOOL_GROUPS = {
source: "gemini-mcp",
},
- // --- OpenAI Codex ---
+ // --- OpenAI Codex (MCP server mode removed from current CLI; #3509) ---
codex: {
- enabled: process.env.MCP_GROUP_CODEX === "true",
- description: "OpenAI Codex coding agent β€” code generation and execution (requires OPENAI_API_KEY)",
+ enabled: false,
+ description: "Unavailable: Codex CLI has no MCP server mode. Use Codex dual-mode workers instead.",
source: "codex",
},
};
+if (process.env.MCP_GROUP_CODEX === "true") {
+ console.warn("[codex] Codex CLI has no MCP server mode; MCP_GROUP_CODEX is disabled. Use Codex dual-mode workers (codex exec) instead.");
+}
+
// =============================================================================
// STDIO MCP CLIENT β€” Connects to external MCP servers via child process
// =============================================================================
@@ -257,7 +261,6 @@ const BACKEND_DEFS = [
{ name: "agentic-flow", command: "npx", args: ["-y", "agentic-flow@alpha", "mcp", "start"], groups: ["agentic-flow"] },
{ name: "claude", command: "claude", args: ["mcp", "serve"], groups: ["claude-code"] },
{ name: "gemini-mcp", command: "npx", args: ["-y", "gemini-mcp-server"], groups: ["gemini"] },
- { name: "codex", command: "npx", args: ["-y", "@openai/codex", "mcp-server"], groups: ["codex"] },
];
const mcpBackends = new Map();
@@ -602,19 +605,7 @@ Requires: GOOGLE_API_KEY environment variable (already set for Gemini models).
codex: `# Codex Group
-OpenAI Codex coding agent.
-
-Requires: OPENAI_API_KEY environment variable (already set for OpenAI models).
-
-## Capabilities
-- Code generation and execution
-- Code completion
-- Code explanation
-
-## When to Use
-- Code generation tasks
-- Quick code completions
-- Code explanation and documentation`,
+Unavailable: current Codex CLI has no MCP server mode (#3509). This group is disabled even if MCP_GROUP_CODEX=true, so it exposes no tools. Use the separate Codex dual-mode worker through codex exec. A future MCP adapter requires its own execution and security design.`,
};
if (topic === "tool" && toolName) {
diff --git a/ruflo/src/ruvocal/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md b/ruflo/src/ruvocal/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md
index db70dfcb74..6793124bb8 100644
--- a/ruflo/src/ruvocal/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md
+++ b/ruflo/src/ruvocal/docs/adr/ADR-034-OPTIONAL-MCP-BACKENDS.md
@@ -1,4 +1,4 @@
-# ADR-034: Optional MCP Backends β€” Claude Code, Gemini, Codex
+# ADR-034: Optional MCP Backends β€” Claude Code and Gemini
**Status:** Accepted
**Date:** 2026-03-05
@@ -16,7 +16,7 @@ These require their own API keys and have different resource profiles, so they s
## Decision
-Add three optional MCP backends that can be enabled via environment variables. Unlike ruvector/ruflo (enabled by default), these are **disabled by default** and require explicit API keys.
+Claude Code and Gemini remain optional MCP backends. Codex was originally listed here, but current Codex CLI has no MCP server mode. As of #3509, the bridge leaves that group disabled and warns when `MCP_GROUP_CODEX=true` is requested. Ruflo's separate Codex dual-mode workers use `codex exec`; a future MCP adapter needs a separate execution and security design.
### Backend Configuration
@@ -26,7 +26,7 @@ Add three optional MCP backends that can be enabled via environment variables. U
| ruflo | `ENABLE_RUFLO` | None | `npx ruflo mcp start` | **enabled** |
| Claude Code | `ENABLE_CLAUDE_CODE` | `ANTHROPIC_API_KEY` | `claude mcp serve` | disabled |
| Gemini MCP | `ENABLE_GEMINI_MCP` | `GOOGLE_API_KEY` | `npx gemini-mcp-server` | disabled |
-| Codex | `ENABLE_CODEX` | `OPENAI_API_KEY` | `npx @openai/codex mcp serve` | disabled |
+| Codex | `MCP_GROUP_CODEX` | N/A | No supported MCP server mode | unavailable; opt-in warns |
### Architecture
@@ -37,7 +37,6 @@ ruvector__hooks_route β†’ ruvector MCP
ruflo__agent_spawn β†’ ruflo MCP
claude__Read β†’ Claude Code MCP
gemini__chat β†’ Gemini MCP
-codex__execute β†’ Codex MCP
```
```
@@ -52,10 +51,10 @@ codex__execute β†’ Codex MCP
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β”‚ β”‚
β”‚ Optional backends (API key required): β”‚
-β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
-β”‚ β”‚ Claude Code β”‚ β”‚ Gemini β”‚ β”‚ OpenAI Codex β”‚ β”‚
-β”‚ β”‚ (opt-in) β”‚ β”‚ (opt-in) β”‚ β”‚ (opt-in) β”‚ β”‚
-β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ Claude Code β”‚ β”‚ Gemini β”‚ β”‚
+β”‚ β”‚ (opt-in) β”‚ β”‚ (opt-in) β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```
@@ -69,10 +68,10 @@ ANTHROPIC_API_KEY=sk-ant-...
ENABLE_GEMINI_MCP=true
GOOGLE_API_KEY=AIzaSy... # already set for Gemini models
-ENABLE_CODEX=true
-OPENAI_API_KEY=sk-... # already set for OpenAI models
```
+`MCP_GROUP_CODEX=true` is not an enablement path: it produces an explicit warning and does not start a Codex child process.
+
### Security Considerations
1. **API keys stay server-side** β€” keys are only in the bridge container's env vars, never exposed to the browser
@@ -88,14 +87,13 @@ OPENAI_API_KEY=sk-... # already set for OpenAI models
| ruflo | ~50MB | Low | ~5s |
| Claude Code | ~100MB | Medium | ~5s |
| Gemini MCP | ~40MB | Low | ~4s |
-| Codex | ~80MB | Medium | ~5s |
-With all 5 backends enabled, the bridge container needs ~800MB memory.
+Resource estimates for the remaining backends require current deployment measurement.
## Consequences
### Positive
-- Users can access Claude, Gemini, and Codex capabilities directly from HF Chat UI
+- Users can access Claude and Gemini capabilities directly from HF Chat UI
- Single `/mcp` endpoint β€” no client-side config changes
- Opt-in model keeps default resource usage low
- API keys shared with the chat proxy (no additional secrets needed for Gemini/OpenAI)
diff --git a/ruflo/src/ruvocal/mcp-bridge/index.js b/ruflo/src/ruvocal/mcp-bridge/index.js
index 0d20fa77ad..8f6835be8e 100644
--- a/ruflo/src/ruvocal/mcp-bridge/index.js
+++ b/ruflo/src/ruvocal/mcp-bridge/index.js
@@ -106,14 +106,18 @@ const TOOL_GROUPS = {
source: "gemini-mcp",
},
- // --- OpenAI Codex ---
+ // --- OpenAI Codex (MCP server mode removed from current CLI; #3509) ---
codex: {
- enabled: process.env.MCP_GROUP_CODEX === "true",
- description: "OpenAI Codex coding agent β€” code generation and execution (requires OPENAI_API_KEY)",
+ enabled: false,
+ description: "Unavailable: Codex CLI has no MCP server mode. Use Codex dual-mode workers instead.",
source: "codex",
},
};
+if (process.env.MCP_GROUP_CODEX === "true") {
+ console.warn("[codex] Codex CLI has no MCP server mode; MCP_GROUP_CODEX is disabled. Use Codex dual-mode workers (codex exec) instead.");
+}
+
// =============================================================================
// STDIO MCP CLIENT β€” Connects to external MCP servers via child process
// =============================================================================
@@ -262,7 +266,6 @@ const BACKEND_DEFS = [
{ name: "agentic-flow", command: "npx", args: ["-y", "agentic-flow@alpha", "mcp", "start"], groups: ["agentic-flow"] },
{ name: "claude", command: "claude", args: ["mcp", "serve"], groups: ["claude-code"] },
{ name: "gemini-mcp", command: "npx", args: ["-y", "gemini-mcp-server"], groups: ["gemini"] },
- { name: "codex", command: "npx", args: ["-y", "@openai/codex", "mcp-server"], groups: ["codex"] },
];
const mcpBackends = new Map();
@@ -607,19 +610,7 @@ Requires: GOOGLE_API_KEY environment variable (already set for Gemini models).
codex: `# Codex Group
-OpenAI Codex coding agent.
-
-Requires: OPENAI_API_KEY environment variable (already set for OpenAI models).
-
-## Capabilities
-- Code generation and execution
-- Code completion
-- Code explanation
-
-## When to Use
-- Code generation tasks
-- Quick code completions
-- Code explanation and documentation`,
+Unavailable: current Codex CLI has no MCP server mode (#3509). This group is disabled even if MCP_GROUP_CODEX=true, so it exposes no tools. Use the separate Codex dual-mode worker through codex exec. A future MCP adapter requires its own execution and security design.`,
};
if (topic === "tool" && toolName) {
diff --git a/ruflo/tests/codex-mcp-backend-3509.test.mjs b/ruflo/tests/codex-mcp-backend-3509.test.mjs
new file mode 100644
index 0000000000..a8bc901728
--- /dev/null
+++ b/ruflo/tests/codex-mcp-backend-3509.test.mjs
@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+const bridges = [
+ '../src/mcp-bridge/index.js',
+ '../src/ruvocal/mcp-bridge/index.js',
+];
+
+for (const relativePath of bridges) {
+ test(`${relativePath}: removed Codex MCP mode does not delay other groups`, async t => {
+ const dir = mkdtempSync(join(tmpdir(), 'ruflo-codex-mcp-'));
+ const marker = join(dir, 'npx-spawned');
+ const fakeNpx = join(dir, 'npx');
+ writeFileSync(fakeNpx, '#!/bin/sh\nprintf launched > "$RUFLO_CODEX_SPAWN_MARKER"\nexit 1\n');
+ chmodSync(fakeNpx, 0o755);
+
+ const child = spawn(process.execPath, [fileURLToPath(new URL(relativePath, import.meta.url))], {
+ env: {
+ ...process.env,
+ PATH: `${dir}:${process.env.PATH ?? ''}`,
+ PORT: '0',
+ MCP_GROUP_INTELLIGENCE: 'false',
+ MCP_GROUP_AGENTS: 'false',
+ MCP_GROUP_MEMORY: 'false',
+ MCP_GROUP_DEVTOOLS: 'false',
+ MCP_GROUP_CODEX: 'true',
+ RUFLO_CODEX_SPAWN_MARKER: marker,
+ },
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ let stdout = '';
+ let stderr = '';
+ child.stdout.on('data', chunk => { stdout += chunk; });
+ child.stderr.on('data', chunk => { stderr += chunk; });
+ t.after(() => {
+ child.kill();
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ const deadline = Date.now() + 3000;
+ while (Date.now() < deadline && !stderr.includes('Codex CLI has no MCP server mode')) {
+ await new Promise(resolve => setTimeout(resolve, 25));
+ }
+ assert.match(stdout, /Active groups: core\s*$/m, `stdout: ${stdout}\nstderr: ${stderr}`);
+ assert.match(stderr, /Codex CLI has no MCP server mode/, stderr);
+ assert.equal(existsSync(marker), false, 'removed backend must not spawn npx');
+ });
+}
diff --git a/scripts/audit-codex-integration.mjs b/scripts/audit-codex-integration.mjs
index 1605b696dd..e50e49d6c1 100755
--- a/scripts/audit-codex-integration.mjs
+++ b/scripts/audit-codex-integration.mjs
@@ -26,18 +26,18 @@ const section = (t) => console.log(`\n${t}`);
console.log('Codex ↔ Ruflo integration audit (#1909)\n' + '─'.repeat(48));
-// ── 1. Codex MCP backend uses the real `mcp-server` subcommand ──────────────
-section('MCP backend registration (`codex` group):');
+// ── 1. The removed Codex MCP mode must not return as a dead backend ──────────
+section('Codex MCP backend retirement (#3509):');
for (const p of ['ruflo/src/mcp-bridge/index.js', 'ruflo/src/ruvocal/mcp-bridge/index.js']) {
if (!existsSync(resolve(ROOT, p))) { fail(`${p}: file missing`); continue; }
const src = read(p);
- const codexLine = (src.match(/.*@openai\/codex.*/g) ?? [])[0]?.trim() ?? '(no @openai/codex entry)';
- check(/@openai\/codex"\s*,\s*"mcp-server"/.test(src),
- `${p}: codex backend uses "mcp-server"`,
- `${p}: codex backend must use "mcp-server" β€” found: ${codexLine}`);
- check(!/@openai\/codex"\s*,\s*"mcp"\s*,\s*"serve"/.test(src),
- `${p}: no invalid "mcp serve" subcommand`,
- `${p}: still uses "mcp serve" (not a valid \`codex\` subcommand) β€” ${codexLine}`);
+ const codexGroup = src.match(/codex:\s*\{([^}]+)\}/)?.[1] ?? '';
+ check(/enabled:\s*false/.test(codexGroup),
+ `${p}: unsupported Codex MCP group stays disabled`);
+ check(!/\{\s*name:\s*"codex"\s*,\s*command:/.test(src),
+ `${p}: no backend launches the removed Codex MCP server`);
+ check(/MCP_GROUP_CODEX === "true"/.test(src) && /Codex CLI has no MCP server mode/.test(src),
+ `${p}: opt-in users receive a specific unsupported-mode diagnostic`);
}
// ── 2. @claude-flow/codex VERSION const tracks package.json ─────────────────