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.

Policy modes form a ranked ladder that gates what each individual tool operation is permitted to do. Every tool invocation declares the policy mode it requires, and the server checks that mode against both the global cap (GPT_FS_MCP_MAX_POLICY_MODE) and the per-workspace-profile allowlist before executing. Policy modes are independent of scopes — a session can have the mcp:write scope but be blocked from writing by a restrictive policy mode cap, and vice versa. Both must permit an operation for it to succeed.

​
The Five Policy Modes

The modes come directly from src/policy.ts. They are ordered by rank from safest to most powerful.
ModeRankDescriptionExample tools
observe0Safe read and inspection operations that do not modify anythingread_file, stat, tree, hash, window_list, process_list, port_list, tail_log
diagnose1Diagnostic operations that may query deeper system statesearch, wait_for_port, screen_screenshot, screen_ocr
edit2Non-destructive mutations such as creating new directoriesmkdir
operate3Process and browser operations, shell executionshell, process start/stop/kill, browser navigation, desktop mouse/keyboard
destructive4Permanent or overwriting changeswrite_file, delete, move, copy, rollback_backup, git_commit, apply_patch
A mode at rank N permits all operations at rank ≤ N. Setting GPT_FS_MCP_MAX_POLICY_MODE=edit allows observe and diagnose operations too, but blocks operate and destructive ones.

​
Global Cap: GPT_FS_MCP_MAX_POLICY_MODE

The GPT_FS_MCP_MAX_POLICY_MODE environment variable sets the ceiling for the entire server. Any tool that requires a mode above this rank is disabled — it will return an error regardless of what scopes the token carries. 
# Default — all tools enabled
GPT_FS_MCP_MAX_POLICY_MODE=destructive

# Read-only — only observe-ranked tools permitted
GPT_FS_MCP_MAX_POLICY_MODE=observe

# Diagnostics — observe and diagnose tools permitted
GPT_FS_MCP_MAX_POLICY_MODE=diagnose
The default is destructive, which enables all tools. For any session where you do not need write or execute access, lower this cap before starting the server.

​
Per-Profile Restriction: allowedPolicyModes

Individual workspace profiles can further restrict which modes are allowed for paths under their root. This lets you grant broad access to one folder while keeping another folder read-only, within the same running server instance. A workspace profile that restricts access to read and diagnostic operations only: 
{
  "name": "project-read-only",
  "rootPath": "C:\\Users\\you\\Projects\\sensitive-repo",
  "allowedPolicyModes": ["observe", "diagnose"]
}
With this profile, a tool that requires destructive mode on a path under C:\Users\you\Projects\sensitive-repo will be blocked even if GPT_FS_MCP_MAX_POLICY_MODE=destructive is set globally.
The per-profile allowedPolicyModes can only be equal to or more restrictive than the global GPT_FS_MCP_MAX_POLICY_MODE. Listing destructive in allowedPolicyModes while the global cap is observe still blocks destructive operations — the global cap takes priority.

​
Common Configurations

Disables all write, execute, and destructive tools globally. Only inspection and diagnostic tools work.
GPT_FS_MCP_MAX_POLICY_MODE=observe
Allows all read and inspection tools plus diagnostic queries like search, wait_for_port, screen_screenshot, and screen_ocr. Blocks file writes, shell execution, and process control.
GPT_FS_MCP_MAX_POLICY_MODE=diagnose
Allows mkdir in addition to all observe and diagnose tools. Blocks file writes (write_file), shell execution, process control, and all destructive operations.
GPT_FS_MCP_MAX_POLICY_MODE=edit
All tools available. Use when you need the full surface and are actively supervising the session.
GPT_FS_MCP_MAX_POLICY_MODE=destructive
Global cap permits full access, but a specific workspace profile limits one directory to observation only.
GPT_FS_MCP_MAX_POLICY_MODE=destructive
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[{"name":"secrets","rootPath":"C:\\Vault","allowedPolicyModes":["observe"]}]

​
Policy Modes vs. Scopes

Policy modes and scopes are two independent gates that both must pass for an operation to succeed.
GateControlsSet via
ScopesWhich tool categories are availableDEFAULT_OAUTH_SCOPES at authorization time
Policy modesHow destructive an operation within a category can beGPT_FS_MCP_MAX_POLICY_MODE and per-profile allowedPolicyModes
Example: a token with mcp:write scope and a server configured with GPT_FS_MCP_MAX_POLICY_MODE=edit can call mkdir (rank 2 = edit) but cannot call write_file (rank 4 = destructive). The scope grants category access; the policy mode caps the operation level within that category. For more on scopes, see MCP Scopes.

Build docs developers (and LLMs) love

Get started for freeTalk to us