First connection¶
Use this checklist the first time you connect truenas-mcp to a real TrueNAS SCALE appliance. The server starts read-only. Keep it read-only until you have checked the tool results against your appliance.
Safety rules¶
- Do not pass
--enable-writes, and unsetTRUENAS_ENABLE_WRITES. - Use a dedicated API key. When your TrueNAS release supports scoped or read-only credentials, use the narrowest scope it offers.
- Prefer a valid TLS certificate. Use
--tls-insecureonly when you accept the risk of a self-signed certificate. - Start with prompts that list tools or call read-only list and report tools.
- Read-only tools still send appliance metadata to the AI client and its logs.
truenas_app_configcan return plaintext secrets from an app's configuration.
Step 1: set the environment¶
Read the API key without echo, so that it stays out of your shell history:
unset TRUENAS_ENABLE_WRITES
export TRUENAS_HOST=truenas.local
read -rs TRUENAS_API_KEY
export TRUENAS_API_KEY
TRUENAS_HOST is a host name or an IP address, not a URL. The server
connects to wss://<host>/api/current.
If the appliance uses a self-signed certificate and you accept that risk:
Step 2: run the server read-only¶
The server reads TRUENAS_HOST and TRUENAS_API_KEY from the environment.
It writes its status to stderr:
Connecting to TrueNAS at truenas.local...
Connected and authenticated.
Starting MCP server on stdio (read-only mode)...
The server then waits for an MCP client on stdin. Stop it with Ctrl+C. An MCP client starts the server itself; the configuration page shows the client entry.
The repository has a guided script. It builds the server, checks that
writes are off and that TRUENAS_HOST is not a URL, and prints the
read-only command and the client configuration. It never prints the API
key, and it contacts the appliance only with --run-server.
scripts/first-contact.sh # check, build and print the runbook
scripts/first-contact.sh --run-server # start the read-only server
The script needs make, go and python3. Do not run it with shell
tracing (bash -x): a trace can show the API key.
Step 3: ask read-only questions¶
Start with tool discovery and read-only checks:
- "List the available TrueNAS tools."
- "Run
truenas_health_reportand summarize the result." - "Run
truenas_apps_update_report; do not update anything." - "List recent TrueNAS jobs with
truenas_jobs_list."
Do not ask the assistant to create, delete, start, stop, restart, upgrade or change anything during the first connection.
Step 4: check the tool list¶
The read-only server registers these tools, among others:
truenas_health_reporttruenas_system_infotruenas_pool_listtruenas_app_listtruenas_apps_update_reporttruenas_jobs_listtruenas_filesystem_stattruenas_rsync_task_list
The read-only server registers exactly 24 tools. No write tool must appear:
no tool that creates, deletes, starts, stops, restarts, updates, configures,
runs or dismisses something. If one appears, the server runs with writes
enabled: stop it and check TRUENAS_ENABLE_WRITES. The
tool reference marks each write tool.
Undo it¶
The read-only server changes nothing on the appliance. To end the first connection, stop the server and remove the API key in the TrueNAS web interface.
When the read-only results look right, read enable write tools before you turn writes on.