> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MDM configuration reference

> Every mdm.toml field, tfy-local-ai-setup CLI flag, client version requirement, and file path for MDM rollouts to the TrueFoundry AI Gateway, with defaults and accepted values.

This page lists every option for an [MDM rollout](https://www.truefoundry.com/docs/ai-gateway/mdm-setup.md). For guidance on when to use them, see the overview and the [Claude](https://www.truefoundry.com/docs/ai-gateway/mdm/claude.md) and [Codex](https://www.truefoundry.com/docs/ai-gateway/mdm/codex.md) pages.

## File format

Pass the file to the binary with `--config=/absolute/path/mdm.toml`.

* The format follows the file extension: `.json` is read as JSON, `.yaml` and `.yml` are rejected, and anything else is read as TOML.
* Unknown keys fail validation, except inside `agents.claude-code.managed_settings`, which follows Claude Code's own schema.
* Explicit CLI flags override the matching file values.
* Never put tokens, refresh tokens, or client secrets in the file.

This file is separate from personal setup's `~/.tf/config.toml` and from the `agents-policy.json` file that the binary generates.

## Fields

> [accordion] Connection, agent selection, and sign-in
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `url` | String; required | HTTPS TrueFoundry control-plane URL |
> | `tenant` | String; required | Your tenant name |
> | `gateway` | String; defaults to `url` | Gateway base URL, including any path such as `/api/llm`. Set it when it differs from `url` |
> | `tools` | String array | [Agent IDs](https://www.truefoundry.com/docs/ai-gateway/mdm-setup.md#supported-agents) to configure. See the note below |
> | `auth.mode` | String; `"api-key"` | `"api-key"` for per-employee device login, or `"oidc"` |
> | `auth.login` | Optional string | `"manual"` defers sign-in to the employee's `login --mdm` command. Requires `api-key` mode |
> | `auth.pat_team` | Optional string | Owning team for each employee's PAT in manual mode. The employee's `--pat-team` overrides it |
> | `auth.oidc.issuer` | String; required for OIDC | Exact HTTPS OIDC issuer |
> | `auth.oidc.client_id` | String; required for OIDC | Public client ID. No client secret |
> | `agents.<id>.auth` | String; inherits `auth.mode` | `"api-key"` or `"oidc"`. Claude Code, Codex, and Claude Desktop can differ; all additional agents must use the same mode |
>
> **How `tools` works:**
>
> * **Explicit list:** configures exactly those agents. Claude Code, Codex, Claude Desktop, and agents with managed settings (OpenCode, Qwen Code, Gemini CLI's managed file, and Grok Build on macOS and Linux) are configured before installation. Agents configured through user settings are configured on the first run after installation.
> * **`[]`:** configures no agents. Use it for a Cursor monitoring-only rollout.
> * **Omitted:** detects Claude Code, Codex, and Claude Desktop if installed. Other agents must be listed explicitly. A `[monitoring.cursor]` table turns detection off, so list agents explicitly when you use it.

> [accordion] Models
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `defaults.models` | String array | Shared gateway model IDs for additional agents with a model list. Required unless each agent sets its own |
> | `defaults.default_model` | String; first model | Must be in the effective model list |
> | `agents.<id>.models`, `agents.<id>.default_model` | Array, string | Override the shared models for OpenCode, Qwen Code, Grok Build, Pi, Gemini CLI, GitHub Copilot CLI, Goose, or VS Code. The list must not be empty |
> | `agents.claude-code.opus_model`, `sonnet_model`, `haiku_model` | Strings | Gateway tier IDs. Defaults: `claude-code/claude-opus`, `claude-code/claude-sonnet`, `claude-code/claude-haiku` |
> | `agents.claude-desktop.opus_model`, `sonnet_model`, `haiku_model` | Strings; inherit Claude Code's | Desktop tier IDs |
> | `agents.codex.model` | Optional string | Default model. Use a Virtual Model with a bare OpenAI slug. Omitted: no default is set |
> | `agents.codex.auth_mode` | String; `"api-key"` | `"chatgpt-subscription"` sends the TrueFoundry credential in `x-tfy-api-key` and turns on ChatGPT sign-in. Requires `api-key` auth |

> [accordion] MCP servers and Skills
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `mcp.servers` | String array; optional | Gateway registry names, matching `^[A-Za-z0-9_-]+$`. Each becomes `<gateway>/<tenant>/mcp/<name>/server` |
> | `mcp.discovery` | Optional string | `"all-accessible"` deploys every usable server the employee can access. Needs an existing sign-in. Cannot be combined with a nonempty `servers`, `--mcp-server`, or `--no-mcp` |
> | `skills.names` | String array; optional | `[repo/]name[:version]` references. Pin a version or follow the latest |
> | `skills.discovery` | Optional string | `"all-accessible"` deploys every published Skill the employee can access, at its latest version. Cannot be combined with a nonempty `names`, `--skill`, or `--no-skills` |
> | `agents.<id>.mcp_servers`, `agents.<id>.skills` | String arrays | Replace the shared or discovered selection for that agent. Omitted: inherit. `[]`: deploy nothing |
>
> `[[mcp.custom]]` is not applied in MDM rollouts. Register custom servers in the gateway and use their registry names.

> [accordion] Claude Code policy and gateway overrides
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `agents.claude-code.managed_settings` | Table; optional | Claude Code's managed-settings schema. Replaces the built-in baseline. Only Claude Code supports an inline table |
> | `agents.claude-code.gateway` | Optional HTTPS URL | Gateway for Claude Code only |
> | `agents.codex.gateway` | Optional HTTPS URL | Gateway for Codex only |
> | `agents.claude-desktop.gateway` | Optional HTTPS URL | Gateway for Claude Desktop only |
>
> For the Claude Code policy, see [Set the Claude Code policy](https://www.truefoundry.com/docs/ai-gateway/mdm/claude.md#set-the-claude-code-policy). For a Codex template, use the `--codex-settings-file` flag. On Windows it applies only to `config.toml`, not `requirements.toml`.

> [accordion] Claude Desktop
>
> All fields are under `agents.claude-desktop`.
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `tool_search_enabled` | Optional boolean | Turn tool search on or off. Omitted: the app's default |
> | `prefer_1m_context` | Optional boolean | Desktop's global 1M context preference |
> | `context.<tier>.supports_1m` | Optional boolean | Declare 1M support for `opus`, `sonnet`, or `haiku` |
> | `context.<tier>.prefer_1m` | Optional boolean | Prefer 1M for that tier. Requires `supports_1m = true` |
> | `history_import.enabled` | Boolean; `false` | Allow claude.ai history import. The other `history_import` fields apply only when this is `true` |
> | `history_import.encoding` | String; `"json-string"` | macOS preference encoding: `"json-string"` or `"native-dict"`. Windows always uses JSON |
> | `history_import.export_enabled` | Boolean; `true` | Show **Export** |
> | `history_import.banner_behavior` | String; `"detect"` | `"off"`, `"detect"`, or `"show"` |
> | `history_import.automatic_3p` | Boolean; `false` | Beta. Import earlier third-party sessions without asking. Also requires `deploymentOrganizationUuid`, which this tool does not set |
>
> Desktop inference headers use the `--desktop-header` flag; a `headers` key fails validation.

> [accordion] Prompt blocking
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `restrictions.blocked_agents` | String array; optional | Agents whose prompts are blocked: `claude-code`, `codex`, or `cursor`. `[]` removes every block. Omitted: keep the blocks from the last run |
> | `restrictions.message` | Optional string | Message shown when a prompt is blocked. Default: "Your organization has disabled this application. Please use an approved alternative or contact your administrator." |

> [accordion] Cursor monitoring and sign-in failures
>
> | Field | Type and default | Meaning |
> | - | - | - |
> | `monitoring.cursor.enabled` | Boolean; `false` | Install Cursor activity-monitoring hooks. `false` or an omitted table removes hooks this tool installed |
> | `monitoring.cursor.require_login` | Boolean; `false` | Block Cursor agent prompts and tool and MCP calls when no credential is available. Has no effect unless monitoring is enabled |
> | `execution.write_config_on_login_failure` | Boolean; `false` | If device login fails, write managed settings with a cached or placeholder credential and exit with code `1` |
> | `execution.placeholder_token` | String; `"TFY_PLACEHOLDER_LOGIN_REQUIRED"` | Deliberately invalid credential used when no cached one exists. Requests fail until sign-in succeeds |

> [accordion] Additional agent options
>
> Set only the keys an agent supports; others fail validation.
>
> | Agent | Extra keys | Accepted `api` values |
> | - | - | - |
> | OpenCode | `headers`, `context_window`, `max_tokens`, `gateway_only` | |
> | Qwen Code | `headers`, `context_window`, `api` | `chat-completions`, `responses` |
> | Grok Build | `headers`, `context_window`, `max_tokens`, `api` | `chat_completions`, `responses`, `messages` |
> | Pi | `headers`, `context_window`, `max_tokens`, `api` | `openai-completions`, `openai-responses`, `anthropic-messages` |
> | Gemini CLI | `headers`, `provider_account` | |
> | GitHub Copilot CLI | `headers`, `context_window`, `max_tokens`, `api` | `completions`, `responses` |
> | Goose | `headers`, `context_window` | |
> | VS Code | `headers`, `context_window`, `max_tokens`, `api`, `utility_model`, `insiders` | `chat-completions`, `responses`, `messages` |
>
> * `headers` is an array of `"Name: Value"` strings.
> * `context_window` and `max_tokens` are positive token counts that match the model. Where written, the defaults are 128000 and 16384.
> * The default `api` is the first value in each row.
> * OpenCode's `gateway_only = true` hides other providers.
> * Gemini CLI's `provider_account` routes natively through `<gateway>/gemini/<account>/proxy`.
> * VS Code's `utility_model` is `"mainAgent"` (default), `"copilot"`, or `"none"`. `insiders = true` targets VS Code Insiders.

## CLI flags

Keep routine configuration in the TOML file. Add these flags to the binary's command in your script when needed:

| Flag | Purpose |
| - | - |
| `--config` | Path to `mdm.toml`. Cannot be combined with the older `--agents-config` input |
| `--dry-run` | Print changes without writing managed files. Can still sign the employee in, and its output can contain credentials |
| `--log-file`, `--debug` | Append to a log file; add diagnostic output |
| `--settings-file` | Claude Code policy as a JSON file. If the path cannot be read, the built-in baseline is used |
| `--codex-settings-file` | Codex template as a TOML file |
| `--desktop-header='Name: Value'` | Add a Claude Desktop inference header. Repeatable |
| `--force-login-org=<UUID>` | Restrict Claude Desktop sign-in to a Claude organization. Repeatable |
| `--disable-deployment-mode-chooser` | With Desktop OIDC, stop employees from switching to a personal Claude.ai profile |
| `--claude-desktop-allow-local-mcp=false` | Block employees' local (stdio) MCP servers in Claude Desktop |
| `--oidc-scopes`, `--oidc-bearer-token-type` | Claude Desktop OIDC values. Keep the defaults for TrueFoundry |
| `--wsl` | Also configure Claude Code and Codex in the employee's WSL distributions. See [WSL](https://www.truefoundry.com/docs/ai-gateway/mdm/codex.md#windows-subsystem-for-linux) |
| `--block-agent=claude-code,codex,cursor`, `--block-message="..."` | Block new prompts in the listed agents. Overrides `[restrictions]`. Persists across runs |
| `--unblock-agent=cursor` | Remove the block for an agent |
| `--refresh-token-file`, `--access-token-file` | Override the employee's device-login token cache paths |

Prompt blocks stop new submissions, not launching the app, manual edits, or Cursor Tab completions, and native Windows hooks do not cover WSL.

## Client version requirements

| Agent | Feature | Minimum version |
| - | - | - |
| Claude Code | Managed MCP servers (`managedMcpServers`) | 2.1.259 |
| Claude Code | Prompt blocks that fail closed | 2.1.295 |
| Claude Desktop | Managed MCP connectors | 1.2581.0 |
| Claude Desktop | Tool search | 1.21459.0 |
| Claude Desktop | History import | 1.10628.0 |
| Claude Desktop | OIDC sign-in (`external-idp`) | 2.7032.0 |
| Codex on Windows | Enforcement through `requirements.toml` | 0.156.0 |

Older versions ignore the setting, and Codex on Windows falls back to `config.toml`, which employees can override.

## Files written

> [accordion] Managed files (locked, administrator-only)
>
> | Item | macOS | Linux | Windows |
> | - | - | - | - |
> | Organization policy and state | `/Library/Application Support/TrueFoundry/` | `/etc/truefoundry/` | `%ProgramFiles%\TrueFoundry\` |
> | Claude Code | `/Library/Application Support/ClaudeCode/managed-settings.json` | `/etc/claude-code/managed-settings.json` | `C:\Program Files\ClaudeCode\managed-settings.json` |
> | Codex | `/etc/codex/managed_config.toml` | `/etc/codex/managed_config.toml` | `%ProgramData%\OpenAI\Codex\requirements.toml` and `config.toml` |
> | Codex hooks | `/etc/codex/hooks.json` | `/etc/codex/hooks.json` | `%ProgramData%\OpenAI\Codex\hooks.json` |
> | Claude Desktop | `/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist` | Not supported | `HKLM\SOFTWARE\Policies\Claude` |
> | Cursor hooks | `/Library/Application Support/Cursor/hooks.json` | `/etc/cursor/hooks.json` | `%ProgramData%\Cursor\hooks.json` |
>
> The organization policy directory holds `agents-policy.json` (configuration, never credentials), `agents-state.json`, `cursor-monitoring.json`, and, for prompt blocks, `agent-blocking.json` with its `tfy-agent-blocking.sh` or `.ps1` script.

> [accordion] Employee files
>
> | File | Contents |
> | - | - |
> | `~/.tf/refresh-token`, `~/.tf/access-token` | Device-login credentials |
> | `~/.tf/oidc-*` | OIDC credentials |
> | OS credential store, or `~/.tf/personal-mdm-<account-hash>-pat` as an owner-only fallback | Deferred PAT |
> | `~/.tf/mdm-user.json` | Record of user settings this tool applied |
> | `~/.tf/skills/claude-desktop/` | Claude Desktop Skill ZIPs for upload |

With device login, managed agent files contain the employee's credential. When you contact support, share your TOML and log errors, not token files, dry-run output, or generated agent files.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.