grok mcp list printed the project server as enabled. grok inspect --json named the same server and set source.path to the user config. That file did not contain the server. grok mcp doctor refused to start it, and the hint said to re-run with --trust. That flag is not in grok --help, and putting it after doctor is an error.
The file a script will open is the file inspect names. On this binary that file is the wrong one for a project server, before the folder is trusted and after the grant is written.
The three reports before any grant
The binary was Grok Build 1.0.67, build 2fe064390d07, on Linux x86_64, on 13 November 2026. HOME pointed at a new directory, so the user config was a new file, not an existing grok home. No login was run. The commands that follow do not send a prompt. A separate attempt to list workflows asked for a sign-in before it printed a catalog. This note does not use that command as a trust measurement.
The fixture was a new git repository with one commit. The project config defined one stdio server, named probe, whose command was a script that appended a marker and exited 1. The same file held a permission deny for Bash(rm *). An AGENTS.md at the repository root held a marker sentence. A skill file sat at .grok/skills/probe/SKILL.md. A SessionStart hook sat under .grok/hooks/ and named mark.sh beside the JSON. None of those files lived in the new user config.
Before any trusted launch, the user config contained only a marketplace key. It had no MCP server table.
List exited 0. The human line was the server name, the script path, and (project). The JSON row set enabled to true and scope to project. It did not have a trusted field. A wrapper that stops at enabled will treat the server as on.
Doctor exited 1. The human report listed the project config as found, with one server, and the user config as zero servers. The probe row failed one check, folder untrusted, with the detail that a repo-local server is not started for an untrusted folder. The hint was to re-run with --trust to allow repo-local servers. The marker file was still empty. The process was not started. The JSON checks array had that one failed check and no start check. healthy was false and failing_count was 1.
Inspect set projectTrusted to false. Project instructions, hooks, and skills were empty arrays. permissions.loaded was 0 and permissions.sources was empty. permissions.skipped was also empty, so the deny rule was not reported as skipped. It was absent. configSources.layers still named the project file, with role project.
The MCP array was not empty. It held probe. The source type was configToml. The source path was the user config, the file with no MCP server table. Skill and hook objects, empty at this point, are the objects that later name their own project paths. The MCP object does not. There is no scope field on that object. List has the scope. Inspect has a path, and the path is the user file.
That split is the one to keep. Doctor knows the project file and will not start the process. List knows the scope and does not know the trust bit. Inspect knows the name and points at a file that does not define it. Editing the path inspect prints will not change the project server, because the project server is not in that file.
The bundled MCP guide says list marks a project-scoped server with (project), and that a project file replaces a user file of the same name rather than merging fields. This run did not define the same name in both files. The guide does not say that inspect will name the user file as the source of a server that exists only in the project file. That sentence is the measurement.
The flag the hint names
grok --help on this binary does not contain the string trust. The long help mentions an untrusted folder in the description of --add-dir. It does not list a --trust option. grok mcp doctor --help does not list it either. A job that discovers flags from help will not find the grant the hint just printed.
The hint is still a real flag. It has to sit on grok, before the subcommand.
grok mcp doctor --trust exited 2. Stderr began unexpected argument '--trust' found, and the usage line was grok mcp doctor [OPTIONS] [NAME]. The tip said to pass the flag after -- if it was meant as a value. That is not the grant. The marker file stayed empty on that attempt. The folder was still untrusted. A wrapper that appends the hint’s flag to the doctor command will get this usage error and will not write a trust file.
grok --trust mcp doctor is the form that matches the hint. It wrote trusted_folders.toml under the new home and then started the process. The section name was folders."<project>", trusted was true, and decided_at was a unix timestamp. On this host that timestamp converted to 13 November 2026, US Eastern, the minute of the command. The path in the section is the grant. The timestamp is not a second copy of the path.
Three launches wrote three different files, each under its own home, so one grant could not leak into the next.
A launch that did not pass --cwd, from a directory that was not the fixture, recorded that process directory. The fixture was not the trusted path. Doctor, run later from the fixture under that same home, would still be looking at an untrusted fixture. The grant went to the directory the process was sitting in. If a cron starts in a checkout other than the one whose project config you mean to admit, the section it writes is that other checkout.
A launch from an unrelated directory that passed --cwd <project> recorded <project>. It did not record the process directory. --cwd is the folder the grant uses when you pass it. The shell’s directory is the folder it uses when you do not. The two are not the same switch. Passing --cwd on a later inspect does not rewrite a grant that an earlier launch already stored for a different directory. This run used a new home for each of those launches so the files could be compared. It did not retry a second --trust against a home that already held a different section.
A launch from <project>/nested, with no --cwd, recorded <project>. It did not record nested. The subdirectory is inside the repository, and the section name is the git root. The bundled hooks guide says a grant covers subdirectories of the same repository and does not cover a nested git checkout. This run did not add a nested git checkout, so it does not say whether a second .git would be a separate section. It says the section written from a subdirectory of this repository was the root, not the subdirectory. A check that compares the section path to $PWD will fail that launch even though the root was trusted. Compare the section to the git root.
The bundled guide shipped with this binary says to grant trust with /hooks-trust or by launching with --trust, and that the decision is stored in trusted_folders.toml and is the same gate as repo-local MCP and LSP. The public hooks page says the same about launching with --trust. Neither page says the flag is absent from grok --help, and neither says that grok mcp doctor --trust is rejected. The doctor hint names the flag and does not show which word it follows. The help text will not fill that gap. The usage error will, after you have already put the flag in the wrong place.
What the grant changes, and what it leaves
After grok --trust mcp doctor from the repository root, the marker file contained one line, mcp-ran. Doctor’s JSON still exited 1. It had three checks. command found passed. server started passed, with detail 0.0s. handshake failed did not pass. The detail was a broken pipe while sending the initialize request. The probe script exits 1 after the marker write. It is not an MCP server. The exit 1 after the grant is the handshake, not the trust gate. The check that means the gate opened is server started, and the marker line agrees with it. A server that stays up for initialize is a different process from the one this run started. Do not read a handshake failure on a command that exits immediately as evidence that the folder is still untrusted.
Inspect after that grant set projectTrusted to true. permissions.loaded was 1. permissions.sources named the project config and tagged it as config. The deny text was not a field on that object. The count and the source path are what this run can say about the rule. It cannot say the rule string was echoed. Before the grant the same object had a loaded count of 0 and an empty source list, and it did not list the rule under skipped. The rule became visible as a source count, not as a quoted deny line.
Project instructions held the repository AGENTS.md, with scope project. Hooks held one session-start command, target mark.sh, source type project, path the project hooks directory. Skills held probe-skill, source type project, path the skill file. Those three objects name the project tree. They were empty before the grant. The bundled guide’s claim that one grant covers instructions, hooks, and skills together matches these three arrays. They moved on the same launch.
The MCP object did not move. probe was still source type configToml, and the path was still the user config. Trust changed whether doctor spawned the process. It did not change the path inspect prints for that process’s definition.
A user-scoped server was then added with grok mcp add --scope user, name other, command /bin/true, from the repository, under the home that already held the grant. List then showed two rows. other had scope user and command /bin/true. probe had scope project and the probe script. The user config then contained an mcp_servers.other table and still did not contain mcp_servers.probe.
Inspect after that add listed both names. Both source paths were the user config. The project layer was still present under configSources.layers, role project, path the project file. The layer list is the place the project file appears. The MCP source path is not. A reader who trusts the source path and ignores the layer list will edit one file and leave the project server where it was.
A script that opens mcpServers[].source.path and looks for the probe table will open the user file, find other or find nothing, and report that the project server is missing. The server is in the project file. List’s scope is the field that says so. Doctor’s config-sources block is the other place the project path is printed as a path, and it prints the server count next to that path. Before the grant that count was 1 and the process was not started. After the grant the count was still 1 and the process was started. The count is not the start bit. The folder untrusted check is the start bit, until a grant replaces it with server started.
Verify the file that defines the server
Do not edit the path inspect assigns to a project MCP server. Read list for the scope, then open the file that scope implies.
For a row whose scope is project, the definition is in the repository’s .grok/config.toml, or in a .grok/config.toml on the walk from the working directory up to the git root. This fixture had one such file, at the root. Doctor’s config-sources block printed that path with one server both before and after the grant. That path is the one to edit. The user file is the one inspect named, and it is the one a user-scoped add writes.
For a row whose scope is user, the definition is in the user config. After the user add, that file held other and inspect’s source path for other was that file. The same path on the probe row is the false one. Match the name to the file that contains the table, or match list’s scope, before you write. Two rows that share a source path are not two views of one table.
Doctor is the start check. Exit 1 with folder untrusted and an empty marker means the project process was not spawned. The hint’s flag belongs before the subcommand, as grok --trust mcp doctor, from the repository, or with --cwd set to it. grok mcp doctor --trust does not write the grant. A --trust with no --cwd, launched from another directory, writes a grant for that other directory. Confirm the section path in trusted_folders.toml is the repository you meant. A launch from a subdirectory of that repository wrote the git root. Read the section. Do not assume it repeats the shell’s working directory when that directory is below the root.
After the grant, require server started before you treat a later handshake failure as a trust problem. This probe’s handshake failed because the script exited. A server that speaks the protocol should get past that check. This run does not show a completed handshake, and it does not show what doctor prints when the command path is missing. The untrusted refusal happened before any command-found check. A missing binary is a later failure, on a trusted folder, and this fixture’s script was present.
Inspect remains useful for the trust bit and for skills, hooks, and instructions. projectTrusted false, with empty skills and a populated MCP array, is the untrusted picture this binary produced. projectTrusted true, with a project skill path and an MCP source path that still names the user file, is the trusted picture. The trust bit does not correct the MCP path. A dashboard that colors a server green because inspect listed it will go green before doctor is willing to spawn the process, and it will keep pointing operators at the user file after the spawn is allowed.
The bundled hooks guide says a --trust grant covers MCP, LSP, hooks, project instructions, and project skills together. The surfaces this run measured moved together, except the MCP source path, which was already pointing at the user file and stayed there. The process start is what the grant changed for MCP. The path inspect prints is not what it changed. LSP was not configured in the fixture, so this note does not say whether an untrusted language server is omitted from inspect or mis-pathed the way the MCP row was.
Sources
- Grok Build 1.0.67, build
2fe064390d07, on Linux x86_64, 13 November 2026. List, doctor, inspect, and--trustwere the measurements.HOMEwas a new directory for each grant comparison. No login was required for those four commands. - Bundled user guide shipped with that binary, hooks and MCP servers. The hooks page says a project is trusted with
/hooks-trustor--trust, and that the grant is stored intrusted_folders.tomland covers repo-local MCP. - Hooks, read 13 November 2026. Launching with
--trustis the documented grant. The page does not say the flag is omitted fromgrok --help.