ai-sdk-provider-codex-cli 0.5.1 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/ben-vargas/ai-sdk-provider-codex-cli/issues)
 [![Latest Release](https://img.shields.io/github/v/release/ben-vargas/ai-sdk-provider-codex-cli?display_name=tag)](https://github.com/ben-vargas/ai-sdk-provider-codex-cli/releases/latest)
 
-A community provider for Vercel AI SDK v5 that uses OpenAI’s Codex CLI (non‑interactive `codex exec`) to talk to GPT‑5.1 class models (`gpt-5.1`, the Codex-specific `gpt-5.1-codex`, and the lightweight `gpt-5.1-codex-mini` slugs) with your ChatGPT Plus/Pro subscription. The provider spawns the Codex CLI process, parses its JSONL output, and adapts it to the AI SDK LanguageModelV2 interface. Legacy GPT-5 / GPT-5-codex slugs remain compatible for existing workflows.
+A community provider for Vercel AI SDK v5 that uses OpenAI’s Codex CLI (non‑interactive `codex exec`) to talk to GPT‑5.1 class models (`gpt-5.1`, the Codex-specific `gpt-5.1-codex`, the flagship `gpt-5.1-codex-max`, and the lightweight `gpt-5.1-codex-mini` slugs) with your ChatGPT Plus/Pro subscription. The provider spawns the Codex CLI process, parses its JSONL output, and adapts it to the AI SDK LanguageModelV2 interface. Legacy GPT-5 / GPT-5-codex slugs remain compatible for existing workflows.
 
 - Works with `generateText`, `streamText`, and `generateObject` (native JSON Schema support via `--output-schema`)
 - Uses ChatGPT OAuth from `codex login` (tokens in `~/.codex/auth.json`) or `OPENAI_API_KEY`
@@ -28,7 +28,7 @@ npm i -g @openai/codex
 codex login   # or set OPENAI_API_KEY
 ```
 
-> **⚠️ Version Requirement**: Requires Codex CLI **>= 0.42.0** for `--experimental-json` and `--output-schema` support. **>= 0.44.0 recommended** for full usage tracking and tool streaming support. Check your version with `codex --version` and upgrade if needed:
+> **⚠️ Version Requirement**: Requires Codex CLI **>= 0.42.0** for `--experimental-json` and `--output-schema` support. **>= 0.60.0 recommended** for `gpt-5.1-codex-max` and `xhigh` reasoning effort. If you supply your own Codex CLI (global install or custom `codexPath`/`allowNpx`), check it with `codex --version` and upgrade if needed. The optional dependency `@openai/codex` in this package pulls a compatible version automatically.
 >
 > ```bash
 > npm i -g @openai/codex@latest
@@ -223,6 +223,7 @@ When OpenAI adds streaming support, this provider will be updated to handle thos
 
 - `allowNpx`: If true, falls back to `npx -y @openai/codex` when Codex is not on PATH
 - `cwd`: Working directory for Codex
+- `addDirs`: Extra directories Codex may read/write (repeats `--add-dir`)
 - Autonomy/sandbox:
   - `fullAuto` (equivalent to `--full-auto`)
   - `dangerouslyBypassApprovalsAndSandbox` (bypass approvals and sandbox; dangerous)
@@ -246,9 +247,10 @@ import { codexCli } from 'ai-sdk-provider-codex-cli';
 const model = codexCli('gpt-5.1-codex', {
   allowNpx: true,
   skipGitRepoCheck: true,
+  addDirs: ['../shared'],
 
   // Reasoning & verbosity
-  reasoningEffort: 'medium', // minimal | low | medium | high
+  reasoningEffort: 'medium', // minimal | low | medium | high | xhigh (xhigh only on gpt-5.1-codex-max)
   reasoningSummary: 'auto', // auto | detailed (Note: 'concise' and 'none' are rejected by API)
   reasoningSummaryFormat: 'none', // none | experimental
   modelVerbosity: 'high', // low | medium | high
@@ -259,6 +261,23 @@ const model = codexCli('gpt-5.1-codex', {
   oss: false, // adds --oss when true
   webSearch: true, // maps to -c tools.web_search=true
 
+  // MCP servers (stdio + HTTP/RMCP)
+  rmcpClient: true, // enables HTTP-based MCP clients (features.rmcp_client=true)
+  mcpServers: {
+    local: {
+      transport: 'stdio',
+      command: 'node',
+      args: ['tools/mcp.js'],
+      env: { API_KEY: process.env.MCP_API_KEY ?? '' },
+    },
+    docs: {
+      transport: 'http',
+      url: 'https://mcp.my-org.com',
+      bearerTokenEnvVar: 'MCP_BEARER',
+      httpHeaders: { 'x-tenant': 'acme' },
+    },
+  },
+
   // Generic overrides (maps to -c key=value)
   configOverrides: {
     experimental_resume: '/tmp/session.jsonl',
@@ -269,6 +288,7 @@ const model = codexCli('gpt-5.1-codex', {
 
 Nested override objects are flattened to dotted keys (e.g., the example above emits
 `-c sandbox_workspace_write.network_access=true`). Arrays are serialized to JSON strings.
+MCP server env/header objects flatten the same way (e.g., `mcp_servers.docs.http_headers.x-tenant=acme`).
 
 ### Per-call overrides via `providerOptions` (v0.4.0+)
 
@@ -293,6 +313,14 @@ const response = await generateText({
       reasoningEffort: 'high',
       reasoningSummary: 'detailed',
       textVerbosity: 'high', // AI SDK naming; maps to model_verbosity
+      rmcpClient: true,
+      mcpServers: {
+        scratch: {
+          transport: 'stdio',
+          command: 'pnpm',
+          args: ['mcp', 'serve'],
+        },
+      },
       configOverrides: {
         experimental_resume: '/tmp/resume.jsonl',
       },

package/dist/index.cjs

@@ -68,9 +68,37 @@ var loggerFunctionSchema = zod.z.object({
     message: "error must be a function"
   })
 });
+var mcpServerBaseSchema = zod.z.object({
+  enabled: zod.z.boolean().optional(),
+  startupTimeoutSec: zod.z.number().int().positive().optional(),
+  toolTimeoutSec: zod.z.number().int().positive().optional(),
+  enabledTools: zod.z.array(zod.z.string()).optional(),
+  disabledTools: zod.z.array(zod.z.string()).optional()
+});
+var mcpServerStdioSchema = mcpServerBaseSchema.extend({
+  transport: zod.z.literal("stdio"),
+  command: zod.z.string().min(1),
+  args: zod.z.array(zod.z.string()).optional(),
+  env: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+  cwd: zod.z.string().optional()
+});
+var mcpServerHttpSchema = mcpServerBaseSchema.extend({
+  transport: zod.z.literal("http"),
+  url: zod.z.string().min(1),
+  bearerToken: zod.z.string().optional(),
+  bearerTokenEnvVar: zod.z.string().optional(),
+  httpHeaders: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+  envHttpHeaders: zod.z.record(zod.z.string(), zod.z.string()).optional()
+});
+var mcpServerSchema = zod.z.discriminatedUnion("transport", [
+  mcpServerStdioSchema,
+  mcpServerHttpSchema
+]);
+var mcpServersSchema = zod.z.record(zod.z.string(), mcpServerSchema);
 var settingsSchema = zod.z.object({
   codexPath: zod.z.string().optional(),
   cwd: zod.z.string().optional(),
+  addDirs: zod.z.array(zod.z.string().min(1)).optional(),
   approvalMode: zod.z.enum(["untrusted", "on-failure", "on-request", "never"]).optional(),
   sandboxMode: zod.z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
   fullAuto: zod.z.boolean().optional(),
@@ -78,11 +106,12 @@ var settingsSchema = zod.z.object({
   skipGitRepoCheck: zod.z.boolean().optional(),
   color: zod.z.enum(["always", "never", "auto"]).optional(),
   allowNpx: zod.z.boolean().optional(),
+  outputLastMessageFile: zod.z.string().optional(),
   env: zod.z.record(zod.z.string(), zod.z.string()).optional(),
   verbose: zod.z.boolean().optional(),
   logger: zod.z.union([zod.z.literal(false), loggerFunctionSchema]).optional(),
   // NEW: Reasoning & Verbosity
-  reasoningEffort: zod.z.enum(["minimal", "low", "medium", "high"]).optional(),
+  reasoningEffort: zod.z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
   // Note: API rejects 'concise' and 'none' despite error messages claiming they're valid
   reasoningSummary: zod.z.enum(["auto", "detailed"]).optional(),
   reasoningSummaryFormat: zod.z.enum(["none", "experimental"]).optional(),
@@ -92,6 +121,8 @@ var settingsSchema = zod.z.object({
   profile: zod.z.string().optional(),
   oss: zod.z.boolean().optional(),
   webSearch: zod.z.boolean().optional(),
+  mcpServers: mcpServersSchema.optional(),
+  rmcpClient: zod.z.boolean().optional(),
   // NEW: Generic overrides
   configOverrides: zod.z.record(
     zod.z.string(),
@@ -231,10 +262,11 @@ function isAuthenticationError(err) {
 
 // src/codex-cli-language-model.ts
 var codexCliProviderOptionsSchema = zod.z.object({
-  reasoningEffort: zod.z.enum(["minimal", "low", "medium", "high"]).optional(),
+  reasoningEffort: zod.z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
   reasoningSummary: zod.z.enum(["auto", "detailed"]).optional(),
   reasoningSummaryFormat: zod.z.enum(["none", "experimental"]).optional(),
   textVerbosity: zod.z.enum(["low", "medium", "high"]).optional(),
+  addDirs: zod.z.array(zod.z.string().min(1)).optional(),
   configOverrides: zod.z.record(
     zod.z.string(),
     zod.z.union([
@@ -244,7 +276,9 @@ var codexCliProviderOptionsSchema = zod.z.object({
       zod.z.object({}).passthrough(),
       zod.z.array(zod.z.any())
     ])
-  ).optional()
+  ).optional(),
+  mcpServers: mcpServersSchema.optional(),
+  rmcpClient: zod.z.boolean().optional()
 }).strict();
 function resolveCodexPath(explicitPath, allowNpx) {
   if (explicitPath) return { cmd: "node", args: [explicitPath] };
@@ -286,15 +320,80 @@ var CodexCliLanguageModel = class {
       ...this.settings.configOverrides ?? {},
       ...providerOptions.configOverrides ?? {}
     } : void 0;
+    const mergedAddDirs = providerOptions.addDirs || this.settings.addDirs ? [...this.settings.addDirs ?? [], ...providerOptions.addDirs ?? []] : void 0;
+    const mergedMcpServers = this.mergeMcpServers(
+      this.settings.mcpServers,
+      providerOptions.mcpServers
+    );
     return {
       ...this.settings,
       reasoningEffort: providerOptions.reasoningEffort ?? this.settings.reasoningEffort,
       reasoningSummary: providerOptions.reasoningSummary ?? this.settings.reasoningSummary,
       reasoningSummaryFormat: providerOptions.reasoningSummaryFormat ?? this.settings.reasoningSummaryFormat,
       modelVerbosity: providerOptions.textVerbosity ?? this.settings.modelVerbosity,
-      configOverrides: mergedConfigOverrides
+      configOverrides: mergedConfigOverrides,
+      addDirs: mergedAddDirs,
+      mcpServers: mergedMcpServers,
+      rmcpClient: providerOptions.rmcpClient ?? this.settings.rmcpClient
     };
   }
+  mergeMcpServers(base, override) {
+    if (!base) return override;
+    if (!override) return base;
+    const merged = { ...base };
+    for (const [name, incoming] of Object.entries(override)) {
+      const existing = base[name];
+      merged[name] = this.mergeSingleMcpServer(existing, incoming);
+    }
+    return merged;
+  }
+  mergeSingleMcpServer(existing, incoming) {
+    if (!existing || existing.transport !== incoming.transport) {
+      return { ...incoming };
+    }
+    if (incoming.transport === "stdio") {
+      const baseStdio = existing;
+      const result2 = {
+        transport: "stdio",
+        command: incoming.command,
+        args: incoming.args ?? baseStdio.args,
+        env: this.mergeStringRecord(baseStdio.env, incoming.env),
+        cwd: incoming.cwd ?? baseStdio.cwd,
+        enabled: incoming.enabled ?? existing.enabled,
+        startupTimeoutSec: incoming.startupTimeoutSec ?? existing.startupTimeoutSec,
+        toolTimeoutSec: incoming.toolTimeoutSec ?? existing.toolTimeoutSec,
+        enabledTools: incoming.enabledTools ?? existing.enabledTools,
+        disabledTools: incoming.disabledTools ?? existing.disabledTools
+      };
+      return result2;
+    }
+    const baseHttp = existing;
+    const hasIncomingAuth = incoming.bearerToken !== void 0 || incoming.bearerTokenEnvVar !== void 0;
+    const bearerToken = hasIncomingAuth ? incoming.bearerToken : baseHttp.bearerToken;
+    const bearerTokenEnvVar = hasIncomingAuth ? incoming.bearerTokenEnvVar : baseHttp.bearerTokenEnvVar;
+    const result = {
+      transport: "http",
+      url: incoming.url,
+      bearerToken,
+      bearerTokenEnvVar,
+      httpHeaders: this.mergeStringRecord(baseHttp.httpHeaders, incoming.httpHeaders),
+      envHttpHeaders: this.mergeStringRecord(baseHttp.envHttpHeaders, incoming.envHttpHeaders),
+      enabled: incoming.enabled ?? existing.enabled,
+      startupTimeoutSec: incoming.startupTimeoutSec ?? existing.startupTimeoutSec,
+      toolTimeoutSec: incoming.toolTimeoutSec ?? existing.toolTimeoutSec,
+      enabledTools: incoming.enabledTools ?? existing.enabledTools,
+      disabledTools: incoming.disabledTools ?? existing.disabledTools
+    };
+    return result;
+  }
+  mergeStringRecord(base, override) {
+    if (override !== void 0) {
+      if (Object.keys(override).length === 0) return {};
+      return { ...base ?? {}, ...override };
+    }
+    if (base) return { ...base };
+    return void 0;
+  }
   // Codex JSONL items use `type` for the item discriminator, but some
   // earlier fixtures (and defensive parsing) might still surface `item_type`.
   // This helper returns whichever is present.
@@ -345,12 +444,20 @@ var CodexCliLanguageModel = class {
     if (settings.webSearch) {
       args.push("-c", "tools.web_search=true");
     }
+    this.applyMcpSettings(args, settings);
     if (settings.color) {
       args.push("--color", settings.color);
     }
     if (this.modelId) {
       args.push("-m", this.modelId);
     }
+    if (settings.addDirs?.length) {
+      for (const dir of settings.addDirs) {
+        if (typeof dir === "string" && dir.trim().length > 0) {
+          args.push("--add-dir", dir);
+        }
+      }
+    }
     if (settings.configOverrides) {
       for (const [key, value] of Object.entries(settings.configOverrides)) {
         this.addConfigOverride(args, key, value);
@@ -379,16 +486,73 @@ var CodexCliLanguageModel = class {
       RUST_LOG: process.env.RUST_LOG || "error"
     };
     let lastMessagePath = settings.outputLastMessageFile;
+    let lastMessageIsTemp = false;
     if (!lastMessagePath) {
       const dir = fs.mkdtempSync(path.join(os.tmpdir(), "codex-cli-"));
       lastMessagePath = path.join(dir, "last-message.txt");
+      lastMessageIsTemp = true;
     }
     args.push("--output-last-message", lastMessagePath);
-    return { cmd: base.cmd, args, env, cwd: settings.cwd, lastMessagePath, schemaPath };
+    return {
+      cmd: base.cmd,
+      args,
+      env,
+      cwd: settings.cwd,
+      lastMessagePath,
+      lastMessageIsTemp,
+      schemaPath
+    };
+  }
+  applyMcpSettings(args, settings) {
+    if (settings.rmcpClient) {
+      this.addConfigOverride(args, "features.rmcp_client", true);
+    }
+    if (!settings.mcpServers) return;
+    for (const [rawName, server] of Object.entries(settings.mcpServers)) {
+      const name = rawName.trim();
+      if (!name) continue;
+      const prefix = `mcp_servers.${name}`;
+      if (server.enabled !== void 0) {
+        this.addConfigOverride(args, `${prefix}.enabled`, server.enabled);
+      }
+      if (server.startupTimeoutSec !== void 0) {
+        this.addConfigOverride(args, `${prefix}.startup_timeout_sec`, server.startupTimeoutSec);
+      }
+      if (server.toolTimeoutSec !== void 0) {
+        this.addConfigOverride(args, `${prefix}.tool_timeout_sec`, server.toolTimeoutSec);
+      }
+      if (server.enabledTools !== void 0) {
+        this.addConfigOverride(args, `${prefix}.enabled_tools`, server.enabledTools);
+      }
+      if (server.disabledTools !== void 0) {
+        this.addConfigOverride(args, `${prefix}.disabled_tools`, server.disabledTools);
+      }
+      if (server.transport === "stdio") {
+        this.addConfigOverride(args, `${prefix}.command`, server.command);
+        if (server.args !== void 0) this.addConfigOverride(args, `${prefix}.args`, server.args);
+        if (server.env !== void 0) this.addConfigOverride(args, `${prefix}.env`, server.env);
+        if (server.cwd) this.addConfigOverride(args, `${prefix}.cwd`, server.cwd);
+      } else {
+        this.addConfigOverride(args, `${prefix}.url`, server.url);
+        if (server.bearerToken !== void 0)
+          this.addConfigOverride(args, `${prefix}.bearer_token`, server.bearerToken);
+        if (server.bearerTokenEnvVar)
+          this.addConfigOverride(args, `${prefix}.bearer_token_env_var`, server.bearerTokenEnvVar);
+        if (server.httpHeaders !== void 0)
+          this.addConfigOverride(args, `${prefix}.http_headers`, server.httpHeaders);
+        if (server.envHttpHeaders !== void 0)
+          this.addConfigOverride(args, `${prefix}.env_http_headers`, server.envHttpHeaders);
+      }
+    }
   }
   addConfigOverride(args, key, value) {
     if (this.isPlainObject(value)) {
-      for (const [childKey, childValue] of Object.entries(value)) {
+      const entries = Object.entries(value);
+      if (entries.length === 0) {
+        args.push("-c", `${key}={}`);
+        return;
+      }
+      for (const [childKey, childValue] of entries) {
         this.addConfigOverride(
           args,
           `${key}.${childKey}`,
@@ -682,7 +846,7 @@ var CodexCliLanguageModel = class {
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
     const responseFormat = options.responseFormat?.type === "json" ? { type: "json", schema: options.responseFormat.schema } : void 0;
-    const { cmd, args, env, cwd, lastMessagePath, schemaPath } = this.buildArgs(
+    const { cmd, args, env, cwd, lastMessagePath, lastMessageIsTemp, schemaPath } = this.buildArgs(
       promptText,
       responseFormat,
       effectiveSettings
@@ -802,9 +966,11 @@ var CodexCliLanguageModel = class {
         }
       } catch {
       }
-      try {
-        fs.rmSync(lastMessagePath, { force: true });
-      } catch {
+      if (lastMessageIsTemp) {
+        try {
+          fs.rmSync(lastMessagePath, { force: true });
+        } catch {
+        }
       }
     }
     const content = [{ type: "text", text }];
@@ -838,7 +1004,7 @@ var CodexCliLanguageModel = class {
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
     const responseFormat = options.responseFormat?.type === "json" ? { type: "json", schema: options.responseFormat.schema } : void 0;
-    const { cmd, args, env, cwd, lastMessagePath, schemaPath } = this.buildArgs(
+    const { cmd, args, env, cwd, lastMessagePath, lastMessageIsTemp, schemaPath } = this.buildArgs(
       promptText,
       responseFormat,
       effectiveSettings
@@ -969,9 +1135,11 @@ var CodexCliLanguageModel = class {
               if (fileText) finalText = fileText.trim();
             } catch {
             }
-            try {
-              fs.rmSync(lastMessagePath, { force: true });
-            } catch {
+            if (lastMessageIsTemp) {
+              try {
+                fs.rmSync(lastMessagePath, { force: true });
+              } catch {
+              }
             }
           }
           if (finalText) {

package/dist/index.d.cts

@@ -37,7 +37,7 @@ interface Logger {
 }
 type ApprovalMode = 'untrusted' | 'on-failure' | 'on-request' | 'never';
 type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
-type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 /**
  * Reasoning summary detail level.
  * Note: The API error messages claim 'concise' and 'none' are valid, but they are
@@ -46,9 +46,60 @@ type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
 type ReasoningSummary = 'auto' | 'detailed';
 type ReasoningSummaryFormat = 'none' | 'experimental';
 type ModelVerbosity = 'low' | 'medium' | 'high';
+interface McpServerBase {
+    /**
+     * Enable/disable this MCP server without removing its definition.
+     * Maps to: `mcp_servers.<name>.enabled`
+     */
+    enabled?: boolean;
+    /**
+     * Time allowed for the MCP server to start (in seconds).
+     * Maps to: `mcp_servers.<name>.startup_timeout_sec`
+     */
+    startupTimeoutSec?: number;
+    /**
+     * Max time a single MCP tool call may run (in seconds).
+     * Maps to: `mcp_servers.<name>.tool_timeout_sec`
+     */
+    toolTimeoutSec?: number;
+    /**
+     * Explicit allow/deny lists for tools exposed by the server.
+     * Maps to: `mcp_servers.<name>.enabled_tools` / `disabled_tools`
+     */
+    enabledTools?: string[];
+    disabledTools?: string[];
+}
+interface McpServerStdio extends McpServerBase {
+    /** Execute an MCP server over stdio */
+    transport: 'stdio';
+    /** Command to start the MCP server (e.g., `node`, `python`, or a binary path). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variables passed to the MCP process. */
+    env?: Record<string, string>;
+    /** Optional working directory for the MCP server process. */
+    cwd?: string;
+}
+interface McpServerHttp extends McpServerBase {
+    /** Use an HTTP-based MCP server (RMCP). */
+    transport: 'http';
+    /** Base URL for the MCP server. */
+    url: string;
+    /** Bearer token supplied inline (use env var variant to avoid embedding secrets). */
+    bearerToken?: string;
+    /** Name of env var that holds the bearer token. */
+    bearerTokenEnvVar?: string;
+    /** Static HTTP headers to send with each MCP request. */
+    httpHeaders?: Record<string, string>;
+    /** Names of env vars whose values should be sent as HTTP headers. */
+    envHttpHeaders?: Record<string, string>;
+}
+type McpServerConfig = McpServerStdio | McpServerHttp;
 interface CodexCliSettings {
     codexPath?: string;
     cwd?: string;
+    addDirs?: string[];
     approvalMode?: ApprovalMode;
     sandboxMode?: SandboxMode;
     fullAuto?: boolean;
@@ -64,9 +115,9 @@ interface CodexCliSettings {
      * Controls reasoning effort for reasoning-capable models (o3, o4-mini, the GPT-5.1 family,
      * and legacy GPT-5 slugs). Higher effort produces more thorough reasoning at the cost of latency.
      *
-     * Codex CLI model presets currently expose `low`/`medium`/`high` for `gpt-5.1` and `gpt-5.1-codex`,
-     * while `gpt-5.1-codex-mini` only offers `medium`/`high`. The legacy `gpt-5` slug still allowed
-     * `minimal`, but GPT-5.1 rejects it.
+     * Codex CLI model presets currently expose `low`/`medium`/`high` for `gpt-5.1` and `gpt-5.1-codex`.
+     * `gpt-5.1-codex-max` additionally supports `xhigh`. `gpt-5.1-codex-mini` only offers `medium`/`high`.
+     * The legacy `gpt-5` slug still allowed `minimal`, but GPT-5.1 rejects it.
      *
      * Maps to: `-c model_reasoning_effort=<value>`
      * @see https://platform.openai.com/docs/guides/reasoning
@@ -97,6 +148,16 @@ interface CodexCliSettings {
      * Maps to: `-c model_verbosity=<value>`
      */
     modelVerbosity?: ModelVerbosity;
+    /**
+     * Configure MCP servers (stdio or HTTP/RMCP). Keys are server names.
+     * Each entry maps to the Codex CLI `mcp_servers.<name>` table.
+     */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Enable the RMCP client so HTTP-based MCP servers can be contacted.
+     * Maps to: `-c features.rmcp_client=true`
+     */
+    rmcpClient?: boolean;
     /**
      * Include experimental plan tool that the model can use to update its current plan.
      *
@@ -169,11 +230,25 @@ interface CodexCliProviderOptions {
      * Maps to Codex `model_verbosity`.
      */
     textVerbosity?: ModelVerbosity;
+    /**
+     * Per-call override for extra directories Codex can access.
+     * Maps to repeated `--add-dir` flags.
+     */
+    addDirs?: string[];
     /**
      * Per-call Codex CLI config overrides. These are merged with
      * constructor-level overrides with per-call values taking precedence.
      */
     configOverrides?: Record<string, string | number | boolean | object>;
+    /**
+     * Per-call MCP server definitions. Merged with constructor definitions
+     * (per-call servers and fields take precedence).
+     */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-call override for RMCP client enablement.
+     */
+    rmcpClient?: boolean;
 }
 
 interface CodexCliProvider extends ProviderV2 {
@@ -203,8 +278,12 @@ declare class CodexCliLanguageModel implements LanguageModelV2 {
     private sessionId?;
     constructor(options: CodexLanguageModelOptions);
     private mergeSettings;
+    private mergeMcpServers;
+    private mergeSingleMcpServer;
+    private mergeStringRecord;
     private getItemType;
     private buildArgs;
+    private applyMcpSettings;
     private addConfigOverride;
     /**
      * Serialize a config override value into a CLI-safe string.

package/dist/index.d.ts

@@ -37,7 +37,7 @@ interface Logger {
 }
 type ApprovalMode = 'untrusted' | 'on-failure' | 'on-request' | 'never';
 type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
-type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 /**
  * Reasoning summary detail level.
  * Note: The API error messages claim 'concise' and 'none' are valid, but they are
@@ -46,9 +46,60 @@ type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
 type ReasoningSummary = 'auto' | 'detailed';
 type ReasoningSummaryFormat = 'none' | 'experimental';
 type ModelVerbosity = 'low' | 'medium' | 'high';
+interface McpServerBase {
+    /**
+     * Enable/disable this MCP server without removing its definition.
+     * Maps to: `mcp_servers.<name>.enabled`
+     */
+    enabled?: boolean;
+    /**
+     * Time allowed for the MCP server to start (in seconds).
+     * Maps to: `mcp_servers.<name>.startup_timeout_sec`
+     */
+    startupTimeoutSec?: number;
+    /**
+     * Max time a single MCP tool call may run (in seconds).
+     * Maps to: `mcp_servers.<name>.tool_timeout_sec`
+     */
+    toolTimeoutSec?: number;
+    /**
+     * Explicit allow/deny lists for tools exposed by the server.
+     * Maps to: `mcp_servers.<name>.enabled_tools` / `disabled_tools`
+     */
+    enabledTools?: string[];
+    disabledTools?: string[];
+}
+interface McpServerStdio extends McpServerBase {
+    /** Execute an MCP server over stdio */
+    transport: 'stdio';
+    /** Command to start the MCP server (e.g., `node`, `python`, or a binary path). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variables passed to the MCP process. */
+    env?: Record<string, string>;
+    /** Optional working directory for the MCP server process. */
+    cwd?: string;
+}
+interface McpServerHttp extends McpServerBase {
+    /** Use an HTTP-based MCP server (RMCP). */
+    transport: 'http';
+    /** Base URL for the MCP server. */
+    url: string;
+    /** Bearer token supplied inline (use env var variant to avoid embedding secrets). */
+    bearerToken?: string;
+    /** Name of env var that holds the bearer token. */
+    bearerTokenEnvVar?: string;
+    /** Static HTTP headers to send with each MCP request. */
+    httpHeaders?: Record<string, string>;
+    /** Names of env vars whose values should be sent as HTTP headers. */
+    envHttpHeaders?: Record<string, string>;
+}
+type McpServerConfig = McpServerStdio | McpServerHttp;
 interface CodexCliSettings {
     codexPath?: string;
     cwd?: string;
+    addDirs?: string[];
     approvalMode?: ApprovalMode;
     sandboxMode?: SandboxMode;
     fullAuto?: boolean;
@@ -64,9 +115,9 @@ interface CodexCliSettings {
      * Controls reasoning effort for reasoning-capable models (o3, o4-mini, the GPT-5.1 family,
      * and legacy GPT-5 slugs). Higher effort produces more thorough reasoning at the cost of latency.
      *
-     * Codex CLI model presets currently expose `low`/`medium`/`high` for `gpt-5.1` and `gpt-5.1-codex`,
-     * while `gpt-5.1-codex-mini` only offers `medium`/`high`. The legacy `gpt-5` slug still allowed
-     * `minimal`, but GPT-5.1 rejects it.
+     * Codex CLI model presets currently expose `low`/`medium`/`high` for `gpt-5.1` and `gpt-5.1-codex`.
+     * `gpt-5.1-codex-max` additionally supports `xhigh`. `gpt-5.1-codex-mini` only offers `medium`/`high`.
+     * The legacy `gpt-5` slug still allowed `minimal`, but GPT-5.1 rejects it.
      *
      * Maps to: `-c model_reasoning_effort=<value>`
      * @see https://platform.openai.com/docs/guides/reasoning
@@ -97,6 +148,16 @@ interface CodexCliSettings {
      * Maps to: `-c model_verbosity=<value>`
      */
     modelVerbosity?: ModelVerbosity;
+    /**
+     * Configure MCP servers (stdio or HTTP/RMCP). Keys are server names.
+     * Each entry maps to the Codex CLI `mcp_servers.<name>` table.
+     */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Enable the RMCP client so HTTP-based MCP servers can be contacted.
+     * Maps to: `-c features.rmcp_client=true`
+     */
+    rmcpClient?: boolean;
     /**
      * Include experimental plan tool that the model can use to update its current plan.
      *
@@ -169,11 +230,25 @@ interface CodexCliProviderOptions {
      * Maps to Codex `model_verbosity`.
      */
     textVerbosity?: ModelVerbosity;
+    /**
+     * Per-call override for extra directories Codex can access.
+     * Maps to repeated `--add-dir` flags.
+     */
+    addDirs?: string[];
     /**
      * Per-call Codex CLI config overrides. These are merged with
      * constructor-level overrides with per-call values taking precedence.
      */
     configOverrides?: Record<string, string | number | boolean | object>;
+    /**
+     * Per-call MCP server definitions. Merged with constructor definitions
+     * (per-call servers and fields take precedence).
+     */
+    mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-call override for RMCP client enablement.
+     */
+    rmcpClient?: boolean;
 }
 
 interface CodexCliProvider extends ProviderV2 {
@@ -203,8 +278,12 @@ declare class CodexCliLanguageModel implements LanguageModelV2 {
     private sessionId?;
     constructor(options: CodexLanguageModelOptions);
     private mergeSettings;
+    private mergeMcpServers;
+    private mergeSingleMcpServer;
+    private mergeStringRecord;
     private getItemType;
     private buildArgs;
+    private applyMcpSettings;
     private addConfigOverride;
     /**
      * Serialize a config override value into a CLI-safe string.

package/dist/index.js

@@ -65,9 +65,37 @@ var loggerFunctionSchema = z.object({
     message: "error must be a function"
   })
 });
+var mcpServerBaseSchema = z.object({
+  enabled: z.boolean().optional(),
+  startupTimeoutSec: z.number().int().positive().optional(),
+  toolTimeoutSec: z.number().int().positive().optional(),
+  enabledTools: z.array(z.string()).optional(),
+  disabledTools: z.array(z.string()).optional()
+});
+var mcpServerStdioSchema = mcpServerBaseSchema.extend({
+  transport: z.literal("stdio"),
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  cwd: z.string().optional()
+});
+var mcpServerHttpSchema = mcpServerBaseSchema.extend({
+  transport: z.literal("http"),
+  url: z.string().min(1),
+  bearerToken: z.string().optional(),
+  bearerTokenEnvVar: z.string().optional(),
+  httpHeaders: z.record(z.string(), z.string()).optional(),
+  envHttpHeaders: z.record(z.string(), z.string()).optional()
+});
+var mcpServerSchema = z.discriminatedUnion("transport", [
+  mcpServerStdioSchema,
+  mcpServerHttpSchema
+]);
+var mcpServersSchema = z.record(z.string(), mcpServerSchema);
 var settingsSchema = z.object({
   codexPath: z.string().optional(),
   cwd: z.string().optional(),
+  addDirs: z.array(z.string().min(1)).optional(),
   approvalMode: z.enum(["untrusted", "on-failure", "on-request", "never"]).optional(),
   sandboxMode: z.enum(["read-only", "workspace-write", "danger-full-access"]).optional(),
   fullAuto: z.boolean().optional(),
@@ -75,11 +103,12 @@ var settingsSchema = z.object({
   skipGitRepoCheck: z.boolean().optional(),
   color: z.enum(["always", "never", "auto"]).optional(),
   allowNpx: z.boolean().optional(),
+  outputLastMessageFile: z.string().optional(),
   env: z.record(z.string(), z.string()).optional(),
   verbose: z.boolean().optional(),
   logger: z.union([z.literal(false), loggerFunctionSchema]).optional(),
   // NEW: Reasoning & Verbosity
-  reasoningEffort: z.enum(["minimal", "low", "medium", "high"]).optional(),
+  reasoningEffort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
   // Note: API rejects 'concise' and 'none' despite error messages claiming they're valid
   reasoningSummary: z.enum(["auto", "detailed"]).optional(),
   reasoningSummaryFormat: z.enum(["none", "experimental"]).optional(),
@@ -89,6 +118,8 @@ var settingsSchema = z.object({
   profile: z.string().optional(),
   oss: z.boolean().optional(),
   webSearch: z.boolean().optional(),
+  mcpServers: mcpServersSchema.optional(),
+  rmcpClient: z.boolean().optional(),
   // NEW: Generic overrides
   configOverrides: z.record(
     z.string(),
@@ -228,10 +259,11 @@ function isAuthenticationError(err) {
 
 // src/codex-cli-language-model.ts
 var codexCliProviderOptionsSchema = z.object({
-  reasoningEffort: z.enum(["minimal", "low", "medium", "high"]).optional(),
+  reasoningEffort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional(),
   reasoningSummary: z.enum(["auto", "detailed"]).optional(),
   reasoningSummaryFormat: z.enum(["none", "experimental"]).optional(),
   textVerbosity: z.enum(["low", "medium", "high"]).optional(),
+  addDirs: z.array(z.string().min(1)).optional(),
   configOverrides: z.record(
     z.string(),
     z.union([
@@ -241,7 +273,9 @@ var codexCliProviderOptionsSchema = z.object({
       z.object({}).passthrough(),
       z.array(z.any())
     ])
-  ).optional()
+  ).optional(),
+  mcpServers: mcpServersSchema.optional(),
+  rmcpClient: z.boolean().optional()
 }).strict();
 function resolveCodexPath(explicitPath, allowNpx) {
   if (explicitPath) return { cmd: "node", args: [explicitPath] };
@@ -283,15 +317,80 @@ var CodexCliLanguageModel = class {
       ...this.settings.configOverrides ?? {},
       ...providerOptions.configOverrides ?? {}
     } : void 0;
+    const mergedAddDirs = providerOptions.addDirs || this.settings.addDirs ? [...this.settings.addDirs ?? [], ...providerOptions.addDirs ?? []] : void 0;
+    const mergedMcpServers = this.mergeMcpServers(
+      this.settings.mcpServers,
+      providerOptions.mcpServers
+    );
     return {
       ...this.settings,
       reasoningEffort: providerOptions.reasoningEffort ?? this.settings.reasoningEffort,
       reasoningSummary: providerOptions.reasoningSummary ?? this.settings.reasoningSummary,
       reasoningSummaryFormat: providerOptions.reasoningSummaryFormat ?? this.settings.reasoningSummaryFormat,
       modelVerbosity: providerOptions.textVerbosity ?? this.settings.modelVerbosity,
-      configOverrides: mergedConfigOverrides
+      configOverrides: mergedConfigOverrides,
+      addDirs: mergedAddDirs,
+      mcpServers: mergedMcpServers,
+      rmcpClient: providerOptions.rmcpClient ?? this.settings.rmcpClient
     };
   }
+  mergeMcpServers(base, override) {
+    if (!base) return override;
+    if (!override) return base;
+    const merged = { ...base };
+    for (const [name, incoming] of Object.entries(override)) {
+      const existing = base[name];
+      merged[name] = this.mergeSingleMcpServer(existing, incoming);
+    }
+    return merged;
+  }
+  mergeSingleMcpServer(existing, incoming) {
+    if (!existing || existing.transport !== incoming.transport) {
+      return { ...incoming };
+    }
+    if (incoming.transport === "stdio") {
+      const baseStdio = existing;
+      const result2 = {
+        transport: "stdio",
+        command: incoming.command,
+        args: incoming.args ?? baseStdio.args,
+        env: this.mergeStringRecord(baseStdio.env, incoming.env),
+        cwd: incoming.cwd ?? baseStdio.cwd,
+        enabled: incoming.enabled ?? existing.enabled,
+        startupTimeoutSec: incoming.startupTimeoutSec ?? existing.startupTimeoutSec,
+        toolTimeoutSec: incoming.toolTimeoutSec ?? existing.toolTimeoutSec,
+        enabledTools: incoming.enabledTools ?? existing.enabledTools,
+        disabledTools: incoming.disabledTools ?? existing.disabledTools
+      };
+      return result2;
+    }
+    const baseHttp = existing;
+    const hasIncomingAuth = incoming.bearerToken !== void 0 || incoming.bearerTokenEnvVar !== void 0;
+    const bearerToken = hasIncomingAuth ? incoming.bearerToken : baseHttp.bearerToken;
+    const bearerTokenEnvVar = hasIncomingAuth ? incoming.bearerTokenEnvVar : baseHttp.bearerTokenEnvVar;
+    const result = {
+      transport: "http",
+      url: incoming.url,
+      bearerToken,
+      bearerTokenEnvVar,
+      httpHeaders: this.mergeStringRecord(baseHttp.httpHeaders, incoming.httpHeaders),
+      envHttpHeaders: this.mergeStringRecord(baseHttp.envHttpHeaders, incoming.envHttpHeaders),
+      enabled: incoming.enabled ?? existing.enabled,
+      startupTimeoutSec: incoming.startupTimeoutSec ?? existing.startupTimeoutSec,
+      toolTimeoutSec: incoming.toolTimeoutSec ?? existing.toolTimeoutSec,
+      enabledTools: incoming.enabledTools ?? existing.enabledTools,
+      disabledTools: incoming.disabledTools ?? existing.disabledTools
+    };
+    return result;
+  }
+  mergeStringRecord(base, override) {
+    if (override !== void 0) {
+      if (Object.keys(override).length === 0) return {};
+      return { ...base ?? {}, ...override };
+    }
+    if (base) return { ...base };
+    return void 0;
+  }
   // Codex JSONL items use `type` for the item discriminator, but some
   // earlier fixtures (and defensive parsing) might still surface `item_type`.
   // This helper returns whichever is present.
@@ -342,12 +441,20 @@ var CodexCliLanguageModel = class {
     if (settings.webSearch) {
       args.push("-c", "tools.web_search=true");
     }
+    this.applyMcpSettings(args, settings);
     if (settings.color) {
       args.push("--color", settings.color);
     }
     if (this.modelId) {
       args.push("-m", this.modelId);
     }
+    if (settings.addDirs?.length) {
+      for (const dir of settings.addDirs) {
+        if (typeof dir === "string" && dir.trim().length > 0) {
+          args.push("--add-dir", dir);
+        }
+      }
+    }
     if (settings.configOverrides) {
       for (const [key, value] of Object.entries(settings.configOverrides)) {
         this.addConfigOverride(args, key, value);
@@ -376,16 +483,73 @@ var CodexCliLanguageModel = class {
       RUST_LOG: process.env.RUST_LOG || "error"
     };
     let lastMessagePath = settings.outputLastMessageFile;
+    let lastMessageIsTemp = false;
     if (!lastMessagePath) {
       const dir = mkdtempSync(join(tmpdir(), "codex-cli-"));
       lastMessagePath = join(dir, "last-message.txt");
+      lastMessageIsTemp = true;
     }
     args.push("--output-last-message", lastMessagePath);
-    return { cmd: base.cmd, args, env, cwd: settings.cwd, lastMessagePath, schemaPath };
+    return {
+      cmd: base.cmd,
+      args,
+      env,
+      cwd: settings.cwd,
+      lastMessagePath,
+      lastMessageIsTemp,
+      schemaPath
+    };
+  }
+  applyMcpSettings(args, settings) {
+    if (settings.rmcpClient) {
+      this.addConfigOverride(args, "features.rmcp_client", true);
+    }
+    if (!settings.mcpServers) return;
+    for (const [rawName, server] of Object.entries(settings.mcpServers)) {
+      const name = rawName.trim();
+      if (!name) continue;
+      const prefix = `mcp_servers.${name}`;
+      if (server.enabled !== void 0) {
+        this.addConfigOverride(args, `${prefix}.enabled`, server.enabled);
+      }
+      if (server.startupTimeoutSec !== void 0) {
+        this.addConfigOverride(args, `${prefix}.startup_timeout_sec`, server.startupTimeoutSec);
+      }
+      if (server.toolTimeoutSec !== void 0) {
+        this.addConfigOverride(args, `${prefix}.tool_timeout_sec`, server.toolTimeoutSec);
+      }
+      if (server.enabledTools !== void 0) {
+        this.addConfigOverride(args, `${prefix}.enabled_tools`, server.enabledTools);
+      }
+      if (server.disabledTools !== void 0) {
+        this.addConfigOverride(args, `${prefix}.disabled_tools`, server.disabledTools);
+      }
+      if (server.transport === "stdio") {
+        this.addConfigOverride(args, `${prefix}.command`, server.command);
+        if (server.args !== void 0) this.addConfigOverride(args, `${prefix}.args`, server.args);
+        if (server.env !== void 0) this.addConfigOverride(args, `${prefix}.env`, server.env);
+        if (server.cwd) this.addConfigOverride(args, `${prefix}.cwd`, server.cwd);
+      } else {
+        this.addConfigOverride(args, `${prefix}.url`, server.url);
+        if (server.bearerToken !== void 0)
+          this.addConfigOverride(args, `${prefix}.bearer_token`, server.bearerToken);
+        if (server.bearerTokenEnvVar)
+          this.addConfigOverride(args, `${prefix}.bearer_token_env_var`, server.bearerTokenEnvVar);
+        if (server.httpHeaders !== void 0)
+          this.addConfigOverride(args, `${prefix}.http_headers`, server.httpHeaders);
+        if (server.envHttpHeaders !== void 0)
+          this.addConfigOverride(args, `${prefix}.env_http_headers`, server.envHttpHeaders);
+      }
+    }
   }
   addConfigOverride(args, key, value) {
     if (this.isPlainObject(value)) {
-      for (const [childKey, childValue] of Object.entries(value)) {
+      const entries = Object.entries(value);
+      if (entries.length === 0) {
+        args.push("-c", `${key}={}`);
+        return;
+      }
+      for (const [childKey, childValue] of entries) {
         this.addConfigOverride(
           args,
           `${key}.${childKey}`,
@@ -679,7 +843,7 @@ var CodexCliLanguageModel = class {
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
     const responseFormat = options.responseFormat?.type === "json" ? { type: "json", schema: options.responseFormat.schema } : void 0;
-    const { cmd, args, env, cwd, lastMessagePath, schemaPath } = this.buildArgs(
+    const { cmd, args, env, cwd, lastMessagePath, lastMessageIsTemp, schemaPath } = this.buildArgs(
       promptText,
       responseFormat,
       effectiveSettings
@@ -799,9 +963,11 @@ var CodexCliLanguageModel = class {
         }
       } catch {
       }
-      try {
-        rmSync(lastMessagePath, { force: true });
-      } catch {
+      if (lastMessageIsTemp) {
+        try {
+          rmSync(lastMessagePath, { force: true });
+        } catch {
+        }
       }
     }
     const content = [{ type: "text", text }];
@@ -835,7 +1001,7 @@ var CodexCliLanguageModel = class {
     });
     const effectiveSettings = this.mergeSettings(providerOptions);
     const responseFormat = options.responseFormat?.type === "json" ? { type: "json", schema: options.responseFormat.schema } : void 0;
-    const { cmd, args, env, cwd, lastMessagePath, schemaPath } = this.buildArgs(
+    const { cmd, args, env, cwd, lastMessagePath, lastMessageIsTemp, schemaPath } = this.buildArgs(
       promptText,
       responseFormat,
       effectiveSettings
@@ -966,9 +1132,11 @@ var CodexCliLanguageModel = class {
               if (fileText) finalText = fileText.trim();
             } catch {
             }
-            try {
-              rmSync(lastMessagePath, { force: true });
-            } catch {
+            if (lastMessageIsTemp) {
+              try {
+                rmSync(lastMessagePath, { force: true });
+              } catch {
+              }
             }
           }
           if (finalText) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sdk-provider-codex-cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "AI SDK v5 provider for OpenAI Codex CLI with native JSON Schema support",
   "keywords": [
     "ai-sdk",
@@ -11,6 +11,7 @@
     "gpt-5",
     "gpt-5.1",
     "gpt-5.1-codex",
+    "gpt-5.1-codex-max",
     "provider"
   ],
   "homepage": "https://github.com/ben-vargas/ai-sdk-provider-codex-cli",
@@ -63,7 +64,7 @@
     "jsonc-parser": "^3.3.1"
   },
   "optionalDependencies": {
-    "@openai/codex": "^0.44.0"
+    "@openai/codex": "^0.60.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.14.0",