Environment Variable Reference for ChatGPT Local Agent MCP

All configuration for ChatGPT Local Agent MCP lives in a private .env file that you create inside your install folder by copying .env.example. The install folder is %LOCALAPPDATA%\chatgpt-local-agent-mcp by default — never commit this file or share it, as it contains OAuth secrets and controls what tools are exposed to ChatGPT. The sections below document every supported variable, its type, its default value, and what it does.

Treat .env as a security-critical file. It contains OAuth secrets, controls access to your filesystem and shell, and determines whether the server requires authentication. Back it up securely but never check it into source control.

Server Binding

These variables control the network address the MCP server listens on and the public URL it advertises in OAuth metadata and resource discovery.

GPT_FS_MCP_HOST

string

default:"127.0.0.1"

The hostname or IP address the HTTP server binds to. The default binds to loopback only, which means the server is not reachable from other machines. Do not change this to 0.0.0.0 or a public interface unless you are intentionally exposing the server and have auth fully configured.

GPT_FS_MCP_PORT

integer

default:"8789"

The TCP port the server listens on. Must be a positive integer. Change this only if port 8789 is already occupied on your machine.

PUBLIC_BASE_URL

string

default:"http://127.0.0.1:8789"

The base URL the server advertises in OAuth protected resource metadata and authorization server discovery. For local-only use, the default loopback URL is correct. For a remote ChatGPT connector with Cloudflare Tunnel, set this to your HTTPS public hostname (e.g. https://mcp.your-domain.example). When AUTH_REQUIRED=true and the URL is not localhost, HTTPS is enforced.

TRUST_PROXY_HEADERS

boolean

default:"false"

When true, the server trusts X-Forwarded-For and related reverse-proxy headers for rate limiting and IP extraction. Only set this to true if the server sits behind a trusted reverse proxy that you control. Setting it true when the server is directly internet-facing allows IP spoofing.

Authentication

These variables control the authentication system: whether auth is required, PKCE enforcement, rate limiting on the auth endpoints, and the in-memory store limits for auth codes and tokens.

AUTH_REQUIRED

boolean

default:"true"

Master switch for authentication. When true, all requests to the MCP endpoint require a valid OAuth access token. Set to false only for a localhost-only smoke test before OAuth is configured — the server enforces that AUTH_REQUIRED=false cannot be combined with a public HTTPS URL, a Cloudflare Tunnel, or a non-loopback bind address.

AUTH_REQUIRE_PKCE

boolean

default:"true"

When true, the OAuth authorization code flow requires PKCE (code_challenge / code_verifier). Leave this enabled. Disabling it weakens the authorization code flow and should only be considered for debugging against a client that does not support PKCE.

The synthetic identity login used when AUTH_REQUIRED=false. This value appears in journals and logs to identify the actor. Only relevant for local smoke tests — it has no effect when AUTH_REQUIRED=true.

AUTH_RATE_LIMIT_MAX

integer

default:"60"

Maximum number of requests allowed per IP address within the rate-limit window on authentication endpoints. Requests above this threshold receive a 429 Too Many Requests response.

AUTH_RATE_LIMIT_MAX_BUCKETS

integer

default:"10000"

Maximum number of IP-keyed rate-limit buckets kept in memory simultaneously. Limiting this prevents unbounded memory growth from large numbers of distinct IPs hitting the auth endpoints.

AUTH_RATE_LIMIT_WINDOW_MS

integer

default:"60000"

The sliding window duration in milliseconds for the auth rate limiter. The default is 60 seconds. Each IP’s request count resets after this period.

AUTH_STORE_MAX_PENDING

integer

default:"1000"

Maximum number of in-flight OAuth authorization requests (pending state entries) the server holds in memory. Excess entries are rejected to prevent memory exhaustion from abandoned flows.

AUTH_STORE_MAX_AUTH_CODES

integer

default:"1000"

Maximum number of issued authorization codes the server keeps in memory before older ones are evicted. Each code is short-lived and consumed on token exchange.

AUTH_STORE_MAX_TOKENS

integer

default:"100"

Maximum number of active access tokens the server holds in memory simultaneously. This is intentionally small — the server is designed for a single authorized ChatGPT connector, not many concurrent clients.

AUTH_STORE_CLEANUP_INTERVAL_MS

integer

default:"60000"

How often (in milliseconds) the auth store scans for and removes expired codes, tokens, and pending entries. The default is 60 seconds.

GitHub OAuth

GitHub is used as the identity provider. You sign in with GitHub, the server checks your login against the allowlist, and then issues a local MCP authorization code. These credentials come from your GitHub OAuth App — they are separate from the ChatGPT connector OAuth credentials below.

GITHUB_CLIENT_ID

string

The Client ID from your GitHub OAuth App. Required when AUTH_REQUIRED=true. The GitHub OAuth App callback URL must be set to https://your-public-host.example/callback.

GITHUB_CLIENT_SECRET

string

The Client Secret from your GitHub OAuth App. Required when AUTH_REQUIRED=true. Keep this value secret.

ALLOWED_GITHUB_LOGINS

string

Comma-separated list of GitHub usernames that are permitted to complete authentication. After a successful GitHub login, the server checks the authenticated username (case-insensitive) against this list before issuing a local authorization code. Required when AUTH_REQUIRED=true. Example: alice,bob.

ALLOWED_GITHUB_LOGINS is your primary access control gate. Keep this list as narrow as possible — ideally just your own GitHub username.

ChatGPT Connector OAuth

ChatGPT connects to this MCP server as an OAuth client. These credentials are configured in the ChatGPT connector settings and then mirrored here. They are completely separate from your GitHub OAuth credentials.

OAUTH_CLIENT_ID

string

The OAuth client ID that ChatGPT presents when initiating the authorization flow. This value is assigned when you create the ChatGPT MCP connector. Required when AUTH_REQUIRED=true.

OAUTH_CLIENT_SECRET

string

The OAuth client secret that ChatGPT presents at the token endpoint. Required when AUTH_REQUIRED=true. If the connector is deleted and recreated, ChatGPT may issue a new secret — update this value and restart the server.

OAUTH_REDIRECT_URIS

string

Comma-separated list of allowed OAuth redirect URIs. ChatGPT provides a redirect URI during the authorization request; the server rejects any URI not in this list. Non-localhost URIs must use HTTPS. Required when AUTH_REQUIRED=true. If ChatGPT gives you a new redirect URI after recreating the connector, add it here.

DEFAULT_OAUTH_SCOPES

string

Space-separated list of MCP scopes included in access tokens by default. The default grants all ten scopes. Narrow this list to limit which tool categories ChatGPT can access without requiring per-session scope negotiation. See Security — Scopes for the full scope reference.

For a first remote connector, consider starting with a narrower scope set such as mcp:read mcp:git and expanding only as needed.

Cloudflare Tunnel

Cloudflare Tunnel is the recommended way to expose the local MCP server to ChatGPT over HTTPS without opening inbound firewall ports. These variables control whether the server starts a local cloudflared process and how it is configured.

CLOUDFLARE_TUNNEL_ENABLED

boolean

default:"false"

When true, the server attempts to start or monitor a Cloudflare Tunnel using the cloudflared binary. Cannot be combined with AUTH_REQUIRED=false.

CLOUDFLARED_EXE

string

Optional absolute path to the cloudflared executable. If empty, the server looks for cloudflared on the system PATH. Example: C:\tools\cloudflared.exe.

CLOUDFLARED_CONFIG

string

Path to the cloudflared configuration YAML file. Required when CLOUDFLARE_TUNNEL_ENABLED=true and using a locally managed named tunnel. Example: C:\Users\you\.cloudflared\config.yml.

CLOUDFLARE_TUNNEL_NAME

string

default:"chatgpt-local-agent-mcp"

The name of the Cloudflare Tunnel. Used for display and identification in dashboard output. Change this if you have multiple tunnels and need to distinguish them.

Filesystem & Workspace

These variables control where the server starts, how much of the filesystem it can reach, what policy mode ceiling applies, and where it stores journals and backups.

GPT_FS_MCP_DEFAULT_CWD

string

default:"Documents/GitHub (inside home dir)"

The initial working directory used for relative paths and shell commands. If empty or not set, falls back to Documents\GitHub inside the current user’s home directory (e.g. C:\Users\you\Documents\GitHub on Windows). This does not restrict filesystem access on its own — use GPT_FS_MCP_WORKSPACE_PROFILES_JSON for that.

GPT_FS_MCP_MAX_POLICY_MODE

string

default:"destructive"

The highest policy mode the server will permit across all tool calls. Valid values are read, annotate, suggest, write, patch, delete, and destructive. Setting this to a lower value like write prevents tools from deleting files even if the client requests it. See Security — Policy Modes for the full hierarchy.

GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES

boolean

default:"true"

When true, all filesystem and shell operations are checked against the declared workspace profiles. Paths outside every profile’s rootPath are rejected. Set to false only if you are intentionally running without profile-based path restrictions.

GPT_FS_MCP_WORKSPACE_PROFILES_JSON

string

A JSON array of workspace profile objects. Each profile defines a rootPath, a name, an optional label, allowedPolicyModes, backupPolicy (none | manual | snapshot), and secretDenyGlobs. When empty, the server auto-generates one profile per detected drive root on Windows (e.g. C:\, D:\), giving full-machine access. Define explicit profiles to restrict access to specific folders or repos.

[
  {
    "name": "my-project",
    "label": "My Project",
    "rootPath": "C:\\Users\\you\\projects\\my-project",
    "allowedPolicyModes": ["read", "write", "patch"],
    "backupPolicy": "manual",
    "secretDenyGlobs": ["**/.env", "**/*secret*"]
  }
]

GPT_FS_MCP_JOURNAL_PATH

string

default:".\\data\\journal.jsonl"

Path to the JSONL operation journal file. The server appends a structured log entry for each MCP tool call, redacting common secret-looking fields. Relative paths are resolved from the server’s working directory (the install folder).

GPT_FS_MCP_BACKUP_DIR

string

default:".\\data\\backups"

Directory where file backups are written before destructive operations. Relative paths are resolved from the install folder.

GPT_FS_MCP_UNTRUSTED_CONTENT_ROOTS

string

Comma-separated list of absolute paths that are treated as untrusted content sources. Files read from these paths are handled with additional caution. Useful for marking directories that contain user-generated or third-party content that should not be treated as trusted instructions.

Shell & Process

These variables control whether shell and process execution tools are available and how they behave relative to workspace boundaries. See Command Policies for the full policy reference.

GPT_FS_MCP_SHELL_POLICY

string

default:"full"

Controls the shell tool’s access to paths outside declared workspace profiles. Valid values: disabled (tool is unavailable), workspace_guarded (checks working directory and path references against profiles), full (no path restriction beyond scopes and policy mode). See Command Policies.

GPT_FS_MCP_PROCESS_POLICY

string

default:"full"

Controls start_process tool access relative to workspace profiles. Same three values as GPT_FS_MCP_SHELL_POLICY. Note: stop_process and process_kill are governed by scope and policy mode checks, not by this command policy gate. See Command Policies.

GPT_FS_MCP_SHELL_TIMEOUT_MS

integer

default:"120000"

Maximum time in milliseconds a shell command is allowed to run before it is forcibly terminated. The default is 120 seconds (2 minutes). Increase this for long-running build commands; lower it for tighter latency control.

Limits & Sizing

These variables cap the size of request bodies, file backups, tool output, and screenshot data. They protect against accidental or intentional requests that would transfer very large amounts of data.

GPT_FS_MCP_MAX_BODY_BYTES

integer

default:"300000"

Maximum allowed size in bytes for incoming HTTP request bodies. When unset, defaults to 150% of GPT_FS_MCP_MAX_OUTPUT_BYTES (i.e. ceil(200000 * 1.5) = 300000). Must be at least 110% of GPT_FS_MCP_MAX_OUTPUT_BYTES. The server enforces this relationship at startup.

GPT_FS_MCP_MAX_BACKUP_BYTES

integer

default:"5000000"

Maximum size in bytes of a single file that will be backed up before a destructive operation. Files larger than this limit are not backed up.

GPT_FS_MCP_MAX_OUTPUT_BYTES

integer

default:"200000"

Maximum size in bytes for a single tool’s text output. Responses that exceed this limit are truncated before being returned to the MCP client.

GPT_FS_MCP_MAX_SCREENSHOT_AREA_PIXELS

integer

default:"33000000"

Maximum allowed pixel area (width × height) for a captured screenshot. Screenshots that would exceed this area are rejected or scaled down.

GPT_FS_MCP_MAX_SCREENSHOT_BYTES

integer

default:"100000000"

Maximum file size in bytes for a single screenshot image.

GPT_FS_MCP_MAX_SCREENSHOT_DIMENSION

integer

default:"8192"

Maximum width or height in pixels for a captured screenshot. Either dimension exceeding this value causes the screenshot to be rejected or resized.

GPT_FS_MCP_MAX_SCREENSHOT_FILES

integer

default:"100"

Maximum number of screenshot files the server will retain on disk. Older files are rotated out when the count exceeds this limit.

Browser

These variables control browser automation sessions managed via Playwright. Browser tools are high-risk because they can interact with visible browser UI and active authenticated sessions.

GPT_FS_MCP_BROWSER_SESSION_IDLE_MS

integer

default:"1800000"

Time in milliseconds of inactivity after which an idle browser session is automatically closed. The default is 30 minutes (1,800,000 ms).

GPT_FS_MCP_MAX_BROWSER_LOG_ENTRIES

integer

default:"200"

Maximum number of browser console and network log entries retained per session. Older entries are dropped when the limit is reached.

GPT_FS_MCP_MAX_BROWSER_SCREENSHOT_FILES

integer

default:"100"

Maximum number of browser screenshot files retained on disk. Older files are rotated out when the count exceeds this limit.

GPT_FS_MCP_MAX_BROWSER_SCREENSHOT_BYTES

integer

default:"10000000"

Maximum file size in bytes for a single browser screenshot.

GPT_FS_MCP_MAX_BROWSER_SESSIONS

integer

default:"5"

Maximum number of concurrent browser sessions the server will manage. Requests to open a new session when the limit is reached are rejected.

Development

NODE_ENV

string

default:"development"

Node.js environment mode. Valid values are development and production. Setting AUTH_REQUIRED=false is only permitted when NODE_ENV is development or unset. Set to production for any deployment reachable from outside your local machine.

EXPOSE_RUNTIME_DEBUG

boolean

default:"false"

When true, the server exposes additional runtime diagnostic information in HTTP responses and logs. Do not enable this in production — it may leak internal state.

Example Configurations

Localhost-only smoke test (no OAuth required)

Use this configuration to verify the server starts and the dashboard is accessible before setting up GitHub OAuth and the ChatGPT connector. This configuration must never be used with a public URL or tunnel.

# Server
GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
PUBLIC_BASE_URL=http://127.0.0.1:8789
TRUST_PROXY_HEADERS=false

# Auth — disabled for local smoke test only
AUTH_REQUIRED=false
NODE_ENV=development

# Tunnel — must be off when AUTH_REQUIRED=false
CLOUDFLARE_TUNNEL_ENABLED=false

# Filesystem — restrict to one test folder
GPT_FS_MCP_MAX_POLICY_MODE=write
GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[{"name":"test-project","rootPath":"C:\\Users\\you\\projects\\test","allowedPolicyModes":["read","write"],"backupPolicy":"manual","secretDenyGlobs":["**/.env","**/*secret*"]}]

# Command policies — guarded for first test
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded

Never combine AUTH_REQUIRED=false with CLOUDFLARE_TUNNEL_ENABLED=true, a non-loopback GPT_FS_MCP_HOST, or an HTTPS PUBLIC_BASE_URL. The server enforces these constraints at startup and will refuse to start with an unsafe combination.

Remote production connector (Cloudflare Tunnel + full auth)

Use this configuration after the local smoke test succeeds and you are ready to connect ChatGPT via a public HTTPS endpoint.

# Server
GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
PUBLIC_BASE_URL=https://mcp.your-domain.example
TRUST_PROXY_HEADERS=true

# Auth — required for remote use
AUTH_REQUIRED=true
AUTH_REQUIRE_PKCE=true
NODE_ENV=production

# GitHub OAuth (identity provider)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
ALLOWED_GITHUB_LOGINS=your-github-username

# ChatGPT connector OAuth
OAUTH_CLIENT_ID=your_chatgpt_oauth_client_id
OAUTH_CLIENT_SECRET=your_chatgpt_oauth_client_secret
OAUTH_REDIRECT_URIS=https://chatgpt.com/aip/your-connector-id/oauth/callback
DEFAULT_OAUTH_SCOPES=mcp:read mcp:write mcp:git mcp:patch mcp:shell mcp:process mcp:browser

# Cloudflare Tunnel
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml
CLOUDFLARE_TUNNEL_NAME=chatgpt-local-agent-mcp

# Filesystem — single project workspace
GPT_FS_MCP_MAX_POLICY_MODE=destructive
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","delete","destructive"],"backupPolicy":"snapshot","secretDenyGlobs":["**/.env","**/.env.*","**/*secret*","**/*token*","**/*credential*"]}]

# Command policies — guarded for safety
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
GPT_FS_MCP_SHELL_TIMEOUT_MS=120000

Get Started

Setup Guides

Security & Auth

Configuration

Operations

Environment Variable Reference for ChatGPT Local Agent MCP

Server Binding

Authentication

GitHub OAuth

ChatGPT Connector OAuth

Cloudflare Tunnel

Filesystem & Workspace

Shell & Process

Limits & Sizing

Browser

Development

Example Configurations

Localhost-only smoke test (no OAuth required)

Remote production connector (Cloudflare Tunnel + full auth)

Build docs developers (and LLMs) love

Get Started

Setup Guides

Security & Auth

Configuration

Operations

Documentation Index

​Server Binding

​Authentication

​GitHub OAuth

​ChatGPT Connector OAuth

​Cloudflare Tunnel

​Filesystem & Workspace

​Shell & Process

​Limits & Sizing

​Browser

​Development

​Example Configurations

​Localhost-only smoke test (no OAuth required)

​Remote production connector (Cloudflare Tunnel + full auth)

Build docs developers (and LLMs) love

Server Binding

Authentication

GitHub OAuth

ChatGPT Connector OAuth

Cloudflare Tunnel

Filesystem & Workspace

Shell & Process

Limits & Sizing

Browser

Development

Example Configurations

Localhost-only smoke test (no OAuth required)

Remote production connector (Cloudflare Tunnel + full auth)