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.

Most first-run problems fall into a small number of categories: local server not starting, OAuth values not matching what ChatGPT sends, the Cloudflare tunnel connector not running, browser binaries missing, or confusion between the GitHub OAuth layer and the ChatGPT connector OAuth layer. This page covers each of them with the specific cause and fix.
Cause: AUTH_REQUIRED=true (the default). When auth is required the server validates that OAuth values are present, so saving .env without them fails.Fix: For Path A — the local-only smoke test before OAuth is configured — set these three values and save .env again:
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false
This combination is allowed only while the server is bound to localhost with no tunnel enabled. It is the correct configuration for proving the server starts and the dashboard works before you set up any OAuth.
Do not use AUTH_REQUIRED=false with a public URL, public hostname, or Cloudflare Tunnel. The installer and server guard against this, but .env is still security-critical.
This is normal without a token.A protected MCP endpoint rejects unauthenticated requests by design. If you POST to /mcp without a valid Bearer token — for example, when testing the endpoint directly or running a smoke check before completing the OAuth flow — a 401 Unauthorized response is the correct behavior.You only need to investigate further if /mcp returns 401 after ChatGPT has successfully completed the authorization flow and should have a valid access token. In that case, check the server logs and confirm the access token TTL has not expired.
Cause: A mismatch between what the server expects and what ChatGPT is sending in the authorization request.The most common mismatches are:
  • OAUTH_CLIENT_ID — the value in .env does not match the client ID ChatGPT is sending
  • OAUTH_REDIRECT_URIS — the redirect URI ChatGPT sends is not in the server’s allowed list
  • PUBLIC_BASE_URL — the resource parameter in the request does not match the server’s configured public base URL
  • PKCE settings — the server expects PKCE and ChatGPT is not sending a code_challenge, or vice versa
Fix: Check the server logs for the exact mismatch message. Then compare the values ChatGPT is sending (visible in the authorization request URL) against your .env:
OAUTH_CLIENT_ID=
OAUTH_REDIRECT_URIS=
PUBLIC_BASE_URL=https://your-public-host.example
If you deleted and recreated the ChatGPT connector, ChatGPT may have assigned a new redirect URI. Update OAUTH_REDIRECT_URIS in .env to match the new value.
Cause: The OAUTH_CLIENT_SECRET in .env does not match what ChatGPT is sending during the token exchange, or ChatGPT is not sending the expected client credentials at all.Fix: Verify the secret in .env matches exactly what you entered when configuring the ChatGPT connector:
OAUTH_CLIENT_SECRET=
Secrets are case-sensitive and must not have leading or trailing whitespace. If the values match and the error persists, check whether ChatGPT is sending credentials in the request body or as a Basic auth header — the server expects the standard OAuth 2.0 client credentials format.
Cause: The two OAuth layers are being confused with each other. GitHub OAuth and the ChatGPT connector OAuth are separate relationships and must be configured separately.The two layers:
LayerPurposeCallback / Redirect URI
GitHub OAuth App → MCP serverYou sign in with GitHub to authenticate yourselfhttps://your-public-host.example/callback
ChatGPT connector → MCP serverChatGPT connects as the MCP OAuth clientSet in OAUTH_REDIRECT_URIS — provided by ChatGPT when you configure the connector
The most common mistake: putting the ChatGPT redirect URI into the GitHub OAuth App’s Authorized redirect URIs. Do not do this. The GitHub OAuth App only needs the /callback endpoint on your public host.Fix: Verify each setting is in the right place:
  • GitHub OAuth App settings — Callback URL should be: 
    https://your-public-host.example/callback
  • ChatGPT connector — Connector URL should be: 
    https://your-public-host.example/mcp
  • .env — OAUTH_REDIRECT_URIS should contain the redirect URI provided by ChatGPT when you set up the connector (this is not the GitHub callback): 
    OAUTH_REDIRECT_URIS=
The GitHub App credentials and the ChatGPT connector OAuth credentials are also separate values. Do not mix them up in .env:
# GitHub identity layer
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=your-github-login

# ChatGPT connector OAuth layer
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=
Cause: Playwright browser binaries are missing from the install folder. The playwright package is installed by npm ci, but the actual browser binaries must be downloaded separately.Fix: Run the following from the install folder:
npx playwright install
This downloads the Chromium, Firefox, and WebKit binaries that Playwright uses for automation. If you only need Chromium (the most common case), you can limit the install:
npx playwright install chromium
Also check: The server must run under the Windows user account that owns the browser profile you expect to use. If you start the MCP server as a different user than the one whose Chrome or Edge profile you want to automate, the browser will either not be found or will open without the expected sessions and cookies.If you are using browser_cdp_connect to attach to an existing browser session, make sure the target browser is running with remote debugging enabled and that the debug port is accessible from the server process.
Cause: The Cloudflare DNS record and tunnel route are configured correctly, but the local cloudflared connector is not currently running. Cloudflare knows the tunnel exists but has no active replica to route traffic to, so it returns a 530 error.Checklist:
1

Confirm the MCP server is running

Open http://127.0.0.1:8789/healthz locally. If this does not respond, start the server first using the control menu or fallback dashboard.
2

Confirm cloudflared is running

Use the control menu option Status + health or check the fallback dashboard’s Cloudflare tab. If cloudflared is stopped, start it with option 5 in the control menu or the Start Tunnel button in the fallback dashboard.
3

Check for active replicas

In the Cloudflare dashboard, navigate to Zero Trust → Networks → Tunnels and confirm your tunnel shows at least one active replica (connector). A tunnel with 0 active replicas will return 530 even if the DNS record is correct.
4

Confirm the tunnel route

Verify the tunnel ingress rule points to http://127.0.0.1:8789 (not HTTPS, not a different port):
ingress:
  - hostname: mcp.your-domain.example
    service: http://127.0.0.1:8789
  - service: http_status:404
If the Cloudflare dashboard shows the tunnel as Down with 0 active replicas, the DNS configuration can still be correct. The 530 means the connector is not connected — start cloudflared and the replica count will update within a few seconds.
Cause: ChatGPT and OpenAI have their own safety layers that operate independently of this MCP server. Actions that write, submit, post, operate authenticated browser sessions, or control the desktop may be blocked or require confirmation on the ChatGPT side — even when the MCP server is fully capable of performing them.These blocks happen on the ChatGPT/OpenAI side, not in the MCP server. Making the server more powerful does not bypass them.How to distinguish server-side from ChatGPT-side blocks:
  1. Check the server logs first (server.out.log and server.err.log in the install folder’s logs/ directory). If the tool was invoked and returned an error, that is a server-side issue.
  2. Check the operation journal (data/journal.jsonl). If there is no journal entry for the attempted action, the tool call never reached the server — that is a ChatGPT-side block.
  3. If the journal shows an intent entry but no result entry, the server received the call but something went wrong during execution. Check the logs for the specific error.
If the journal has no record of the action at all, treat it as a platform boundary on the ChatGPT/OpenAI side. Rephrasing the request, confirming the action explicitly, or breaking it into smaller steps may help — but some actions are blocked by OpenAI policy regardless of how they are phrased.
For dashboard and health check guidance, see Local Control.

Build docs developers (and LLMs) love

Get started for freeTalk to us