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.

ChatGPT Local Agent MCP is designed to be capable, not sandboxed. Its purpose is to give ChatGPT meaningful access to local files, shell, processes, browser sessions, and the desktop — and it takes that purpose seriously. Understanding exactly where the boundaries sit is critical before connecting a public endpoint to your local machine. The controls this system provides are real and meaningful, but they are not an OS-level sandbox, and an authorized session still runs with the Windows account permissions of the server process.

​
Boundaries This System DOES Provide

OAuth identity control

Only GitHub accounts listed in ALLOWED_GITHUB_LOGINS can complete the authorization flow and receive an access token. Every connection goes through GitHub identity verification first.

MCP scopes

Ten scopes gate access to tool categories. A token without mcp:shell cannot invoke any shell tool, regardless of what ChatGPT requests. Scopes are locked at token issuance and enforced on every call.

Policy mode cap

GPT_FS_MCP_MAX_POLICY_MODE globally caps how destructive any operation can be. Setting it to observe disables all writes, shell execution, and process control server-wide.

Workspace profiles

Profiles restrict filesystem tool access to declared root paths and can independently limit allowed policy modes per directory. Paths outside declared profiles are blocked when GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true.

Command policies

GPT_FS_MCP_SHELL_POLICY and GPT_FS_MCP_PROCESS_POLICY can be set to workspace_guarded to restrict shell and process tools to commands whose working directory and path references stay within declared workspace profiles. disabled turns the category off entirely.

Secret deny globs and journal redaction

Each workspace profile carries a secretDenyGlobs list (defaulting to patterns like **/.env, **/.env.*, **/*secret*, **/*token*, **/*credential*) that blocks filesystem tools from reading matched paths. Journals separately redact tool argument values whose key names match known secret fields (password, secret, token, client_secret, accessToken, and any key containing “secret” or “token”).

​
Boundaries This System Does NOT Provide

Treat an authorized ChatGPT session like a human assistant sitting at your keyboard. The controls above limit reach, but they are not a process-level sandbox.
The MCP server runs as a normal Windows process under your user account. It has no additional OS-level containment. If your Windows account can read a file, launch a program, or interact with a UI element, the exposed tools — when granted the appropriate scopes and within policy limits — can potentially reach the same surface. Running the server under a dedicated low-privilege Windows account reduces this exposure significantly.
Browser automation uses Playwright and can attach via Chrome DevTools Protocol (CDP) to existing browser profiles. A session with mcp:browser scope can interact with pages where you are already logged in, read cookies, inspect network traffic for active sessions, and submit forms. Use a dedicated browser profile that is not connected to sensitive accounts when testing.
The mcp:desktop scope enables tools that send real mouse movements, clicks, and keystrokes to the desktop. These actions are indistinguishable from physical input at the OS level. They can interact with any visible window, including applications outside any declared workspace.
mcp:shell and mcp:process tools inherit the full permissions of the Windows account running the MCP server. workspace_guarded policy checks the working directory and explicit path references in commands, but it does not prevent a shell command from reading files, making network requests, or spawning subprocesses that reach outside the workspace. It is a guidance layer, not a true sandbox.
An authorized session with broad scopes can read any file accessible to the server process, inspect browser session state, view the desktop, or run shell commands — even with secret deny globs in place. The globs block common patterns like .env files, but they do not prevent all paths to sensitive data. Do not connect ChatGPT to a machine containing secrets you are not willing to expose.

​
Known ChatGPT Platform Limits

The MCP server controls what tools exist and what tokens can call them. ChatGPT/OpenAI has a separate safety layer on its side that operates independently of this server.
Some actions may be asked for confirmation or blocked entirely on the ChatGPT side: changing or deleting things, sending or posting content, interacting with logged-in websites, exposing sensitive data, following suspicious page instructions, or anything that looks like policy evasion or unsafe automation. Making the MCP server more powerful does not bypass these ChatGPT-side safety blocks. If ChatGPT refuses a tool call, check the platform safety layer first before looking at server configuration.
Apply these practices before connecting a public ChatGPT connector:
1

Use narrow scopes for each session

Set DEFAULT_OAUTH_SCOPES to only the categories a session actually needs. For a code review session, mcp:read mcp:git is sufficient. Add mcp:shell or mcp:browser only when the task requires it. See MCP Scopes.
2

Use workspace_guarded shell and process policies

Unless you deliberately need shell and process tools to reach anywhere on the machine, set:
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
This restricts commands to paths within declared workspace profiles. See Command Policies.
3

Configure explicit workspace profiles

Define GPT_FS_MCP_WORKSPACE_PROFILES_JSON to limit filesystem tool access to the project folder or folders you intend to expose. Without custom profiles, the server defaults to all detected drive roots (C:\, D:\, etc.) — full machine access.
4

Use a dedicated browser profile

Do not connect browser automation to a profile that holds active sessions for email, banking, work accounts, or any service you are not comfortable exposing. Create a separate browser profile specifically for MCP sessions.
5

Do not run the server under a highly privileged account

The server inherits the permissions of the Windows account that starts it. Running under a standard user account rather than an administrator account limits the blast radius of a compromised or misbehaving session.
6

Watch the local dashboard during testing

The local dashboard at http://127.0.0.1:8789/dashboard shows active sessions, recent tool calls, and journal entries. Keep it visible while testing a new session configuration. If something looks wrong, stop the server — active tokens expire within one hour, and stopping the server clears all in-memory token state immediately.
Treat access like a human assistant sitting at your keyboard. The OAuth allowlist, scopes, policy modes, and workspace profiles are meaningful controls — but they are boundaries within a capable local agent, not a sandboxed execution environment. Configure deliberately, start narrow, and expand access only when a task specifically requires it.
For scope configuration, see MCP Scopes. For shell and process command policy details, see Command Policies.

Build docs developers (and LLMs) love

Get started for freeTalk to us