Grok mcp doctor refuses the --trust flag its hint names

John Burns

error: unexpected argument '--trust' found

Usage: grok mcp doctor [OPTIONS] [NAME]

That is the whole failure. grok mcp doctor refusebin --trust exited 2. The doctor report did not run. The trust file did not gain an entry for that directory. The next grok mcp doctor refusebin, with no flag, still exited 1, and the first check was still folder untrusted. The hint on that check was still re-run with --trust to allow repo-local servers.

The arrow in the text report is the same sentence. On a different disposable project, before any successful grant, the text doctor printed:

freshbin (stdio: /bin/false)
  ✗ folder untrusted (repo-local (project-scoped) server not started for an untrusted folder)
  → re-run with --trust to allow repo-local servers

A job that appends the named flag to grok mcp doctor follows the arrow and does not grant trust. The parser tip under the exit 2 error says to pass --trust as a value with -- --trust. This run did not use that form. The tip is not a second way to grant trust that was measured here.

The report that prints the hint

The binary was Grok 1.0.67, build 2fe064390d07, on Linux x86_64, on 21 November 2026. grok version printed that same version line. Each command used a new home directory, so the operator Grok home was not the file under test. That directory’s modification time was the same before and after. No grok login was run. No prompt was sent to a model.

The project server was added with grok mcp add --scope project, a new directory as the working directory, and /bin/false after --. The add exited 0 and said it had written the project config. The command string in the file was /bin/false. The name in one directory was freshbin. The name in the directory used to prove the refused flag writes nothing was refusebin. A third directory, with a home that held no user-scoped server, used the name onlybin. The three directories were the same shape: one project config, one stdio command, no git remote, no login.

In the project directory, grok mcp list exited 0 and printed the project server with a (project) marker. grok mcp doctor on that name exited 1. The JSON check had passed false, label folder untrusted, and the hint above. The detail was repo-local (project-scoped) server not started for an untrusted folder. There was no command found check and no server started check on that name. The process did not launch /bin/false for the project server while the folder was untrusted.

grok mcp doctor --help on this binary lists --json, --debug, --debug-file, --help, and --leader-socket. It does not list --trust. grok mcp --help does not list it either. grok --help does not list it. grok help mentions trust once, as a reason --add-dir can be refused, not as a flag you can pass to doctor. The hint is ahead of the help text.

The user guide that this binary wrote into the disposable home on first launch is the version-matched page for the gate itself. The hooks page says a project must be trusted before project hooks run, and that you grant trust with /hooks-trust or by launching with --trust. It says the decision is recorded in ~/.grok/trusted_folders.toml, and that the same gate governs repo-local MCP and LSP servers. It also says a --trust grant covers MCP, LSP, hooks, project instructions, and project skills together, including subdirectories of the same repository, and that a nested git checkout is a separate workspace. This run rechecked doctor after a grant. It did not start a session, did not load a hook, and did not prove those other surfaces. The page’s claim about the shared gate is the guide’s, not a second measurement.

The flag the subcommand refuses

The refused form was grok mcp doctor --trust refusebin, from the project directory, with the disposable home. Exit 2. Standard output was empty. Standard error was the unexpected-argument error, the tip about -- --trust, and the usage line for grok mcp doctor. A search of trusted_folders.toml for that project directory returned no line. The following doctor, without the flag, still had one failing server, label folder untrusted, and the same hint.

So the hint’s words are not a command line. “Re-run with --trust” does not mean “add --trust to the doctor arguments.” On this binary those arguments are rejected before doctor reads the config. The trust file is unchanged. The next report repeats the hint. A retry loop that treats exit 2 as a usage error and stops is safer than a loop that treats the hint as a patch and appends the flag forever. Neither loop grants trust.

The MCP page in the same shipped guide tells you to run grok mcp doctor to diagnose configuration and connectivity, and to pass a server name to check one server. It shows --json. It does not show --trust, and it does not say that a project server is withheld until the folder is trusted. The hooks page has the grant. The doctor hint has the flag name. The doctor help has neither. A reader who stays inside grok mcp doctor --help cannot discover the working placement from that text.

The flag that records trust

The form that changed the report was grok --trust mcp doctor freshbin --json. The flag is on grok, before the subcommand. That process exited 1, which is not the trust failure. The project server’s checks were then:

command found     passed    /bin/false
server started    passed    0.0s
handshake failed  failed    Broken pipe (os error 32), when send initialize request

/bin/false is not an MCP server. Once the trust gate let the process start, the initialize request found a closed pipe. Exit 1 here means the command was launched and did not speak the protocol. It does not mean the folder is still untrusted. A job that only checks the exit code cannot tell those two failures apart. The check label can. folder untrusted is the gate. handshake failed is the binary.

After that grant, trusted_folders.toml in the disposable home had a section for the project directory with trusted = true. A later grok mcp doctor freshbin, with no --trust anywhere on the command, no longer printed folder untrusted. The first check was command found. The grant persisted. Doctor did not ask again.

That persistence is the part the hint does not say. The arrow reads like a switch for one doctor run. The guide says the grant is the folder trust store, and that the same grant opens hooks, LSP, project instructions, and project skills. This run did not exercise those surfaces. It did show that a second doctor, in a new process, without the flag, skipped the trust check. If the intent was only to see whether /bin/false can be executed, the working command also recorded a standing trust decision for that directory.

The refused flag does not do that. The accepted flag does. The hint does not say which placement writes the file.

A clean doctor exit from the wrong directory

List and doctor also disagree about whether the project server exists, depending on the working directory.

In the home that contained only the project server, grok mcp list from the project directory exited 0 and printed onlybin: /bin/false (project). grok mcp doctor from that directory exited 1 with folder untrusted. From a second directory that was not the project, grok mcp list exited 0 and printed No MCP servers configured. grok mcp doctor from that second directory exited 0. The JSON report had healthy_count 0, failing_count 0, and an empty server array. Its sources named the user config, ~/.claude.json, and .mcp.json. They did not name the project file.

A job that runs doctor from a checkout root, a home directory, or a runner workspace that is not the directory where grok mcp add --scope project wrote .grok/config.toml will not see that server. On this binary the empty report is a success exit. The project file is still on disk. Doctor in the project directory still refuses to start the command until the folder is trusted. The clean exit elsewhere is not a statement that the project server is healthy. It is a statement that this working directory has no server in the sources doctor opened.

List has the same blind spot, and a second one in the right directory. In the project it exits 0 while doctor exits 1. Elsewhere it exits 0 and says nothing is configured. Neither list exit is the trust gate.

A disabled user-scoped server is a third split, measured in a different disposable home that also held /bin/false and /bin/true as user servers. grok mcp disable on the missing-command server exited 0. The next list still printed that name with (disabled) and exited 0. The next doctor omitted the name. The user-config source count in that doctor report was 2, matching the two servers it still checked, not the three names list printed. Doctor’s exit code does not describe disabled entries. List’s exit code does not describe untrusted project entries. A gate that uses only one of them will accept a tree the other command still fails, or fail to see a tree the other command still lists.

What still starts while the folder is untrusted

Trust is not a switch that stops every MCP command. In the project directory, before the grant, doctor checked a user-scoped /bin/false and a user-scoped /bin/true in the same report that stopped the project server at folder untrusted. Both user-scoped names had command found, server started, and handshake failed. The folder gate did not apply to them. They were launched. They failed the initialize request for the same reason /bin/false failed after the grant: the file is not an MCP server.

A review that treats “the folder is untrusted” as “no MCP process will be spawned” is reading a project-scope rule as a global one. The user config is outside that rule. On this binary, doctor will start those commands and count a handshake failure while the project server is still withheld. If the user config is empty, as in the onlybin home, doctor in the project fails only the trust check, and doctor elsewhere exits 0 with nothing to start.

Verification

Run the checks from the directory that holds the project config, and run them again from a directory that does not. Use a disposable home so the operator trust file is not the one under test. Record the version with grok version before comparing a hint to a help page. This host was 1.0.67. The public changelog’s latest entry on the morning of the run was 1.0.89, dated 17 November 2026. That release was not installed here. A newer binary may print a different hint. Do not treat this note as a statement about 1.0.89.

From the project directory, grok mcp list may exit 0 and mark the server (project). That is not trust and not connectivity. grok mcp doctor on the name should be the gate. While the folder is untrusted, require exit 1, a check label of folder untrusted, and no server started check on that name. If the label is missing and the command was still not launched, stop and read the report. Do not infer the gate from the exit code alone.

Then run grok mcp doctor --trust with the server name. On this binary that exits 2, prints unexpected argument '--trust' found, and leaves trusted_folders.toml without that directory. The next doctor still says folder untrusted. If a later build accepts the flag on the subcommand, this check will fail in the other direction. Keep the expected placement in the job, and do not append the flag because the hint says to.

The placement that granted trust here was grok --trust before mcp doctor. After it, require a command found check, and require the trust file to contain that directory if the job is allowed to record a standing grant. If the job is not allowed to trust the folder, do not use that form. There is no doctor flag on this binary that prints the connectivity checks without writing the grant. This run did not find one.

If the command is /bin/false or another non-server, the post-grant result is exit 1 with handshake failed, including a broken pipe on the initialize request. That is the connectivity failure. A real MCP server should get past server started and should not fail that initialize line. This run did not start a speaking server. It used /bin/false so the trust gate and the protocol failure would be different labels.

From any other directory, doctor can exit 0 with zero servers even when the project file names a server doctor will not start. Point the job at the project directory, or fail the job when the project config path is absent from the doctor sources. An empty success is the wrong cwd, not a healthy project server.

The shipped hooks page is the source for what a successful --trust grant is supposed to cover beyond MCP. Confirm that page in the guide the binary wrote, or in the public changelog’s release, before you treat a doctor grant as MCP-only. This run’s evidence stops at doctor, the trust file, and list.

Sources

  • grok mcp doctor, grok mcp list, grok mcp add --scope project, and grok mcp disable on Grok 1.0.67 (2fe064390d07), Linux x86_64, 21 November 2026. Disposable homes and disposable project directories. No login and no model turn.
  • The user guide that binary wrote on first launch in the disposable home: docs/user-guide/10-hooks.md (folder trust, --trust, trusted_folders.toml) and docs/user-guide/07-mcp-servers.md (project scope, list, doctor).
  • Grok Build changelog, read 21 November 2026, latest listed entry v1.0.89 on 17 November 2026: https://x.ai/changelog/build. That release was not the binary under test.