π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdindex 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 MCPruflo__agent_spawn β ruflo MCPclaude__Read β Claude Code MCPgemini__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=trueGOOGLE_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 Considerations1. **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.jsindex 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.mdindex 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 MCPruflo__agent_spawn β ruflo MCPclaude__Read β Claude Code MCPgemini__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=trueGOOGLE_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 Considerations1. **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.jsindex 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.mjsnew file mode 100644index 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.mjsindex 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 βββββββββββββββββ