feat(workflows): support Codex MCP nodes

Author: borshyo

packages/docs-web/src/content/docs/guides/authoring-workflows.md

@@ -165,7 +165,7 @@ nodes:
     provider: claude             # Per-node provider override
     model: haiku                 # Per-node model override
     # hooks:                     # Optional: per-node SDK hook callbacks (Claude only) — see hooks guide
-    # mcp: .archon/mcp/servers.json  # Optional: per-node MCP servers (Claude only)
+    # mcp: .archon/mcp/servers.json  # Optional: per-node MCP servers (Codex and Claude)
     # skills: [remotion-best-practices]  # Optional: per-node skills (Claude only) — see skills guide
 ```
 
@@ -1173,7 +1173,7 @@ Before deploying a workflow:
 8. **`allowed_tools` / `denied_tools`** — restrict tools per node (Claude only, SDK-enforced)
 9. **`retry:`** — auto-retries transient errors (default: 2 retries / 3 total attempts, 3 s backoff); customize per node
 10. **`hooks`** — attach SDK hook callbacks to Claude nodes for tool control and context injection
-11. **`mcp:`** — attach per-node MCP servers via JSON config (Claude only)
+11. **`mcp:`** — attach per-node MCP servers via JSON config (Codex and Claude)
 12. **`skills:`** — preload skills into Claude nodes for domain expertise
 13. **`agents:`** — inline Claude sub-agent definitions invokable via the `Task` tool
 14. **`effort` / `thinking`** — control reasoning depth and thinking mode per node or workflow (Claude only)

packages/docs-web/src/content/docs/guides/mcp-servers.md

@@ -13,7 +13,8 @@ DAG workflow nodes support a `mcp` field that attaches MCP (Model Context Protoc
 servers to individual nodes. Each node gets exactly the external tools it needs —
 GitHub, Linear, Postgres, etc. — without over-provisioning.
 
-**Claude only** — Codex nodes will warn and ignore the `mcp` field.
+MCP works with Codex and Claude workflow nodes. Pi nodes still warn and ignore
+the `mcp` field.
 
 ## Quick Start
 
@@ -50,6 +51,9 @@ to the AI, and it shuts down when the node completes.
 MCP config files are JSON objects where each key is a server name and the value
 is a server configuration. Three transport types are supported:
 
+Archon also accepts the common wrapper format `{ "mcpServers": { ... } }`; this
+is useful when copying config from tools that already export MCP JSON.
+
 ### stdio (default)
 
 Runs a local process. This is the most common type.
@@ -119,8 +123,9 @@ Connects to an SSE endpoint.
 
 ## Environment Variable Expansion
 
-Values in `env` and `headers` fields support `$VAR_NAME` references that are
-expanded from `process.env` at execution time.
+Values in `env` and `headers` fields support `$VAR_NAME` references. They are
+expanded from Archon's process environment at execution time. Codex workflow
+nodes also include codebase-scoped env vars in that expansion.
 
 ```json
 {
@@ -165,21 +170,23 @@ A single config file can define multiple servers:
 }
 ```
 
-## Automatic Tool Wildcards
+## Provider Tool Wiring
 
-When a node loads MCP servers, tool wildcards are automatically added to `allowedTools`.
-For servers named `github` and `postgres`, the node gets:
+Claude nodes automatically add tool wildcards to `allowedTools`. For servers
+named `github` and `postgres`, the node gets:
 
 - `mcp__github__*`
 - `mcp__postgres__*`
 
-This means all tools from those servers are immediately available without manually
-listing them. The wildcards merge with any existing `allowed_tools` on the node.
+Codex nodes pass the same MCP config as per-node `mcp_servers` overrides to the
+Codex SDK, so the servers are available for that node without requiring global
+`~/.codex/config.toml` setup.
 
 ## MCP-Only Nodes
 
-Combine `mcp` with `allowed_tools: []` to create nodes that can only use MCP tools
-and have no access to built-in tools (Bash, Read, Write, etc.):
+For providers that support tool restrictions, combine `mcp` with
+`allowed_tools: []` to create nodes that can only use MCP tools and have no
+access to built-in tools (Bash, Read, Write, etc.):
 
 ```yaml
 nodes:
@@ -190,7 +197,9 @@ nodes:
 ```
 
 This is useful for sandboxing — the AI can only interact through the MCP server
-and cannot touch the filesystem or run shell commands.
+and cannot touch the filesystem or run shell commands. Codex currently does not
+support Archon's `allowed_tools` / `denied_tools` restrictions, so this pattern
+is enforced for Claude nodes but not Codex nodes.
 
 ## Connection Failure Handling
 
@@ -205,12 +214,12 @@ MCP server connection failed: github (failed)
 The node continues executing but without the tools from the failed server.
 Check your config file path, server command, and environment variables if this happens.
 
-User-level Claude plugin MCPs inherited from `~/.claude/` (e.g. `telegram`,
-`notion`) routinely fail to connect inside the headless workflow subprocess
-and are **not** surfaced here — they're not actionable for the workflow author.
-They appear only in debug logs as `dag.mcp_plugin_connection_suppressed`. Run
-the CLI with `--verbose` (or set `LOG_LEVEL=debug` on the server) if you need
-to see them.
+User-level plugin MCPs inherited from provider-specific user config routinely
+fail to connect inside headless workflow subprocesses and are **not** surfaced
+when the workflow did not configure MCP itself — they're not actionable for the
+workflow author. They appear only in debug logs as
+`dag.mcp_plugin_connection_suppressed` for Claude workflows. Run the CLI with
+`--verbose` (or set `LOG_LEVEL=debug` on the server) if you need to see them.
 
 ## Workflow Examples
 
@@ -368,8 +377,8 @@ bun run cli workflow run archon-smart-pr-review "Review PR #123"
 
 ## Limitations
 
-- **Claude only** — Codex nodes warn and ignore the `mcp` field. Configure MCP
-  servers globally in the Codex CLI config instead.
+- **Codex tool restrictions** — Codex nodes support `mcp`, but Archon's
+  `allowed_tools` / `denied_tools` restrictions are still ignored by Codex.
 - **Haiku model** — Tool search (lazy loading for many tools) is not supported on
   Haiku. You'll see a warning. Consider using Sonnet or Opus for MCP nodes.
 - **No load-time validation** — The MCP config file is read at execution time, not
@@ -386,8 +395,8 @@ bun run cli workflow run archon-smart-pr-review "Review PR #123"
 | `MCP config must be a JSON object` | Top-level value is array or string | Wrap in `{ "server-name": { ... } }` |
 | `undefined env vars: VAR_NAME` | Environment variable not set | Export the variable or add it to your `.env` |
 | `MCP server connection failed` | Server process crashed or URL unreachable | Check command/URL, test the server standalone |
-| Plugin MCP missing from workflow output | User-level plugin MCPs (from `~/.claude/`) are filtered out of workflow warnings | Run with `--verbose` and look for `dag.mcp_plugin_connection_suppressed` |
-| `mcp config but uses Codex` | Node resolved to Codex provider | Set `provider: claude` on the node or switch default |
+| Plugin MCP missing from workflow output | User-level plugin MCPs are filtered out of workflow warnings | Run with `--verbose` and look for provider MCP debug logs |
+| `allowed_tools` ignored with Codex | Codex provider does not support Archon's tool restrictions yet | Do not rely on `allowed_tools: []` for Codex sandboxing |
 | `Haiku model with MCP servers` | Haiku doesn't support tool search | Use `model: sonnet` or `model: opus` instead |
 
 ## Finding MCP Servers

packages/providers/package.json

@@ -13,6 +13,7 @@
     "./codex/provider": "./src/codex/provider.ts",
     "./codex/config": "./src/codex/config.ts",
     "./codex/binary-resolver": "./src/codex/binary-resolver.ts",
+    "./mcp/config": "./src/mcp/config.ts",
     "./community/pi": "./src/community/pi/index.ts",
     "./errors": "./src/errors.ts",
     "./registry": "./src/registry.ts"

packages/providers/src/claude/index.ts

@@ -1,8 +1,4 @@
 export { ClaudeProvider } from './provider';
 export { parseClaudeConfig, type ClaudeProviderDefaults } from './config';
-export {
-  loadMcpConfig,
-  buildSDKHooksFromYAML,
-  withFirstMessageTimeout,
-  getProcessUid,
-} from './provider';
+export { loadMcpConfig } from '../mcp/config';
+export { buildSDKHooksFromYAML, withFirstMessageTimeout, getProcessUid } from './provider';

packages/providers/src/claude/provider.ts

@@ -36,8 +36,7 @@ import { parseClaudeConfig } from './config';
 import { CLAUDE_CAPABILITIES } from './capabilities';
 import { resolveClaudeBinaryPath } from './binary-resolver';
 import { createLogger } from '@archon/paths';
-import { readFile } from 'fs/promises';
-import { resolve, isAbsolute } from 'path';
+import { loadMcpConfig } from '../mcp/config';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
 let cachedLog: ReturnType<typeof createLogger> | undefined;
@@ -199,96 +198,6 @@ export function getProcessUid(): number | undefined {
   return typeof process.getuid === 'function' ? process.getuid() : undefined;
 }
 
-// ─── MCP Config Loading (absorbed from dag-executor) ───────────────────────
-
-/**
- * Expand $VAR_NAME references in string-valued records from process.env.
- */
-function expandEnvVarsInRecord(
-  record: Record<string, unknown>,
-  missingVars: string[]
-): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [key, val] of Object.entries(record)) {
-    if (typeof val !== 'string') {
-      getLog().warn({ key, valueType: typeof val }, 'mcp_env_value_coerced_to_string');
-      result[key] = String(val);
-      continue;
-    }
-    result[key] = val.replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, varName: string) => {
-      const envVal = process.env[varName];
-      if (envVal === undefined) {
-        missingVars.push(varName);
-      }
-      return envVal ?? '';
-    });
-  }
-  return result;
-}
-
-function expandEnvVars(config: Record<string, unknown>): {
-  expanded: Record<string, unknown>;
-  missingVars: string[];
-} {
-  const result: Record<string, unknown> = {};
-  const missingVars: string[] = [];
-  for (const [serverName, serverConfig] of Object.entries(config)) {
-    if (typeof serverConfig !== 'object' || serverConfig === null) {
-      getLog().warn({ serverName, valueType: typeof serverConfig }, 'mcp_server_config_not_object');
-      continue;
-    }
-    const server = { ...(serverConfig as Record<string, unknown>) };
-    if (server.env && typeof server.env === 'object') {
-      server.env = expandEnvVarsInRecord(server.env as Record<string, unknown>, missingVars);
-    }
-    if (server.headers && typeof server.headers === 'object') {
-      server.headers = expandEnvVarsInRecord(
-        server.headers as Record<string, unknown>,
-        missingVars
-      );
-    }
-    result[serverName] = server;
-  }
-  return { expanded: result, missingVars };
-}
-
-/**
- * Load MCP server config from a JSON file and expand environment variables.
- */
-export async function loadMcpConfig(
-  mcpPath: string,
-  cwd: string
-): Promise<{ servers: Record<string, unknown>; serverNames: string[]; missingVars: string[] }> {
-  const fullPath = isAbsolute(mcpPath) ? mcpPath : resolve(cwd, mcpPath);
-
-  let raw: string;
-  try {
-    raw = await readFile(fullPath, 'utf-8');
-  } catch (err) {
-    const e = err as NodeJS.ErrnoException;
-    if (e.code === 'ENOENT') {
-      throw new Error(`MCP config file not found: ${mcpPath} (resolved to ${fullPath})`);
-    }
-    throw new Error(`Failed to read MCP config file: ${mcpPath} — ${e.message}`);
-  }
-
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(raw) as Record<string, unknown>;
-  } catch (parseErr) {
-    const detail = (parseErr as SyntaxError).message;
-    throw new Error(`MCP config file is not valid JSON: ${mcpPath} — ${detail}`);
-  }
-
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`MCP config must be a JSON object (Record<string, ServerConfig>): ${mcpPath}`);
-  }
-
-  const { expanded, missingVars } = expandEnvVars(parsed);
-  const serverNames = Object.keys(expanded);
-  return { servers: expanded, serverNames, missingVars };
-}
-
 // ─── SDK Hooks Building (absorbed from dag-executor) ───────────────────────
 
 /** YAML hook matcher shape (matches @archon/workflows/schemas/dag-node WorkflowNodeHooks) */

packages/providers/src/codex/capabilities.ts

@@ -2,7 +2,7 @@ import type { ProviderCapabilities } from '../types';
 
 export const CODEX_CAPABILITIES: ProviderCapabilities = {
   sessionResume: true,
-  mcp: false,
+  mcp: true,
   hooks: false,
   skills: false,
   agents: false,