Read-only by default¶
truenas-mcp has 2 modes. The default mode registers only the read-only tools. The write mode also registers the tools that create, change or delete things on the appliance. The decision and its reasons are in ADR-0004 — Read-only by default.
The rule¶
- The server always registers the 24 read-only tools.
- It registers the 20 write tools only when you start it with
--enable-writesor withTRUENAS_ENABLE_WRITESset to a true value. - A write tool that is not registered does not exist for the client. It is absent from the tool list, and a call to it fails.
So a plain truenas-mcp serve cannot change the appliance, and an AI client
cannot reach a write tool until you restart the server in write mode.
Which values turn writes on¶
TRUENAS_ENABLE_WRITES accepts these spellings, in lower case, upper case or
with a capital first letter:
| Value | Effect |
|---|---|
1, t, true, y, yes, on |
Writes on |
0, f, false, n, no, off |
Writes off |
| Empty, or any other value | The default: writes off |
TRUENAS_TLS_INSECURE reads its value by the same rule.
What the mode does not do¶
Read-only mode limits scope. It is not a security boundary against a hostile client on a server that runs in write mode. Inside write mode, each tool carries MCP annotations that tell the client how careful to be. The enable write tools guide explains them.
The roles of the API key's user are a second limit. TrueNAS refuses a call that the roles do not allow, in either mode.
Why it fails closed¶
The appliance holds live data, and some write tools destroy it:
truenas_dataset_delete, truenas_snapshot_delete, truenas_app_delete,
truenas_app_compose_update, the snapshot retention that
truenas_snapshot_task_create and truenas_snapshot_task_run start, and the
retention of the task that truenas_replication_task_create makes. On a
first connection you have not checked any tool result yet. A server that
registers every tool and relies on the client to ask first fails open: the
server cannot enforce a client policy.
See the tool reference for the mode of every tool.