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.

When no custom workspace profile is configured, the server creates one profile per detected filesystem root. On Windows that means every existing drive letter — C:\, D:\, and so on — is a workspace root, giving the connected assistant full-machine style access to your entire filesystem. That is intentional and explicit: the server does not quietly restrict access behind the scenes. If you want to limit ChatGPT to a specific folder, repository, or set of directories, you configure workspace profiles yourself before connecting anything remotely.
Full-machine access (all drive roots) is the default when GPT_FS_MCP_WORKSPACE_PROFILES_JSON is empty. If you only want ChatGPT to see one repo or folder, configure a custom profile before running Path B.

​
What a workspace profile contains

Each profile in GPT_FS_MCP_WORKSPACE_PROFILES_JSON is a JSON object with the following fields:
FieldTypeDescription
namestringUnique identifier for the profile. Required.
labelstringHuman-readable display label shown in the dashboard. Falls back to name if omitted.
rootPathstringThe allowed root directory for this profile. Filesystem tools are restricted to this path when GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true. Required.
allowedPolicyModesstring[]Array of policy mode names permitted within this profile. See Policy Modes for values.
backupPolicy"none" | "manual" | "snapshot"Controls how file backups are handled before write operations. Defaults to "manual".
secretDenyGlobsstring[]Glob patterns for files that should never be read, even if they fall within rootPath. Defaults to the built-in secret deny list.

​
How to configure workspace profiles

Set GPT_FS_MCP_WORKSPACE_PROFILES_JSON in your .env to a JSON array of profile objects. The value must be valid JSON and must contain at least one profile. The following example restricts the server to a single repository: 
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[
  {
    "name": "my-project",
    "label": "My Project",
    "rootPath": "C:\\Users\\you\\repos\\my-project",
    "allowedPolicyModes": ["observe", "diagnose", "edit"],
    "backupPolicy": "manual",
    "secretDenyGlobs": ["**/.env", "**/*secret*", "**/*token*"]
  }
]
Windows path separators must be escaped as \\ inside a JSON string. Alternatively, you can use forward slashes (/) — Node.js path.resolve normalizes them on Windows.
To allow multiple profiles (for example, a project repo and a documents folder): 
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[
  {
    "name": "my-project",
    "label": "My Project",
    "rootPath": "C:\\Users\\you\\repos\\my-project",
    "allowedPolicyModes": ["observe", "diagnose", "edit"],
    "backupPolicy": "manual",
    "secretDenyGlobs": ["**/.env", "**/*secret*", "**/*token*", "**/*credential*"]
  },
  {
    "name": "documents",
    "label": "Documents",
    "rootPath": "C:\\Users\\you\\Documents",
    "allowedPolicyModes": ["observe", "diagnose"],
    "backupPolicy": "none",
    "secretDenyGlobs": ["**/.env", "**/*secret*", "**/*token*", "**/*credential*"]
  }
]

​
Enforcement and default CWD

GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES

When true (the default), filesystem tools are restricted to the declared profile root paths. Attempts to read or write outside declared profiles will be rejected.
GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true

GPT_FS_MCP_DEFAULT_CWD

Controls the starting current working directory for relative paths and shell commands. Does not restrict filesystem access by itself — that is the job of GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES.If empty, defaults to ~/Documents/GitHub.
GPT_FS_MCP_DEFAULT_CWD=C:\Users\you\repos

​
Default secret deny globs

When a profile does not specify secretDenyGlobs, the server applies this built-in list, sourced directly from src/config.ts: 
**/.env
**/.env.local
**/.env.development
**/.env.development.local
**/.env.production
**/.env.production.local
**/.env.test
**/.env.test.local
**/*secret*
**/*token*
**/*credential*
These patterns match any file anywhere in the profile’s root path whose name matches. Specifying a custom secretDenyGlobs array in your profile replaces this default list entirely, so include any patterns from the default list that you still want enforced.

​
Shell and process policy

Workspace profiles restrict filesystem tool paths. Shell and process tools have a separate policy: 
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
workspace_guarded checks the command working directory plus explicit path references in the command against declared workspace roots. full allows shell and process tools to reach outside declared workspace paths. disabled disables those tools entirely.
Use full shell and process policies only when you deliberately want shell and process tools to operate outside declared workspace boundaries. Start with workspace_guarded until you need the extra capability.
Start narrow and expand only when you know you need it:
1

Configure one folder or repo

Set GPT_FS_MCP_WORKSPACE_PROFILES_JSON to a single profile pointing at the specific repo or folder you want to work in. Set allowedPolicyModes to ["observe", "diagnose"] for the first test — read-only observation before allowing edits.
2

Add edit capability when needed

Once read access is working cleanly, expand allowedPolicyModes to include "edit" (and "patch" if you want diff-based patching). Keep backupPolicy set to "manual" so backups are taken before destructive writes.
3

Guard shell and process access

Keep GPT_FS_MCP_SHELL_POLICY=workspace_guarded and GPT_FS_MCP_PROCESS_POLICY=workspace_guarded until you have a reason to expand. Add full only when you deliberately want shell commands to reach outside declared workspace roots.
4

Add additional profiles as needed

Add further profiles for other projects or directories rather than expanding a single profile to a broad root path. Keeping profiles narrow makes the dashboard activity easier to read and limits the blast radius if something unexpected happens.
For the full list of allowedPolicyModes values and what each mode permits, see Policy Modes.

Build docs developers (and LLMs) love

Get started for freeTalk to us