@alvarosw/codex-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# Codex MCP
+
+A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes the local [Codex CLI](https://github.com/openai/codex) (`codex`) to MCP-compatible coding agents.
+
+The project intentionally keeps the architecture small: MCP tools validate inputs, a thin CLI adapter executes `codex exec` (and friends), and `codex_raw` provides an escape hatch for CLI options that are added in future Codex releases.
+
+## Features
+
+- Run Codex as a local coding agent through MCP (`codex exec`).
+- Run non-interactive code reviews (`codex exec review`).
+- Resume or fork previous sessions (`codex exec resume` / `codex exec fork`).
+- Control common CLI options such as model, sandbox policy, approval behavior, extra directories, images, and output handling.
+- Inspect version, login status, and diagnostics (`codex doctor`).
+- Pass arbitrary CLI arguments through `codex_raw` for forward compatibility.
+- No shell execution: arguments are passed directly to the `codex` process (`shell: false`).
+- Optional server-wide model override via an environment variable (see below).
+
+## Requirements
+
+- Node.js 18+
+- Codex CLI installed and authenticated (`codex login`)
+- `codex` available on `PATH`
+- An MCP-compatible client
+
+If `codex` is not on `PATH`, set `CODEX_MCP_CMD` to the executable path.
+
+```bash
+CODEX_MCP_CMD=/custom/path/codex
+```
+
+Windows PowerShell:
+
+```powershell
+$env:CODEX_MCP_CMD = "C:\path\to\codex.exe"
+```
+
+## Forcing a specific model
+
+Every tool that runs the agent (`codex_run`, `codex_review`, `codex_resume`, `codex_fork`, and `codex_raw` when its first argument is `exec`) accepts a `model` input. If you set the `CODEX_MCP_MODEL` environment variable on the MCP server process, it overrides the model for **every** such call, regardless of what the caller (or a raw argument list) requests. This is useful when you want to pin the server to a single model — for cost control, quota limits, or consistency — no matter what any individual tool call asks for.
+
+```bash
+CODEX_MCP_MODEL=your-model-id
+```
+
+The override is applied last, after stripping any `-m`/`--model` flag or `-c model=...` config override already present in the constructed arguments, so it always wins. It is never applied to subcommands that don't accept a model (`--version`, `login status`, `help`, `doctor`, ...), so those keep working normally even when the override is set.
+
+## Quick Start
+
+The recommended setup is through npm. You do not need to clone this repository or install the MCP server manually.
+
+### Claude Code
+
+```bash
+claude mcp add --scope user codex -- npx -y codex-mcp
+```
+
+Verify the server:
+
+```bash
+claude mcp list
+```
+
+If `codex` is not on `PATH`, or you want to pin the model:
+
+```bash
+claude mcp add --scope user \
+  --env CODEX_MCP_CMD=/custom/path/codex \
+  --env CODEX_MCP_MODEL=your-model-id \
+  codex -- npx -y codex-mcp
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add --scope user codex npx -y codex-mcp
+```
+
+Verify:
+
+```bash
+gemini mcp list
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "codex": {
+      "command": "npx",
+      "args": ["-y", "codex-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+```json
+{
+  "mcpServers": {
+    "codex": {
+      "command": "npx",
+      "args": ["-y", "codex-mcp"]
+    }
+  }
+}
+```
+
+### Cline / Roo Code / Other MCP Clients
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "codex-mcp"]
+}
+```
+
+If the client supports environment variables, `CODEX_MCP_CMD` and `CODEX_MCP_MODEL` can be set there as well.
+
+## Local Development
+
+```bash
+git clone https://github.com/alvarosw/codex-mcp.git
+cd codex-mcp
+npm install
+npm start
+```
+
+No build step is required.
+
+### Testing
+
+`npm test` runs a static syntax check only — it makes no network calls and costs nothing.
+
+`npm run test:live` drives the real MCP server end to end over stdio against a real, authenticated Codex CLI (in a throwaway temp git repo it creates and cleans up). It exercises every tool, including verifying that `CODEX_MCP_MODEL` (if set) wins over a deliberately wrong model passed in a tool call or smuggled into `codex_raw` arguments. This makes real model calls and is not run automatically — you need `codex login` completed first, and it will consume real quota/tokens against whichever model resolves for the call:
+
+```bash
+CODEX_MCP_MODEL=your-model-id npm run test:live
+```
+
+`CODEX_MCP_MODEL` is optional for this script; without it, the override-specific assertions are skipped and the rest of the suite still runs against your account's default configured model.
+
+## Tools
+
+### `codex_run`
+
+Run Codex as an agent non-interactively (`codex exec`) with common CLI controls: prompt, model, sandbox policy, approval routing, extra directories, images, working directory, ephemeral/persisted sessions, and raw passthrough args.
+
+Example:
+
+```json
+{
+  "prompt": "Review the authentication implementation and identify security issues.",
+  "cwd": "/workspace/project",
+  "sandbox": "workspace-write",
+  "addDirs": ["/workspace/shared"]
+}
+```
+
+### `codex_review`
+
+Runs `codex exec review` non-interactively against the current repository. Supports `uncommitted`, `base`, `commit`, and `title`, plus a custom review `prompt`.
+
+### `codex_resume`
+
+Resumes a previous session (`codex exec resume`) by `sessionId`, or the most recent one if omitted, optionally sending a new `prompt`.
+
+### `codex_fork`
+
+Forks a previous session (`codex exec fork`) by `sessionId` into a new session, optionally sending a `prompt`.
+
+### `codex_version`
+
+Returns the installed Codex CLI version.
+
+### `codex_login_status`
+
+Runs `codex login status` to check authentication state.
+
+### `codex_doctor`
+
+Runs `codex doctor --json` for install, auth, config, and connectivity diagnostics.
+
+### `codex_help`
+
+Shows CLI help. A command can be provided for command-specific help.
+
+### `codex_raw`
+
+Runs `codex` with an arbitrary argument array. This is the compatibility escape hatch for flags or commands not covered by the convenience tools. The model override, if set, still applies when the first argument is `exec`.
+
+Example:
+
+```json
+{
+  "args": ["mcp", "list"]
+}
+```
+
+## Architecture
+
+```text
+src/
+├── index.js   # MCP server and tool registration
+├── tools.js   # Tool behavior and response formatting (JSONL event parsing)
+└── codex.js   # Thin process adapter for the codex CLI + model-override enforcement
+```
+
+Dependency direction:
+
+```text
+MCP transport
+    ↓
+tool handlers
+    ↓
+codex CLI adapter
+    ↓
+local codex executable
+```
+
+There is intentionally no service container, repository layer, or framework abstraction. The project has one external process boundary and keeps that boundary explicit.
+
+Tools that invoke `codex exec*` request `--json` internally so output can be parsed reliably; each tool's text response is the agent's final message(s), with the full parsed event stream, command executions, token usage, and thread id available in `structuredContent` for programmatic consumers.
+
+## Security Notes
+
+`codex_raw` can execute arbitrary Codex CLI arguments with the permissions of the user running the MCP server. The server itself does not invoke a shell, so tool arguments are not shell-interpreted, but `codex` still has whatever permissions its sandbox and approval settings grant it.
+
+`dangerouslyBypassApprovalsAndSandbox` skips all confirmation prompts and sandboxing. Only use it when you explicitly trust the task and an already-isolated workspace.
+
+Environment variables passed through the `env` field are inherited by the `codex` process. Avoid sending secrets through MCP tool arguments unless necessary.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@alvarosw/codex-mcp",
+  "version": "1.0.0",
+  "description": "A lightweight MCP server that exposes the local Codex CLI to MCP-compatible coding agents.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "codex-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --check src/index.js && node --check src/codex.js && node --check src/tools.js",
+    "test:live": "node test/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "codex",
+    "openai",
+    "claude-code",
+    "agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "zod": "^3.23.8"
+  }
+}

package/src/codex.js

@@ -0,0 +1,176 @@
+import { spawn } from "node:child_process";
+
+function commandName() {
+  return process.env.CODEX_MCP_CMD || "codex";
+}
+
+function forcedModel() {
+  const value = process.env.CODEX_MCP_MODEL;
+  return value && value.trim() ? value.trim() : null;
+}
+
+/**
+ * Strips any user- or tool-supplied model selection (-m/--model, or a
+ * `-c model=...` / `--config model=...` config override) from an argument
+ * list, then appends a single `-m <override>` at the end. A trailing -m
+ * wins over an earlier -c model=... override, and clap resolves flags
+ * placed after positional arguments fine, so appending at the very end
+ * is sufficient to make the override authoritative for every call.
+ */
+export function applyModelOverride(args) {
+  const override = forcedModel();
+  if (!override) return args;
+
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+
+    if (a === "-m" || a === "--model") {
+      i++; // also skip its value
+      continue;
+    }
+    if (a.startsWith("--model=")) continue;
+
+    if (a === "-c" || a === "--config") {
+      const val = args[i + 1] ?? "";
+      if (/^model\s*=/.test(val)) {
+        i++; // also skip its value
+        continue;
+      }
+      out.push(a);
+      continue;
+    }
+    if (a.startsWith("-c=") || a.startsWith("--config=")) {
+      const val = a.slice(a.indexOf("=") + 1);
+      if (/^model\s*=/.test(val)) continue;
+    }
+
+    out.push(a);
+  }
+
+  out.push("-m", override);
+  return out;
+}
+
+export function runCodex(codexArgs, options = {}) {
+  const args = Array.isArray(codexArgs) ? codexArgs : [];
+  const cwd = options.cwd || process.cwd();
+  const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;
+  const env = { ...process.env, ...(options.env || {}) };
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(commandName(), args, {
+      cwd,
+      env,
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      fn(value);
+    };
+
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(reject, new Error(`codex timed out after ${timeoutMs} ms`));
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      finish(reject, error);
+    });
+
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      const result = {
+        command: commandName(),
+        args,
+        cwd,
+        exitCode: code,
+        signal,
+        stdout: stdout.trim(),
+        stderr: stderr.trim()
+      };
+      finish(resolve, result);
+    });
+  });
+}
+
+// Flags shared by every `codex exec*` subcommand (run, review, resume, fork).
+// NOTE: -C/--cd, --add-dir, and -i/--image are deliberately NOT here — per
+// `codex exec <subcommand> --help`, -C and --add-dir only exist on bare
+// `codex exec`, and -i doesn't exist on `codex exec review` at all. They are
+// added individually only where the CLI actually accepts them.
+function pushCommon(args, input) {
+  if (input.ephemeral !== false) args.push("--ephemeral");
+  if (input.skipGitRepoCheck !== false) args.push("--skip-git-repo-check");
+  if (input.ignoreRules === true) args.push("--ignore-rules");
+  if (input.model) args.push("-m", input.model);
+  if (input.outputSchema) args.push("--output-schema", input.outputSchema);
+  if (input.outputLastMessage) args.push("-o", input.outputLastMessage);
+  if (input.dangerouslyBypassApprovalsAndSandbox === true) {
+    args.push("--dangerously-bypass-approvals-and-sandbox");
+  }
+  if (Array.isArray(input.extraArgs)) args.push(...input.extraArgs);
+}
+
+export function buildRunArgs(input) {
+  const args = ["exec", "--json"];
+  if (input.sandbox) args.push("--sandbox", input.sandbox);
+  if (input.approveForMe === true) args.push("--approve-for-me");
+  if (input.cd) args.push("-C", input.cd);
+  if (Array.isArray(input.addDirs)) {
+    for (const dir of input.addDirs) args.push("--add-dir", dir);
+  }
+  if (Array.isArray(input.images) && input.images.length) {
+    args.push("-i", ...input.images);
+  }
+  pushCommon(args, input);
+  if (input.prompt) args.push(input.prompt);
+  return applyModelOverride(args);
+}
+
+export function buildReviewArgs(input) {
+  const args = ["exec", "review", "--json"];
+  if (input.uncommitted === true) args.push("--uncommitted");
+  if (input.base) args.push("--base", input.base);
+  if (input.commit) args.push("--commit", input.commit);
+  if (input.title) args.push("--title", input.title);
+  pushCommon(args, { ...input, skipGitRepoCheck: input.skipGitRepoCheck ?? false });
+  if (input.prompt) args.push(input.prompt);
+  return applyModelOverride(args);
+}
+
+export function buildResumeArgs(input) {
+  const args = ["exec", "resume", "--json"];
+  if (input.all === true) args.push("--all");
+  pushCommon(args, input);
+  if (input.sessionId) args.push(input.sessionId);
+  else args.push("--last");
+  if (input.prompt) args.push(input.prompt);
+  return applyModelOverride(args);
+}
+
+export function buildForkArgs(input) {
+  if (!input.sessionId) throw new Error("sessionId is required to fork a session");
+  const args = ["exec", "fork", "--json"];
+  pushCommon(args, input);
+  args.push(input.sessionId);
+  if (input.prompt) args.push(input.prompt);
+  return applyModelOverride(args);
+}

package/src/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  codexDoctor,
+  codexFork,
+  codexHelp,
+  codexLoginStatus,
+  codexResume,
+  codexReview,
+  codexRun,
+  codexRaw,
+  codexVersion
+} from "./tools.js";
+
+const server = new McpServer({
+  name: "codex-mcp",
+  version: "1.0.0"
+});
+
+const common = {
+  cwd: z.string().optional().describe("Working directory for the codex process."),
+  timeoutMs: z.number().int().positive().optional().describe("Process timeout in milliseconds."),
+  env: z.record(z.string()).optional().describe("Additional environment variables for codex.")
+};
+
+// Flags shared by every `codex exec*` subcommand (run, review, resume, fork).
+// cd/addDirs/images are intentionally excluded here — the underlying CLI
+// only accepts -C/--cd and --add-dir on bare `codex exec`, and doesn't
+// accept -i/--image on `codex exec review` at all. Those are declared only
+// on the tool schemas that actually support them.
+const runControls = {
+  model: z.string().optional().describe("Model the agent should use. May be forced by the server's model-override environment variable."),
+  ephemeral: z.boolean().optional().describe("Skip persisting session files to disk. Defaults to true."),
+  skipGitRepoCheck: z.boolean().optional().describe("Allow running outside a Git repository. Defaults to true."),
+  ignoreRules: z.boolean().optional().describe("Do not load user or project execpolicy .rules files."),
+  outputSchema: z.string().optional().describe("Path to a JSON Schema file describing the expected final response shape."),
+  outputLastMessage: z.string().optional().describe("Path to a file where the final agent message should be written."),
+  dangerouslyBypassApprovalsAndSandbox: z.boolean().optional().describe("Skip all confirmation prompts and sandboxing. Only use in an already-isolated environment."),
+  extraArgs: z.array(z.string()).optional().describe("Additional raw codex CLI arguments appended to the command.")
+};
+
+server.registerTool("codex_run", {
+  description: "Run the Codex agent non-interactively (`codex exec`) with common CLI controls.",
+  inputSchema: {
+    prompt: z.string().describe("Task for the Codex agent."),
+    sandbox: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional().describe("Sandbox policy for model-generated shell commands."),
+    approveForMe: z.boolean().optional().describe("Route approval requests through automatic review using the workspace-write sandbox."),
+    cd: z.string().optional().describe("Directory codex should treat as its working root (--cd)."),
+    addDirs: z.array(z.string()).optional().describe("Additional directories to expose to the agent (--add-dir)."),
+    images: z.array(z.string()).optional().describe("Image file paths to attach to the prompt."),
+    ...runControls,
+    ...common
+  }
+}, codexRun);
+
+server.registerTool("codex_review", {
+  description: "Run a non-interactive Codex code review (`codex exec review`) against the current repository.",
+  inputSchema: {
+    prompt: z.string().optional().describe("Custom review instructions."),
+    uncommitted: z.boolean().optional().describe("Review staged, unstaged, and untracked changes."),
+    base: z.string().optional().describe("Review changes against the given base branch."),
+    commit: z.string().optional().describe("Review the changes introduced by a single commit."),
+    title: z.string().optional().describe("Optional commit title to display in the review summary."),
+    ...runControls,
+    ...common
+  }
+}, codexReview);
+
+server.registerTool("codex_resume", {
+  description: "Resume a previous Codex session non-interactively (`codex exec resume`) and optionally send a new prompt.",
+  inputSchema: {
+    sessionId: z.string().optional().describe("Conversation/session id (UUID) or thread name. Omit to resume the most recent session."),
+    all: z.boolean().optional().describe("Search across all directories, not just the current one."),
+    prompt: z.string().optional().describe("Prompt to send after resuming the session."),
+    ...runControls,
+    ...common
+  }
+}, codexResume);
+
+server.registerTool("codex_fork", {
+  description: "Fork a previous Codex session (`codex exec fork`) into a new session and optionally send a prompt.",
+  inputSchema: {
+    sessionId: z.string().describe("Conversation/session id (UUID) or thread name to fork."),
+    prompt: z.string().optional().describe("Optional prompt to send after forking."),
+    ...runControls,
+    ...common
+  }
+}, codexFork);
+
+server.registerTool("codex_version", {
+  description: "Return the installed Codex CLI version.",
+  inputSchema: common
+}, codexVersion);
+
+server.registerTool("codex_login_status", {
+  description: "Check Codex CLI authentication status (`codex login status`).",
+  inputSchema: common
+}, codexLoginStatus);
+
+server.registerTool("codex_doctor", {
+  description: "Run Codex's built-in diagnostics (`codex doctor --json`): install, auth, config, and connectivity health.",
+  inputSchema: common
+}, codexDoctor);
+
+server.registerTool("codex_help", {
+  description: "Show Codex CLI help, optionally for a specific subcommand.",
+  inputSchema: {
+    command: z.string().optional(),
+    ...common
+  }
+}, codexHelp);
+
+server.registerTool("codex_raw", {
+  description: "Run the Codex CLI with an arbitrary argument array. Escape hatch for options not covered by the other tools. The server's model-override environment variable, if set, still applies.",
+  inputSchema: {
+    args: z.array(z.string()),
+    ...common
+  }
+}, codexRaw);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools.js

@@ -0,0 +1,178 @@
+import {
+  applyModelOverride,
+  buildForkArgs,
+  buildResumeArgs,
+  buildReviewArgs,
+  buildRunArgs,
+  runCodex
+} from "./codex.js";
+
+function textResult(text, structuredContent) {
+  return {
+    content: [{ type: "text", text }],
+    ...(structuredContent ? { structuredContent } : {})
+  };
+}
+
+function parseJsonl(output) {
+  const events = [];
+  for (const line of output.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      events.push({ type: "raw", line: trimmed });
+    }
+  }
+  return events;
+}
+
+function summarizeEvents(events) {
+  const summary = {
+    threadId: null,
+    agentMessages: [],
+    commandExecutions: [],
+    errors: [],
+    usage: null,
+    turnStatus: "unknown"
+  };
+
+  for (const event of events) {
+    switch (event.type) {
+      case "thread.started":
+        summary.threadId = event.thread_id ?? summary.threadId;
+        break;
+      case "turn.completed":
+        summary.turnStatus = "completed";
+        summary.usage = event.usage ?? summary.usage;
+        break;
+      case "turn.failed":
+        summary.turnStatus = "failed";
+        if (event.error) summary.errors.push(event.error.message ?? String(event.error));
+        break;
+      case "error":
+        summary.errors.push(event.message ?? "unknown error");
+        break;
+      case "item.completed":
+      case "item.started": {
+        const item = event.item;
+        if (!item) break;
+        if (item.type === "agent_message" && item.text) {
+          summary.agentMessages.push(item.text);
+        } else if (item.type === "command_execution") {
+          summary.commandExecutions.push({
+            command: item.command,
+            exitCode: item.exit_code,
+            status: item.status,
+            output: item.aggregated_output
+          });
+        } else if (item.type === "error" && item.message) {
+          summary.errors.push(item.message);
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  return summary;
+}
+
+/** Formats the JSONL output of a `codex exec*` invocation into a readable
+ * text reply plus a structured payload for programmatic consumers. */
+function formatExecResult(result) {
+  const events = parseJsonl(result.stdout);
+  const summary = summarizeEvents(events);
+
+  const parts = [];
+  if (summary.agentMessages.length) {
+    parts.push(summary.agentMessages.join("\n\n"));
+  }
+  if (summary.errors.length) {
+    parts.push(`Errors:\n${summary.errors.join("\n")}`);
+  }
+  if (!parts.length) {
+    parts.push(result.stdout || result.stderr || "(no output)");
+  }
+  if (result.exitCode !== 0) {
+    parts.push(`(codex exited with code ${result.exitCode})`);
+  }
+
+  return textResult(parts.join("\n\n"), {
+    threadId: summary.threadId,
+    turnStatus: summary.turnStatus,
+    usage: summary.usage,
+    commandExecutions: summary.commandExecutions,
+    errors: summary.errors,
+    exitCode: result.exitCode,
+    events
+  });
+}
+
+function formatPlainResult(result) {
+  const output = result.stdout || result.stderr || "";
+  return textResult(output, { exitCode: result.exitCode, stderr: result.stderr });
+}
+
+function processOptions(input) {
+  return { cwd: input.cwd, timeoutMs: input.timeoutMs, env: input.env };
+}
+
+export async function codexRun(input) {
+  if (!input.prompt?.trim()) throw new Error("prompt is required");
+  const args = buildRunArgs(input);
+  const result = await runCodex(args, processOptions(input));
+  return formatExecResult(result);
+}
+
+export async function codexReview(input = {}) {
+  const args = buildReviewArgs(input);
+  const result = await runCodex(args, processOptions(input));
+  return formatExecResult(result);
+}
+
+export async function codexResume(input = {}) {
+  const args = buildResumeArgs(input);
+  const result = await runCodex(args, processOptions(input));
+  return formatExecResult(result);
+}
+
+export async function codexFork(input) {
+  if (!input.sessionId?.trim()) throw new Error("sessionId is required");
+  const args = buildForkArgs(input);
+  const result = await runCodex(args, processOptions(input));
+  return formatExecResult(result);
+}
+
+export async function codexVersion(input = {}) {
+  const result = await runCodex(["--version"], processOptions(input));
+  return formatPlainResult(result);
+}
+
+export async function codexLoginStatus(input = {}) {
+  const result = await runCodex(["login", "status"], processOptions(input));
+  return formatPlainResult(result);
+}
+
+export async function codexDoctor(input = {}) {
+  const result = await runCodex(["doctor", "--json"], processOptions(input));
+  return formatPlainResult(result);
+}
+
+export async function codexHelp(input = {}) {
+  const args = input.command ? ["help", input.command] : ["help"];
+  const result = await runCodex(args, processOptions(input));
+  return formatPlainResult(result);
+}
+
+export async function codexRaw(input) {
+  if (!Array.isArray(input.args)) throw new Error("args must be an array");
+  // Only exec-family invocations accept -m/--model; leave other subcommands
+  // (login, doctor, help, mcp, ...) untouched so the override never injects
+  // an unrecognized flag into a command that doesn't take one.
+  const args = input.args[0] === "exec" ? applyModelOverride(input.args) : input.args;
+  const result = await runCodex(args, processOptions(input));
+  return formatPlainResult(result);
+}

package/test/smoke.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Manual, live end-to-end smoke test for codex-mcp.
+//
+// This spawns the real MCP server and drives it over stdio with the real
+// @modelcontextprotocol/sdk Client, exercising every registered tool against
+// a real, authenticated Codex CLI. It makes real model calls and is NOT run
+// by `npm test` (which only does a static syntax check) because it costs
+// real quota/tokens against whatever model resolves for the caller.
+//
+// Usage:
+//   CODEX_MCP_MODEL=<your-model> node test/smoke.mjs
+//
+// Setting CODEX_MCP_MODEL is optional but strongly recommended: it proves
+// the override wins even when a tool call or raw arg list requests a
+// different (here, intentionally bogus) model.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const overrideModel = process.env.CODEX_MCP_MODEL;
+const badModel = "definitely-not-a-real-model"; // must never resolve to any real, billable provider
+
+function assert(condition, message) {
+  if (!condition) throw new Error(`ASSERTION FAILED: ${message}`);
+  console.log(`  ok - ${message}`);
+}
+
+const repoDir = mkdtempSync(join(tmpdir(), "codex-mcp-smoke-"));
+execFileSync("git", ["init", "-q"], { cwd: repoDir });
+execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoDir });
+execFileSync("git", ["config", "user.name", "test"], { cwd: repoDir });
+writeFileSync(
+  join(repoDir, "math.js"),
+  "function add(a, b) {\n  return a - b; // bug: should be a + b\n}\nmodule.exports = { add };\n"
+);
+execFileSync("git", ["add", "math.js"], { cwd: repoDir });
+
+const transport = new StdioClientTransport({
+  command: "node",
+  args: [new URL("../src/index.js", import.meta.url).pathname],
+  env: { ...process.env }
+});
+const client = new Client({ name: "smoke-test", version: "1.0.0" });
+await client.connect(transport);
+
+try {
+  console.log("\n=== tools/list ===");
+  const tools = await client.listTools();
+  const names = tools.tools.map((t) => t.name);
+  console.log(names.join(", "));
+  for (const expected of ["codex_run", "codex_review", "codex_resume", "codex_fork", "codex_version", "codex_login_status", "codex_doctor", "codex_help", "codex_raw"]) {
+    assert(names.includes(expected), `${expected} is registered`);
+  }
+
+  console.log("\n=== codex_version ===");
+  const version = await client.callTool({ name: "codex_version", arguments: {} });
+  assert(!version.isError, "codex_version did not error");
+  console.log(version.content[0].text);
+
+  console.log("\n=== codex_login_status ===");
+  const login = await client.callTool({ name: "codex_login_status", arguments: {} });
+  assert(!login.isError, "codex_login_status did not error");
+  console.log(login.content[0].text);
+
+  console.log(`\n=== codex_run: tool arg requests bogus model "${badModel}"${overrideModel ? "; env override must win" : "; no override set, expect failure" } ===`);
+  const run = await client.callTool({
+    name: "codex_run",
+    arguments: {
+      prompt: "Reply with exactly the single word: PONG",
+      model: badModel,
+      ephemeral: false,
+      cwd: repoDir,
+      timeoutMs: 60000
+    }
+  });
+  console.log("TEXT:", run.content[0].text);
+  if (overrideModel) {
+    assert(!run.isError && run.structuredContent?.turnStatus === "completed", "override forced a working model despite bogus tool-supplied model");
+    assert(run.content[0].text.includes("PONG"), "agent replied PONG using the overridden model");
+  } else {
+    console.log("  (no CODEX_MCP_MODEL set - skipping override assertion)");
+  }
+  const threadId = run.structuredContent?.threadId;
+
+  console.log("\n=== codex_raw: raw args also sneak in a bogus -m; override must still win when set ===");
+  const raw = await client.callTool({
+    name: "codex_raw",
+    arguments: {
+      args: ["exec", "--json", "--ephemeral", "--skip-git-repo-check", "-m", badModel, "Reply with exactly the single word: RAWPONG"],
+      cwd: repoDir,
+      timeoutMs: 60000
+    }
+  });
+  console.log("TEXT:", raw.content[0].text);
+  if (overrideModel) {
+    assert(!raw.isError && raw.content[0].text.includes("RAWPONG"), "override stripped the bogus -m from raw args and still succeeded");
+  }
+
+  console.log("\n=== codex_raw: override must NOT be injected into non-exec subcommands ===");
+  const rawHelp = await client.callTool({ name: "codex_raw", arguments: { args: ["--version"] } });
+  assert(!rawHelp.isError, "codex_raw --version unaffected by model override scoping");
+  console.log(rawHelp.content[0].text);
+
+  console.log("\n=== codex_help ===");
+  const help = await client.callTool({ name: "codex_help", arguments: {} });
+  assert(!help.isError, "codex_help did not error");
+  console.log(help.content[0].text.slice(0, 120));
+
+  console.log("\n=== codex_doctor ===");
+  const doctor = await client.callTool({ name: "codex_doctor", arguments: {} });
+  assert(!doctor.isError, "codex_doctor did not error");
+  console.log(doctor.content[0].text.slice(0, 120), "...");
+
+  console.log("\n=== codex_review: uncommitted change with a deliberate bug ===");
+  const review = await client.callTool({
+    name: "codex_review",
+    arguments: { uncommitted: true, cwd: repoDir, timeoutMs: 90000 }
+  });
+  assert(!review.isError, "codex_review did not error");
+  console.log("TEXT:", review.content[0].text.slice(0, 400));
+
+  console.log("\n=== codex_fork: missing required sessionId must surface as a tool error ===");
+  const fork = await client.callTool({ name: "codex_fork", arguments: {} });
+  assert(fork.isError === true, "codex_fork without sessionId reports isError");
+  console.log(fork.content[0].text);
+
+  if (threadId) {
+    console.log("\n=== codex_resume: recall context from the earlier codex_run ===");
+    const resume = await client.callTool({
+      name: "codex_resume",
+      arguments: {
+        sessionId: threadId,
+        prompt: "What single word did you just reply with in your previous message? Answer with just that one word.",
+        cwd: repoDir,
+        timeoutMs: 60000
+      }
+    });
+    console.log("TEXT:", resume.content[0].text);
+    if (overrideModel) assert(!resume.isError, "codex_resume did not error");
+  }
+
+  console.log("\nALL CHECKS PASSED");
+} finally {
+  await client.close();
+  rmSync(repoDir, { recursive: true, force: true });
+}