ChatGPT Local Agent MCP Architecture and Request Flow

chatgpt-local-agent-mcp is a locally hosted Node.js server that implements the Model Context Protocol over Streamable HTTP. It runs on Windows, binds to 127.0.0.1:8789 by default, and exposes a single authenticated /mcp endpoint that ChatGPT uses to call tools on your machine. Every inbound tool call is checked against an OAuth access token, validated against MCP scopes, matched to a workspace profile, and logged to a local journal before execution. An optional Cloudflare Tunnel bridges the local server to a public HTTPS hostname so ChatGPT can reach it as a remote MCP connector without opening a port in your firewall.

Request flow

When ChatGPT is connected through the full remote setup, a request travels this path:

ChatGPT
  -> HTTPS hostname (e.g. https://mcp.your-domain.example/mcp)
  -> Cloudflare Tunnel
  -> http://127.0.0.1:8789
  -> local MCP server
  -> your Windows PC

For the local-only smoke test (Path A), the flow is simply:

Local client or browser
  -> http://127.0.0.1:8789
  -> local MCP server
  -> your Windows PC

No tunnel, no remote client, and no OAuth are involved in Path A.

Runtime defaults

Resource	Address
Server	`http://127.0.0.1:8789`
MCP endpoint	`http://127.0.0.1:8789/mcp`
Dashboard	`http://127.0.0.1:8789/dashboard`
Health check	`http://127.0.0.1:8789/healthz`
Install root	`%LOCALAPPDATA%\chatgpt-local-agent-mcp`
Default working directory	`%USERPROFILE%\Documents\GitHub`
Journal	`<install root>\data\journal.jsonl`
Backups	`<install root>\data\backups`

The host, port, and working directory are all configurable via environment variables (GPT_FS_MCP_HOST, GPT_FS_MCP_PORT, GPT_FS_MCP_DEFAULT_CWD).

Core components

Streamable HTTP MCP server

Uses @modelcontextprotocol/sdk v1.29+. Each POST to /mcp creates a fresh McpServer instance with a StreamableHTTPServerTransport. The server runs stateless — no persistent session is maintained between requests.

Express HTTP server

Express v5 handles all HTTP routing, body parsing, and error handling. Host header validation middleware rejects requests with unexpected Host values before they reach any route handler.

GitHub OAuth identity flow

GitHub is the identity provider for human login. The server redirects to GitHub, receives the OAuth callback at /callback, and checks the authenticated login against ALLOWED_GITHUB_LOGINS before issuing a local MCP authorization code.

Local MCP authorization flow

A local OAuth 2.0 authorization code + access token flow issues tokens to the ChatGPT connector. The server exposes standard OAuth metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. PKCE is required by default.

Scoped MCP tools

50+ tools across 8 categories, each tagged with a required scope and a policy mode. Before each tool call, the server checks the token’s scopes and rejects the call with 403 insufficient_scope if the required scope is missing.

Operation journal

Every tool call is recorded to a JSONL journal file. Common secret-looking fields (keys, tokens, credentials) are redacted before writing. Incomplete journal entries from a crashed run are marked unknown on startup recovery.

Local web dashboard

A browser-accessible dashboard at /dashboard shows server status, workspace profiles, recent journal entries, and tunnel state. Use it to confirm what is happening before trusting the remote connector.

PowerShell installer and fallback dashboard

A .bat installer with a GUI handles app file copy, preflight, .env configuration, dependency install, build, shortcut creation, and smoke checks. A fallback PowerShell dashboard provides local control when the web dashboard is unavailable.

Optional Cloudflare Tunnel

When CLOUDFLARE_TUNNEL_ENABLED=true, the dashboard reads the local cloudflared configuration file and displays the tunnel route and status. The tunnel itself is managed by cloudflared outside the Node.js process.

Tool categories

Tools are grouped into eight categories. Each category maps to one or more MCP scopes that must be present on the access token for calls in that category to succeed.

Category	Scopes required	Tools include
Workspace	`mcp:read`	`workspace_info`
Filesystem	`mcp:read`, `mcp:write`, `mcp:patch`, `mcp:delete`	`read_file`, `read_file_range`, `read_many`, `write_file`, `list_dir`, `tree`, `stat`, `stat_many`, `search`, `hash`, `mkdir`, `copy`, `move`, `delete`, `apply_patch`
Git	`mcp:git`	`git_status`, `git_diff`, `git_commit`
Shell	`mcp:shell`	`shell`
Process	`mcp:process`	`start_process`, `stop_process`, `process_kill`, `process_list`, `port_list`, `wait_for_port`, `tail_log`
Browser	`mcp:browser`	Browser sessions, navigation, page snapshots, console capture, network capture, screenshots, CDP attach
Screen	`mcp:screen`	Screenshot capture, OCR hook, window listing
Desktop	`mcp:desktop`	Mouse movement, clicks, keyboard input

Tool access is also controlled by policy modes (observe, diagnose, edit, operate, destructive) and workspace profiles. A tool call can be rejected for an insufficient scope, an exceeded policy mode ceiling (GPT_FS_MCP_MAX_POLICY_MODE), or a path that falls outside all configured workspace profiles.

Two-path model

Path A — local-only

The server runs bound to 127.0.0.1 with AUTH_REQUIRED=false and CLOUDFLARE_TUNNEL_ENABLED=false. No OAuth credentials are needed. This path is only for proving the server starts and the dashboard works. It must never be used with a public URL or a tunnel.

Path B — full remote connector

The server runs with AUTH_REQUIRED=true and a public HTTPS PUBLIC_BASE_URL. A Cloudflare Tunnel forwards the public hostname to the local server. Two separate OAuth configurations are required:

GitHub OAuth App — for human identity verification during the /authorize → /callback flow.
ChatGPT connector credentials — the OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, and OAUTH_REDIRECT_URIS that ChatGPT presents when connecting as the MCP client.

These two OAuth layers are completely separate and must not be confused. The GitHub redirect URI goes into the GitHub OAuth App settings. The ChatGPT redirect URI goes into OAUTH_REDIRECT_URIS in .env.

GitHub OAuth App callback:
  https://your-public-host.example/callback

ChatGPT MCP connector URL:
  https://your-public-host.example/mcp

If you delete and recreate the ChatGPT connector, ChatGPT may issue a different redirect URI. Update OAUTH_REDIRECT_URIS in .env and restart the server whenever this happens.

Workspace profiles and path enforcement

By default, when GPT_FS_MCP_WORKSPACE_PROFILES_JSON is not set, the server creates one workspace profile per detected Windows drive root (e.g. C:\, D:\). This gives full-machine filesystem access. Custom profiles narrow access to specific paths:

GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[{"name":"my-repo","label":"My Repo","rootPath":"C:\\Users\\you\\repos\\my-repo","allowedPolicyModes":["observe","diagnose","edit","operate","destructive"],"backupPolicy":"manual","secretDenyGlobs":["**/.env","**/*secret*"]}]

Each profile defines:

rootPath — the root directory the profile covers
allowedPolicyModes — which policy modes (observe, diagnose, edit, operate, destructive) tools may use within this profile
backupPolicy — none, manual, or snapshot
secretDenyGlobs — glob patterns for files the server refuses to read or expose

When GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true (the default), any tool call whose resolved paths do not fall inside a configured profile is rejected with 403 workspace_denied.

Key configuration variables

# Core server
GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
PUBLIC_BASE_URL=http://127.0.0.1:8789

# Auth
AUTH_REQUIRED=true
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=your-github-login
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=

# Tunnel
CLOUDFLARE_TUNNEL_ENABLED=false
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml

# Tool policy
GPT_FS_MCP_MAX_POLICY_MODE=destructive
GPT_FS_MCP_SHELL_POLICY=full
GPT_FS_MCP_PROCESS_POLICY=full
GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true

Learn more

OAuth model

Detailed breakdown of the two OAuth layers — GitHub identity and ChatGPT connector — including token flow, PKCE, and the OAuth metadata endpoints.

Tools overview

Full list of all registered tools, their scopes, policy modes, and input parameters.

Get Started

Setup Guides

Security & Auth

Configuration

Operations

ChatGPT Local Agent MCP Architecture and Request Flow

Request flow

Runtime defaults

Core components

Streamable HTTP MCP server

Express HTTP server

GitHub OAuth identity flow

Local MCP authorization flow

Scoped MCP tools

Operation journal

Local web dashboard

PowerShell installer and fallback dashboard

Optional Cloudflare Tunnel

Tool categories

Two-path model

Path A — local-only

Path B — full remote connector

Workspace profiles and path enforcement

Key configuration variables

Learn more

OAuth model

Tools overview

Build docs developers (and LLMs) love

Get Started

Setup Guides

Security & Auth

Configuration

Operations

Documentation Index

​Request flow

​Runtime defaults

​Core components

Streamable HTTP MCP server

Express HTTP server

GitHub OAuth identity flow

Local MCP authorization flow

Scoped MCP tools

Operation journal

Local web dashboard

PowerShell installer and fallback dashboard

Optional Cloudflare Tunnel

​Tool categories

​Two-path model

​Path A — local-only

​Path B — full remote connector

​Workspace profiles and path enforcement

​Key configuration variables

​Learn more

OAuth model

Tools overview

Build docs developers (and LLMs) love

Request flow

Runtime defaults

Core components

Tool categories

Two-path model

Path A — local-only

Path B — full remote connector

Workspace profiles and path enforcement

Key configuration variables

Learn more