ChatGPT Machine MCP — Technical Guide

01 / Request path

One client call, consistent gates

Streamable HTTP enters the MCP server directly. Tunnel stdio enters through src/supervisor.ts, which isolates src/index.ts in a worker process and restarts/reinitializes that worker after a crash or hard request deadline. Inside the worker, one registry validates the tool name and arguments before policy, preconditions, idempotency, and handlers can touch the host.

The tunnel is transport plumbing. The MCP server itself is not tied to a specific ChatGPT UI and can serve any compatible client.

02 / Tool surface

Purpose-built tools instead of ambiguous shell prompts

Inspect (7) machine_status, read_file, list_directory, find_files, file_info, image_info, search_code

Edit (4) write_file, edit_file, update_file, apply_patch

Run (6) shell_command, start_process, process_status, read_process_output, stop_process, process_write. A timed-out shell call can promote itself into the managed registry instead of losing the job.

Git (9) git_status, git_diff, git_log, git_show, git_branch, git_add, git_commit, git_checkout, git_push

System (6) system_info, list_processes, list_ports, environment_info, disk_info, network_info

Image + Audit (3) save_image_from_url, audit_recent, audit_search

Verified workflow (2) verify_changes runs fast | normal | strict project gates; git_commit_verified verifies first, refuses an existing staging area, stages only explicit paths, and commits locally. Push remains a separate approval/network boundary. — 37 tools total.

Concurrency guard

File reads return a SHA-256 digest. Writes can pass expected_sha256, converting a stale update into PRECONDITION_FAILED instead of silently overwriting a newer edit.

Stable failures

Code	Meaning
`INVALID_ARGUMENT`	Missing, invalid, or out-of-range input.
`PATH_DENIED`	Workspace boundary, symlink escape, or OS permission block.
`PRECONDITION_FAILED`	The file changed after it was read.
`AMBIGUOUS_MATCH` / `NO_MATCH`	Text edit cannot be applied safely.
`TIMEOUT` / `NETWORK`	External command or download did not complete.

03 / Authority

Workspace-only by default. Unrestricted by choice.

WORKSPACE_ONLY

Paths, file tools, search, shell working directories, and patches resolve under --root. Symlink/junction escapes are rejected.

UNRESTRICTED_MACHINE

--dangerously-open-machine permits absolute paths and arbitrary shell reach with the authority of the current Windows user.

This is an administrative bridge, not a hostile multi-tenant sandbox. Only connect an account and tunnel that you trust with the same authority as the Windows account running it.

Network and image safeguards

save_image_from_url accepts HTTPS only, rejects private/local network destinations, has limited redirects, sends no caller cookies or authorization headers, and validates PNG/JPEG/WebP signatures before writing.

04 / Transport

Supervised stdio for the tunnel; HTTP as an alternate transport

node dist/index.js --http --http-port 8787 --root D:\Projects\Github

/healthz reports process liveness; /readyz reports readiness and can return 503 while the HTTP runtime is starting. MCP traffic is served at /mcp. The dependency-free /ui page reads the last 50 redacted audit events from /ui/audit. Binding HTTP beyond loopback requires a bearer token, which also protects the UI endpoints.

node dist/index.js --http --http-host 0.0.0.0 --http-token "<secret>" --root D:\Projects\Github

05 / Runtime operations

Managed processes and tunnel lifecycle

Use start_process for servers and watchers. It returns a PID; process_status, read_process_output, and stop_process handle the lifecycle. Output capture is bounded, while process metadata and logs are persisted under .chatgpt-machine/ so a restarted MCP worker can recover inspection and stop operations.

start_process(command="npm run dev") -> pid
read_process_output(pid, wait_ms=5000) -> stdout / stderr
stop_process(pid) -> stops the process tree

Normal operation uses the operator CLI (after npm link):

chatgpt-local setup       # initialize local config + preflight
chatgpt-local up          # build + start supervised tunnel
chatgpt-local status      # tunnel + supervisor generation/restarts
chatgpt-local restart     # detached refresh via refresh-tunnel
chatgpt-local down        # stop-tunnel
chatgpt-local doctor      # dependencies + workspace permissions
chatgpt-local check       # effective runtime + v2 contract fingerprint
chatgpt-local config show
chatgpt-local version

Local runtime settings live in Git-ignored .chatgpt-machine/config.json. chatgpt-local use <path> persists the active workspace; status reports the live worker root and explicitly marks when a restart is required. The v2 contract fingerprint is derived from the 37 public tool names, schemas, and annotations, making MCP-surface drift visible during deployment checks.

While a tunnel has been intentionally started, watch-tunnel.ps1 or watch-tunnel.sh checks its managed runtime every 15 seconds. Two consecutive unhealthy checks reconnect the tunnel; diagnostics stay bounded in .tunnel/watch-tunnel.log. chatgpt-local down stops that watchdog first, so it never reverses an explicit shutdown.

Underlying scripts remain available for debugging (.ps1 on Windows, .sh on macOS/Ubuntu/WSL):

.\scripts\start-tunnel.ps1     # or ./scripts/start-tunnel.sh
.\scripts\status-tunnel.ps1    # or ./scripts/status-tunnel.sh
.\scripts\stop-tunnel.ps1      # or ./scripts/stop-tunnel.sh
.\scripts\refresh-tunnel.ps1   # or ./scripts/refresh-tunnel.sh  (detached, logs to .tunnel/refresh-tunnel.log)

On Windows, the runtime key belongs in .tunnel\control-plane-api-key.dpapi, which is ignored by Git. The launch scripts decrypt it only for the tunnel-client process and remove the plaintext environment variable in finally (both start-tunnel and refresh-tunnel).

macOS, Ubuntu, and WSL

The MCP server supports macOS, Ubuntu, and Ubuntu WSL with Bash as the default shell and POSIX process termination. Use start-tunnel.sh, status-tunnel.sh, and stop-tunnel.sh. macOS stores the runtime key in Keychain; Linux/WSL accepts CONTROL_PLANE_API_KEY or a local mode-600 key file. WSL controls its Linux environment, not arbitrary native Windows processes.

06 / Contributors

Change code and documentation together

npm run build
npm test

The test suite covers path containment, transactional edits, file preconditions, code search, image validation, timeout promotion, managed process lifecycle, Git inspection, MCP prompt/resource discovery, and stdio behavior. Use --doctor for dependency checks and --dry-run to suppress every mutating tool at the server gate.

File	Responsibility
`src/supervisor.ts`	Tunnel-facing stdio proxy, hard request deadline, worker restart/reinitialize, generation and persisted supervisor state.
`src/index.ts`	MCP worker, CLI parsing (--root, --dangerously-open-machine, --http, --check, --doctor, --dry-run), stdio/HTTP transports, response envelope and HTTP health/readiness.
`src/cli.ts`	Operator CLI `chatgpt-local` (setup/up/down/restart/status/doctor/check/config/version), preflight and script selection per OS.
`src/config.ts`	Git-ignored local runtime configuration and tunnel environment mapping.
`src/contract.ts`	Versioned 37-tool public contract manifest (v2) and deterministic SHA-256 fingerprint.
`src/tools.ts`	Tool registry (37 tools), schemas, handlers, compact/expanded machine status, and contract metadata.
`src/verification.ts`	Detected fast/normal/strict project verification and verified local commit transaction.
`src/file-tools.ts`	Text, directory, image, and code-search operations.
`src/shell-tools.ts`	Path policy, shell execution (caps, timeout, encoding), apply_patch (Codex format).
`src/process-tools.ts`	Background process registry and log capture (4 MiB cap, offsets, wait_ms).
`src/git-tools.ts`	Direct Git (status/diff/log/show/branch/add/commit/checkout/push) without shell interpolation.
`src/system-tools.ts`	System/process/port/env/disk/network inspection (bounded, secret-redacted).
`src/errors.ts`	`ToolError` codes — public contract shared by every module.
`AGENTS.md`	Repository invariants for coding agents.