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.

Before connecting anything remotely, use the local control surfaces to verify the server is running correctly. These tools give you clear visibility into what the server is doing — and when an AI has tools near your machine, that visibility matters. The recommended order is always: confirm the dashboard and health endpoint are clean first, then consider the remote connector.

​
Web Dashboard

http://127.0.0.1:8789/dashboard
The web dashboard is the primary local control surface. It shows server status, recent GPT activity, security settings, file effects, process state, browser sessions, Cloudflare tunnel status, and the operation journal — all in one place. When the MCP server is running, the dashboard is served at the address above. Open it in any local browser before you start testing tools or connecting ChatGPT. The dashboard connects to the server’s own API endpoints (/dashboard/api/status, /dashboard/api/activity, etc.) to populate its panels, so if the dashboard loads and shows a live status, the server is genuinely responding.
The dashboard exists because visibility matters when an AI has tools near your machine. Keep it open in a browser tab while ChatGPT is connected.

​
Health Endpoint

http://127.0.0.1:8789/healthz
The health endpoint is the fastest way to confirm the server is alive. A healthy response looks like: 
200 OK
The server-control.ps1 script checks both the local and public health endpoints when you run Status + health from the control menu. You can also hit the endpoint directly in a browser or with PowerShell: 
Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:8789/healthz" -TimeoutSec 8
If the endpoint returns a non-200 response or times out, the server is not ready — check the server logs before proceeding.

​
Control Menu

The installer creates a batch file shortcut that opens the top-level control menu: 
chatgpt-local-agent-mcp-control.bat
The batch file presents the following options:
#Option
1Open fallback dashboard
2Open web dashboard
3Open repo folder
4Server and tunnel control
5Start live monitor
6Open local health endpoint
Choosing 4 — Server and tunnel control launches scripts/server-control.ps1, which provides its own interactive sub-menu with options to start, stop, and restart the local MCP server and Cloudflare tunnel, check status and health, view endpoint info and scopes, test the public auth guard, show logs, list non-local TCP listeners, and open the local dashboard. Run the batch file from the install folder or use the Desktop shortcut created by the installer.
scripts/server-control.ps1 reads your .env on startup. If you change .env values, restart the script to pick up the new settings.

​
Live Monitor

The installer also creates a batch file shortcut for the live monitor: 
chatgpt-local-agent-mcp-live-monitor.bat
The live monitor (scripts/live-monitor.ps1) tails the operation journal in real time and alerts you when ChatGPT uses high-risk tools, accesses paths outside a designated test root, or runs suspicious commands. It prints a timestamped line for every journal entry and fires a console beep with a prominent STOP GPT banner if a blocked or suspicious action is detected. By default, the monitor watches the journal at the path configured by GPT_FS_MCP_JOURNAL_PATH (default: .\data\journal.jsonl). You can pass a custom test root as a parameter: 
.\scripts\live-monitor.ps1 -TestRoot "C:\Projects\my-test-repo"
The monitor operates in alert-only mode — it will warn you but will not automatically kill any process. Intervention is always your decision.

​
Fallback PowerShell Dashboard

The fallback dashboard (apps/fallback-dashboard/fallback-dashboard.ps1) is a WinForms GUI that provides the same status panels as the web dashboard but runs entirely in PowerShell — no browser required and no dependency on the web server being reachable. Use the fallback dashboard when:
  • The web server has not started yet and you need to diagnose why
  • The web dashboard is unreachable for any reason
  • You prefer a native Windows GUI over a browser tab
The fallback dashboard must be launched with PowerShell in STA mode: 
powershell.exe -STA -File "apps\fallback-dashboard\fallback-dashboard.ps1"
It auto-detects the runtime install folder at %LOCALAPPDATA%\chatgpt-local-agent-mcp and falls back to the source root if no .env is found there. When the MCP server is running and the web API is reachable, the fallback dashboard connects to http://127.0.0.1:8789/dashboard/api/* for live data. When the server is offline, it falls back to reading the local journal directly. The fallback dashboard includes buttons to start, stop, and restart both the local MCP server and the Cloudflare tunnel, making it a self-contained control surface for cold-start scenarios.
The fallback dashboard requires PowerShell in STA (Single-Threaded Apartment) mode. The installer’s Open Control step handles this automatically. If you launch fallback-dashboard.ps1 from a non-STA session it will display an error and exit.

​
Desktop Shortcuts

The installer’s Create Shortcuts step creates Desktop and Start Menu shortcuts for the main local control surfaces. After running that step you will have quick access to:
  • The control menu batch file
  • The live monitor batch file
  • The fallback dashboard
Use Create Shortcuts from the installer whenever you update the install folder so the shortcuts stay pointed at the correct paths.

​
Operation Journal

The server records every MCP tool invocation — intent and result — to a newline-delimited JSON journal. The default path is: 
.\data\journal.jsonl
This path is configurable via the GPT_FS_MCP_JOURNAL_PATH environment variable. Common secret-looking fields (SECRET, TOKEN, PASSWORD, CLIENT_SECRET, API_KEY) are redacted in journal entries. The journal is the source of truth for the GPT Activity, Files, and Journal Explorer panels in both dashboards, and it is what the live monitor tails. If something unexpected happens during a session, the journal is the first place to look.

​
Local-Only Verification Before Going Remote

Do not connect ChatGPT before the local dashboard and health endpoint are working. The two-path sequence (Path A local first, Path B remote second) exists for good reason.
Before configuring the ChatGPT connector, confirm all of the following locally:
1

Start the server

Use the control menu or fallback dashboard to start the local MCP server.
2

Check the health endpoint

Open http://127.0.0.1:8789/healthz and confirm a 200 response.
3

Open the web dashboard

Open http://127.0.0.1:8789/dashboard and confirm the status panel shows the server as running.
4

Run smoke checks

In the installer, click Run Smoke Checks to confirm the build output exists and the local control surfaces are usable.
5

Optionally start the live monitor

Run chatgpt-local-agent-mcp-live-monitor.bat in a separate terminal so you have real-time visibility before any remote session begins.
Only after these checks pass should you proceed to configure the Cloudflare tunnel and ChatGPT connector.

Build docs developers (and LLMs) love

Get started for freeTalk to us