Documentation 2026-06-25 20:59 UTC to 2026-06-27 00:02 UTC

1895 },1895 },

1896 {1896 {

1897 key: "mcp_servers.<id>.identity.command",1897 key: "mcp_servers.<id>.identity.command",

1898 type: "string | table",

1899 description:

1900 "Allow an MCP stdio server by exact command string, or use a matcher table to require an exact executable and ordered argument matchers. The string form doesn't inspect arguments, `cwd`, `env`, or `env_vars`.",

1901 },

1902 {

1903 key: "mcp_servers.<id>.identity.command.executable",

1898 type: "string",1904 type: "string",

1899 description:1905 description:

1900 "Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.",1906 "Executable that the stdio server's configured `command` must match exactly.",

1907 },

1908 {

1909 key: "mcp_servers.<id>.identity.command.args",

1910 type: "array<table>",

1911 description:

1912 "Ordered argument matchers for a stdio server. The configured argument list must have the same length, and every position must match. Command matchers don't inspect `cwd`, `env`, or `env_vars`.",

1913 },

1914 {

1915 key: "mcp_servers.<id>.identity.command.args[].match",

1916 type: "exact | prefix | regex",

1917 description: "Match operation for this argument position.",

1918 },

1919 {

1920 key: "mcp_servers.<id>.identity.command.args[].value",

1921 type: "string",

1922 description: "Value used by an `exact` or `prefix` argument matcher.",

1923 },

1924 {

1925 key: "mcp_servers.<id>.identity.command.args[].expression",

1926 type: "string",

1927 description:

1928 "Regular expression used by a `regex` argument matcher. The expression must be valid and match the complete argument value.",

1901 },1929 },

1902 {1930 {

1903 key: "mcp_servers.<id>.identity.url",1931 key: "mcp_servers.<id>.identity.url",

1932 type: "string | table",

1933 description:

1934 "Allow an MCP streamable HTTP server by exact URL string, or use an `exact`, `prefix`, or `regex` value matcher table.",

1935 },

1936 {

1937 key: "mcp_servers.<id>.identity.url.match",

1938 type: "exact | prefix | regex",

1939 description: "Match operation for the configured MCP server URL.",

1940 },

1941 {

1942 key: "mcp_servers.<id>.identity.url.value",

1943 type: "string",

1944 description: "Value used by an `exact` or `prefix` URL matcher.",

1945 },

1946 {

1947 key: "mcp_servers.<id>.identity.url.expression",

1904 type: "string",1948 type: "string",

1905 description:1949 description:

1906 "Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.",1950 "Regular expression used by a `regex` URL matcher. The expression must be valid and match the complete URL value.",

1907 },1951 },

1908 {1952 {

1909 key: "plugins",1953 key: "plugins",

1910 type: "table",1954 type: "table",

1911 description:1955 description:

1912 "Plugin-specific MCP server allowlists keyed by plugin identifier.",1956 "Plugin-specific MCP server allowlists keyed by plugin identifier. When this table is present, plugin-bundled servers without a matching plugin and server entry are disabled.",

1957 },

1958 {

1959 key: "plugins.<plugin>.mcp_servers",

1960 type: "table",

1961 description:

1962 "Allowlist for MCP servers bundled with one plugin. Plugin server requirements use the same exact identity and matcher forms as top-level `mcp_servers` requirements.",

1963 },

1964 {

1965 key: "plugins.<plugin>.mcp_servers.<server>.identity",

1966 type: "table",

1967 description:

1968 "Identity rule for one plugin-bundled MCP server. Set either `command` (stdio) or `url` (streamable HTTP).",

1913 },1969 },

1914 {1970 {

1915 key: "plugins.<plugin>.mcp_servers.<server>.identity.command",1971 key: "plugins.<plugin>.mcp_servers.<server>.identity.command",

1972 type: "string | table",

1973 description:

1974 "Allow a plugin's stdio MCP server by exact command string, or use a matcher table to require an exact executable and ordered argument matchers.",

1975 },

1976 {

1977 key: "plugins.<plugin>.mcp_servers.<server>.identity.command.executable",

1916 type: "string",1978 type: "string",

1917 description:1979 description:

1918 "Allow a plugin's stdio MCP server when its configured command matches this value.",1980 "Executable that the plugin-bundled stdio server's configured command must match exactly.",

1981 },

1982 {

1983 key: "plugins.<plugin>.mcp_servers.<server>.identity.command.args",

1984 type: "array<table>",

1985 description:

1986 "Ordered argument matchers for a plugin-bundled stdio server. The configured argument list must have the same length, and every position must match.",

1987 },

1988 {

1989 key: "plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match",

1990 type: "exact | prefix | regex",

1991 description: "Match operation for this argument position.",

1992 },

1993 {

1994 key: "plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value",

1995 type: "string",

1996 description: "Value used by an `exact` or `prefix` argument matcher.",

1997 },

1998 {

1999 key: "plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression",

2000 type: "string",

2001 description:

2002 "Regular expression used by a `regex` argument matcher. The expression must match the complete argument value.",

1919 },2003 },

1920 {2004 {

1921 key: "plugins.<plugin>.mcp_servers.<server>.identity.url",2005 key: "plugins.<plugin>.mcp_servers.<server>.identity.url",

2006 type: "string | table",

2007 description:

2008 "Allow a plugin's streamable HTTP MCP server by exact URL string, or use an `exact`, `prefix`, or `regex` value matcher table.",

2009 },

2010 {

2011 key: "plugins.<plugin>.mcp_servers.<server>.identity.url.match",

2012 type: "exact | prefix | regex",

2013 description: "Match operation for the plugin-bundled MCP server URL.",

2014 },

2015 {

2016 key: "plugins.<plugin>.mcp_servers.<server>.identity.url.value",

2017 type: "string",

2018 description: "Value used by an `exact` or `prefix` URL matcher.",

2019 },

2020 {

2021 key: "plugins.<plugin>.mcp_servers.<server>.identity.url.expression",

1922 type: "string",2022 type: "string",

1923 description:2023 description:

1924 "Allow a plugin's streamable HTTP MCP server when its configured URL matches this value.",2024 "Regular expression used by a `regex` URL matcher. The expression must match the complete URL value.",

2025 },

2026 {

2027 key: "marketplaces",

2028 type: "table",

2029 description:

2030 "Admin requirements for plugin marketplace sources. Rules take effect when `restrict_to_allowed_sources` is `true`.",

2031 },

2032 {

2033 key: "marketplaces.restrict_to_allowed_sources",

2034 type: "boolean",

2035 description:

2036 "When `true`, require user-configured marketplace sources to match `allowed_sources` for marketplace add, plugin install, and configured Git marketplace refresh operations. Codex-managed OpenAI marketplaces remain allowed when their reserved source and name match. This doesn't filter already configured user marketplaces at runtime.",

2037 },

2038 {

2039 key: "marketplaces.allowed_sources",

2040 type: "table",

2041 description:

2042 "Allowed marketplace sources keyed by administrator-chosen rule name. Distinct names accumulate across requirements layers; fields under the same name use normal layer precedence.",

2043 },

2044 {

2045 key: "marketplaces.allowed_sources.<name>",

2046 type: "table",

2047 description:

2048 "One allowed source rule. The final `source` value after requirements merge determines which sibling fields Codex interprets.",

2049 },

2050 {

2051 key: "marketplaces.allowed_sources.<name>.source",

2052 type: "git | host_pattern | local",

2053 description:

2054 "Marketplace source matcher type. Use `git` for one repository, `host_pattern` for Git hosts matched by regular expression, or `local` for one directory.",

2055 },

2056 {

2057 key: "marketplaces.allowed_sources.<name>.url",

2058 type: "string",

2059 description:

2060 'Git repository URL required when `source = "git"`. Codex normalizes the configured and allowed URLs before requiring an exact repository match.',

2061 },

2062 {

2063 key: "marketplaces.allowed_sources.<name>.ref",

2064 type: "string",

2065 description:

2066 "Optional exact Git ref for a `git` rule. When omitted, the rule allows any ref for the matching repository.",

2067 },

2068 {

2069 key: "marketplaces.allowed_sources.<name>.host_pattern",

2070 type: "string",

2071 description:

2072 'Regular expression required when `source = "host_pattern"`. Codex matches it against the lowercase hostname parsed from an HTTPS, SSH, or SCP-style Git source. Use `^` and `$` to require a whole-host match.',

2073 },

2074 {

2075 key: "marketplaces.allowed_sources.<name>.path",

2076 type: "string (absolute path)",

2077 description:

2078 'Local marketplace directory required when `source = "local"`. Codex requires an absolute path and compares paths after normalization.',

1925 },2079 },

1926 {2080 {

1927 key: "apps",2081 key: "apps",

7 7 

8## Admin-enforced requirements (requirements.toml)8## Admin-enforced requirements (requirements.toml)

9 9 

10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, permission profiles, web search mode, managed hooks, and optionally which MCP servers users can enable). When resolving configuration (for example from `config.toml`, [profile files](https://developers.openai.com/codex/config-advanced#profiles), or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.10Requirements constrain security-sensitive settings (approval policy, approvals reviewer, automatic review policy, sandbox mode, permission profiles, web search mode, managed hooks, which MCP servers users can enable, and which user-configured plugin marketplace sources they can add, install from, or refresh). When resolving configuration (for example from `config.toml`, [profile files](https://developers.openai.com/codex/config-advanced#profiles), or CLI config overrides), if a value conflicts with an enforced rule, Codex falls back to a compatible value and notifies the user. If you configure an `mcp_servers` allowlist, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

11 11 

12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.12Requirements can also constrain [feature flags](https://developers.openai.com/codex/config-basic/#feature-flags) via the `[features]` table in `requirements.toml`. Note that features aren't always security-sensitive, but enterprises can pin values if desired. Omitted keys remain unconstrained.

13 13 

459identity = { url = "https://example.com/mcp" }459identity = { url = "https://example.com/mcp" }

460```460```

461 461 

462The string form of `identity.command` matches only the configured `command`. It

463doesn't inspect `args`, `cwd`, `env`, or `env_vars`.

464 

465To constrain a complete stdio invocation, match the executable and each

466positional argument:

467 

468```toml

469[mcp_servers.internal.identity]

470command = { executable = "/usr/local/bin/codex-mcp", args = [

471 { match = "exact", value = "serve" },

472 { match = "prefix", value = "--workspace=" },

473] }

474```

475 

476The executable, argument count, and argument order must match. Argument and URL

477rules support `exact`, `prefix`, and full-value `regex` matching. Structured

478command rules still don't inspect `cwd`, `env`, or `env_vars`. Plugin-bundled

479MCP servers use the same identity shapes under

480`plugins.<plugin>.mcp_servers.<server>`.

481 

462If `mcp_servers` is present but empty, Codex disables all MCP servers.482If `mcp_servers` is present but empty, Codex disables all MCP servers.

463 483 

484### Restrict plugin marketplace sources

485 

486To restrict operations on user-configured marketplace sources, set

487`restrict_to_allowed_sources = true` and define one or more source rules:

488 

489```toml

490[marketplaces]

491restrict_to_allowed_sources = true

492 

493[marketplaces.allowed_sources.company_plugins]

494source = "git"

495url = "https://github.com/example/company-plugins.git"

496ref = "main"

497 

498[marketplaces.allowed_sources.internal_git]

499source = "host_pattern"

500host_pattern = '^git\.example\.com$'

501 

502[marketplaces.allowed_sources.local_plugins]

503source = "local"

504path = "/opt/company/codex-plugins"

505```

506 

507Git rules match the normalized repository URL and, when present, an exact

508`ref`. Host patterns are regular expressions matched against the lowercase Git

509host; use `^` and `$` for a whole-host match. Local rules require an absolute,

510normalized path. See the [`requirements.toml` reference](https://developers.openai.com/codex/config-reference#requirementstoml)

511for the full schema and merge behavior.

512 

513These requirements reject unmatched marketplace add, plugin install, and

514configured Git marketplace refresh operations for user-configured sources.

515Codex-managed OpenAI marketplaces remain available when their source and

516reserved name match. The requirements don't filter already configured user

517marketplaces or their plugins at runtime.

518 

464## Managed defaults (`managed_config.toml`)519## Managed defaults (`managed_config.toml`)

465 520 

466Managed defaults merge on top of a user's local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.521Managed defaults merge on top of a user's local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.