Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/chatgpt-local-agent-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Command policies control whether the shell and process execution tools can reach outside your declared workspace paths, or whether they are disabled entirely. They act as a second gate on top of MCP scopes: even if the mcp:shell or mcp:process scope is granted, the policy can still block or restrict what those tools can do. Both policies default to full, which means no path restriction beyond scopes and policy modes. For a first remote connector, using workspace_guarded is strongly recommended.

​
The Three Policy Values

​
disabled

The tool is completely unavailable. Any attempt to invoke it returns an error immediately, before any command is evaluated. Use disabled when you want to remove shell or process execution from the tool surface entirely — for example, when you are connecting ChatGPT to a read-only workspace and do not want it to run commands under any circumstances. 
GPT_FS_MCP_SHELL_POLICY=disabled
GPT_FS_MCP_PROCESS_POLICY=disabled

​
workspace_guarded

The server checks the command’s working directory and all path-like tokens it can extract from the command string — including quoted paths, absolute paths, relative paths, and bare filenames that look like .env or *secret* — against your declared workspace profiles. Any path reference that falls outside every profile’s rootPath causes the call to be rejected before the command runs. For shell commands that look mutative (for example, commands using Set-Content, Remove-Item, rm, > redirection, or similar operators), the client must also supply an expectedTouchedPaths list. This requirement ensures the server has enough information to check that the mutation stays inside the workspace. 
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
workspace_guarded is not a sandbox. It performs path-based checks on the tokens the server can parse from the command string, but it cannot prevent all side effects. A command that spawns subprocesses, uses environment variables that expand to external paths, or writes to paths through aliases or symlinks may still affect files outside the declared workspace. Treat workspace_guarded as a meaningful signal-level check, not a hard containment boundary.

​
full

Shell and process tools run with no workspace path restriction. The only constraints that apply are the active MCP scopes (e.g. mcp:shell must be granted) and the server-wide policy mode ceiling (GPT_FS_MCP_MAX_POLICY_MODE). Use full when you deliberately want ChatGPT to be able to run commands that reach outside your declared workspace — for example, invoking a global build tool, running a system-level diagnostic, or starting a process that lives elsewhere on the machine. 
GPT_FS_MCP_SHELL_POLICY=full
GPT_FS_MCP_PROCESS_POLICY=full
full is the default for both policies in .env.example. This matches the project’s philosophy of deliberate, supervised access — but for a first remote connector, switching to workspace_guarded gives you a meaningful extra layer of path-level checking without losing shell functionality.

​
Which Tools Each Policy Controls

GPT_FS_MCP_SHELL_POLICY governs the shell tool — single-shot command execution in a controlled shell process.GPT_FS_MCP_PROCESS_POLICY governs start_process — the tool that launches long-running background processes. The stop_process and process_kill tools use scope and policy mode checks but are not subject to the command path policy gate.Both policies are independent and can be set to different values.

​
The Scope Gate Comes First

The command policy is a second gate, not the first. Before the policy is evaluated, the server checks whether the active access token includes the required MCP scope:
  • The shell tool requires the mcp:shell scope.
  • The process tools (start_process, stop_process, process_kill) require the mcp:process scope.
If the scope is not present in the token, the tool call is rejected at the scope check before the policy is ever consulted. Both gates must pass for a command to execute. See Security — Scopes for the full scope list, and Security — Policy Modes for how the policy mode ceiling interacts with individual tool calls.
For any setup where you want shell and process tools available but want path-level checking as a guard rail, use workspace_guarded for both: 
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
Pair this with explicit workspace profiles so the guard has defined boundaries to check against: 
GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[
  {
    "name": "my-project",
    "label": "My Project",
    "rootPath": "C:\\Users\\you\\projects\\my-project",
    "allowedPolicyModes": ["read", "write", "patch"],
    "backupPolicy": "manual",
    "secretDenyGlobs": ["**/.env", "**/.env.*", "**/*secret*", "**/*token*"]
  }
]
With this setup, a shell call that references a path outside C:\Users\you\projects\my-project — whether in the working directory argument or anywhere in the command string — will be rejected before the command is executed.

​
When to Use full

Use full command policies when you have a specific, intentional reason to let shell or process tools reach outside workspace paths. Common examples include:
  • Running a globally installed tool (npm, cargo, python, dotnet) that lives outside your project folder.
  • Invoking a system diagnostic command (netstat, tasklist, Get-Process) that has no meaningful path reference.
  • Starting a process whose executable is in a system directory like C:\Windows\System32.
  • Automating a build pipeline where the build tool writes to paths across multiple drive locations.
In all these cases, you are making a deliberate choice to trust ChatGPT with unrestricted command execution. Monitor the operation journal and keep the scope list as narrow as possible to compensate.

​
Disabling Shell Without Disabling Process (and Vice Versa)

The two policies are fully independent. You can disable the interactive shell while still allowing process management, or vice versa: 
# Allow process management but no interactive shell
GPT_FS_MCP_SHELL_POLICY=disabled
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded

# Allow interactive shell but block long-running process starts
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=disabled
This is useful when you want ChatGPT to be able to check running processes or tail logs via process tools but do not want it to open an interactive shell session.

​
Policy Interaction Summary

ScenarioGPT_FS_MCP_SHELL_POLICYGPT_FS_MCP_PROCESS_POLICY
Read-only workspace, no executiondisableddisabled
Safer first remote connectorworkspace_guardedworkspace_guarded
Full local development (deliberate)fullfull
Allow diagnostics, no interactive shelldisabledworkspace_guarded
Interactive shell only, no background processesworkspace_guardeddisabled
Start with workspace_guarded for both policies when setting up a new remote connector. You can always relax to full for specific sessions once you understand what commands ChatGPT will realistically need to run.

Build docs developers (and LLMs) love

Get started for freeTalk to us