VerityMCP: Connect ChatGPT Web Directly to Your Local Computer

Connect ChatGPT Web Chat directly to your local computer.
Execute terminal commands, edit local files, automate Playwright browsers, inspect desktop windows, and run tests—backed by an ironclad Verification Engine that guarantees ChatGPT never hallucinates a successful action.

⚡ Quickstart: Install and Connect ChatGPT Web

Give ChatGPT Web hands-on terminal, code editing, and browser automation capabilities on your local computer.

Step 0: Install Dependencies (First Run Only)

Clone this repository and enter its directory. VerityMCP needs Node.js 20 or newer. The setup scripts check prerequisites, install missing Node.js/pnpm/Git/cloudflared where supported, install dependencies from pnpm-lock.yaml, download Playwright Chromium, and build the app. Depending on your OS, installing system prerequisites may prompt for administrator permission.

Windows: Double-click setup.bat or use PowerShell:

.\setup.bat
# Or run the PowerShell script directly:
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup.ps1

macOS / Linux:

bash ./setup.sh

To check prerequisites without installing anything, run setup.bat -CheckOnly on Windows or bash ./setup.sh --check on macOS/Linux. For local-only use, skip the Cloudflare dependency with -SkipCloudflared (Windows) or --skip-cloudflared (macOS/Linux). You can skip Chromium with -SkipBrowser / --skip-browser, but browser automation may not work. If a Linux distribution's Node.js package is older than 20, install a supported version from Node.js and rerun setup.

Windows troubleshooting: "node" is not recognized while running pnpm.cmd: This usually means Node.js was installed but the current terminal cannot find it. Close the installer, open a new Command Prompt, and run node --version and pnpm --version. If Node.js is still missing, run winget install --id OpenJS.NodeJS.LTS --exact, then open a new terminal and run setup.bat again. The setup script now checks that CMD can run Node.js before attempting pnpm, and fixes the session PATH when possible.

Step 1: Launch VerityMCP

Double-click start.bat on Windows (or run pnpm start on macOS/Linux):

start.bat

==========================================================
    VERITY MCP (Verified Local Computer Engineering Layer)    
==========================================================
[Launcher] Starting Cloudflare tunnel on port 7980...

==========================================================
                 CONNECTION READY!                        
==========================================================
  MCP Server URL:   https://neat-agent-tunnel.trycloudflare.com/mcp (COPIED TO CLIPBOARD)
  Owner Token:      <YOUR-GENERATED-OWNER-TOKEN>
==========================================================

On Windows, the secure Cloudflare tunnel URL is automatically copied to your clipboard.

macOS/Linux: pnpm start starts a local server but does not create a remote tunnel. Run cloudflared tunnel --url http://127.0.0.1:7980 in one terminal, then start the server in another with VERITY_PUBLIC_BASE_URL=https://YOUR-TUNNEL.trycloudflare.com pnpm start (substitute the URL Cloudflare printed). Connect to that HTTPS URL with /mcp appended. If the Linux installer placed cloudflared in ~/.local/bin, ensure that folder is on your PATH.

Step 2: Add to ChatGPT Web

1. Open ChatGPT in your browser.

2. Go to Settings → Connected Apps (or Developer Settings → MCP Servers).

3. Click Add Server:

   • Name: Local PC (VerityMCP)

   • URL: Paste the clipboard URL (e.g. https://neat-agent-tunnel.trycloudflare.com/mcp)

   • Authorization: Enter your Owner Token from the terminal window.

4. Click Save & Connect.

Step 3: Tell ChatGPT What to Do!

Ask ChatGPT anything in your chat:

"Inspect my current project directory, fix the broken login unit test, run pnpm test, and capture a browser screenshot of the web app running on localhost:3000 to verify the fix."

ChatGPT now interacts with your real local environment in real time, with mathematical proof that every command and file write succeeded.

Related MCP server: Chat On Steroids

🔍 Why Normal MCP Servers Fail (And How VerityMCP Solves It)

Standard MCP servers provide naive wrappers around fs.writeFile or child_process.exec. When autonomous agents in ChatGPT use them, they constantly hallucinate success:

[ChatGPT asks to update file]
Naive MCP Server: "Success!" ───► ChatGPT believes file was changed.
Reality: Hunks did not match, disk file unchanged, build fails later, agent gets stuck in a loop.

VerityMCP is engineered around one primary design law:

"AN AGENT MUST BE ABLE TO TRUST ITS TOOLS."

A tool returning success when nothing happened is worse than a tool returning an error.

VerityMCP enforces mandatory pre- and post-condition verification on every operation:

🏛️ Architecture

VerityMCP acts as the secure, high-integrity bridge between ChatGPT and your local machine:

flowchart TD
    subgraph Remote["OpenAI Cloud"]
        GPT["ChatGPT Web Chat (chatgpt.com)"]
    end

    subgraph Transport["Secure Transport"]
        Tunnel["Cloudflare Secure Tunnel<br/>(HTTPS / WSS)"]
        LocalSSE["Local HTTP / SSE<br/>(127.0.0.1:7980)"]
    end

    subgraph VerityCore["VerityMCP Execution Runtime"]
        Auth["RFC 9728 / 8414 OAuth & Bearer Guard"]
        Router["Streamable MCP Tool Router (65 Tools)"]
        
        subgraph Subsystems["Verified Engines"]
            FS["Filesystem Engine<br/>Atomic Edit, Patch & Rollback"]
            Shell["Shell Runtime<br/>PowerShell, cmd, Git Bash, ConPTY"]
            Browser["Playwright Engine<br/>Stable Refs, Snapshots & Screenshots"]
            LSP["LSP & Symbol Engine<br/>AST Outline, Definition & Types"]
            Desk["Desktop Automation<br/>GDI Screenshots & Window Focus"]
        end

        Engine["VERIFICATION ENGINE<br/>- SHA-256 Byte Readback<br/>- In-DOM Property Checks<br/>- Monotonic Cursor Pagination<br/>- Git Status & Diff Validation"]
    end

    GPT -->|Secure HTTPS| Tunnel
    Tunnel --> LocalSSE
    LocalSSE --> Auth
    Auth --> Router
    Router --> Subsystems
    Subsystems --> Engine
    Engine -->|Verified Results + Base64 Visuals| Router

⚡ Fast Agent Profile

VerityMCP defaults to a fast tool profile. Common filesystem, shell, browser, Git, diagnostics, and durable-run tools are exposed directly so the model has a much smaller tool menu to reason over before its first action.

• Specialist capabilities are not removed. Use discover_tools to find them and invoke_tool to execute them on demand.

• Use task_bootstrap at the start of repository work when you need workspace, fresh Git status, optional relevant-code matches, managed processes, and recent activity together.

• Set VERITY_TOOL_PROFILE=full to restore direct exposure of the complete legacy tool surface.

• Tool calls default to compact response metadata to avoid repeating large structured payloads in model context. Pass response_detail: "full" on an individual call, or set VERITY_RESPONSE_DETAIL=full, when complete structured diagnostics are needed.

• Verification remains enabled in both profiles; the optimization reduces schema/context overhead rather than skipping state checks.

• For interactive ChatGPT agent work with VerityMCP, prefer GPT-5.6 Sol over GPT-6 Sol unless GPT-6 Sol is specifically required.

Agents are instructed to make an early safe inspection/action call for clear tasks instead of spending a long planning phase before touching the machine.

🛠️ Complete Tool Reference

VerityMCP exposes a unified, production-ready tool surface organized across 12 engineering domains:

1. Workspace Onboarding & Repo Map

• open_workspace: Opens a local directory or Git repo. In a single call, generates an architectural repo map, Git status/branch, package manifest scripts, detected shells, and discovered project skills.

2. Verified Filesystem & Mutations

• read_file: Reads files with line slicing (line_start, line_end) and SHA-256 hash. Returns direct base64 image blocks for visual formats (.png, .jpg, .svg, etc.).

• write_file: Atomically writes file content with mandatory post-write byte readback and SHA-256 integrity check.

• edit_file: Performs exact-string replacements with occurrence validation, unified diff output, and post-mutation hash checks.

• apply_patch: Applies multi-file Codex or unified diffs with atomic staging, automatic rollback on mismatch, and post-write SHA-256 verification.

• delete_file: Deletes files or directories with post-unlinking existence confirmation.

• move_file: Renames or relocates files with source-removed and destination-verified checks.

• copy_file: Duplicates files with byte-for-byte equality verification.

• list_directory: Recursively lists directories with depth controls and .gitignore parsing.

• locate_files: Fast file locator by glob pattern or filename substring.

• file_metadata: Inspects file size, line counts, MIME types, timestamps, and SHA-256 hashes.

3. Code Search & Structural Intelligence

• search_code: Ultra-fast code search powered by native ripgrep with line numbers, regex, and file filtering.

• get_outline: Extracts structural symbols (functions, classes, interfaces, methods, types) from code files without reading entire files.

4. Language Server Protocol (LSP) Tools

• lsp_goto_definition: Jump directly to the declaration location of a symbol.

• lsp_find_references: Find all references to a symbol across the entire repository.

• lsp_hover: Retrieve type signatures and docstrings at cursor position.

• lsp_document_symbols: Extract document symbol hierarchies (outline, normal, full).

• lsp_workspace_symbols: Project-wide symbol search by name query.

• lsp_type_definition: Navigate directly to symbol type definitions.

5. Jupyter Notebook Engine

• read_notebook: Structurally parses .ipynb files into markdown, code cells, execution counts, and outputs.

• edit_notebook: Atomically edits, replaces, inserts, or deletes notebook cells with schema integrity checks.

6. Shell, Terminal & Process Runtime

• exec_command: Executes commands in explicit shells (powershell, cmd, git-bash). Returns immediately if finished within yield_ms, or yields a durable process session ID.

• read_process_output: Streams stdout/stderr chunks using cursor pagination without dropping output.

• write_stdin: Interacts with running processes via stdin.

• interrupt_process: Terminates process trees cleanly using native Windows taskkill /F /T or SIGINT.

• get_environment: Deep audit of local developer toolchains (Node, pnpm, Python, uv, Git, Docker, shells).

7. Playwright Browser Automation

• browser_navigate: Navigates persistent browser session to a URL and verifies load status.

• browser_snapshot: Builds an accessibility snapshot tree with stable element references ([ref=e1]), names, and roles.

• browser_click: Clicks element by stable ref or CSS selector.

• browser_double_click: Double clicks element.

• browser_hover: Triggers hover state.

• browser_fill: Types text into form fields with live DOM inputValue readback verification.

• browser_check: Checks or unchecks checkboxes with live DOM .isChecked() assertion.

• browser_select_option: Selects dropdown option by value or label.

• browser_upload_file: Uploads local files to file input elements.

• browser_press_key: Sends keystrokes (Enter, Tab, Escape, etc.).

• browser_evaluate: Evaluates JavaScript inside page context safely.

• browser_pdf: Prints current page to a disk PDF file.

• browser_screenshot: Captures viewport or full page, verifies the disk file, and returns a direct base64 ImageContent block.

• browser_console_logs: Inspects real-time browser console warnings, errors, and logs.

• browser_network_requests: Inspects HTTP requests made by the page.

• browser_close: Closes browser sessions cleanly.

8. Desktop Automation (Windows-First)

• screenshot_desktop: Captures full screen or region via Windows GDI and returns a direct base64 image block.

• list_windows: Enumerates open desktop windows with handles, titles, and process IDs.

• focus_window: Brings specific window to the foreground.

9. Git & Isolated Worktrees

• git_status: Inspects branch name, staged changes, and unstaged modifications.

• git_diff: Produces unified diff against HEAD or specified commit.

• show_changes: Unified summary of all uncommitted workspace modifications.

• revert_changes: Reverts uncommitted changes with post-revert verification.

• worktree_create: Creates an isolated Git worktree branch for safe experimentation.

• worktree_list: Lists all active Git worktrees.

• worktree_remove: Removes worktree with dirty-state safety guard.

10. Planning & Tasks

• task_create: Registers a goal in the persistent planning store.

• task_update: Updates task state (pending, in_progress, completed, failed).

• task_list: Inspects all tasks and execution progress.

11. Live Observability & Diagnostics

• activity_list: Lists live activity stream events (intent, action, verifications, fallbacks, warnings, results).

• activity_read: Cursor-paginated operational stream for live execution monitoring.

• activity_clear: Resets active activity stream buffer.

• verity_diagnostics: Returns system health, available shells, browser status, and tool reliability audit logs.

• verity_self_test: Fast automated self-test of core subsystems.

• verity_acceptance_test: Deep end-to-end acceptance test verification.

💻 Configuration Guides

1. ChatGPT Web Setup (Recommended)

1. Launch VerityMCP with start.bat.

2. Copy the generated Cloudflare URL (https://<subdomain>.trycloudflare.com/mcp).

3. In ChatGPT Web, navigate to Settings → Connected Apps → Add Server.

4. Configure:

   • URL: https://<subdomain>.trycloudflare.com/mcp

   • Authentication: Bearer Token

   • Token: Copy the owner password displayed by start.bat, or read it from the ignored project .verity/auth.json (unless you configured VERITY_OWNER_TOKEN or a legacy home-directory credential).

2. Local IDE & Agent Setup

To run VerityMCP locally with standard MCP clients:

• Command: node dist/cli.js serve --port 7980

• HTTP / SSE Endpoint: http://127.0.0.1:7980/mcp

🔒 Security & Local Authority

VerityMCP runs with access to your local machine. We treat security as a first-class product boundary:

1. Approved Roots Boundary: File operations are strictly confined within configured directory roots. Attempting path traversal outside allowed boundaries is immediately rejected.

2. Owner Token Authentication: The HTTP/SSE endpoint requires Bearer authentication based on RFC 9728 and RFC 8414 standards.

3. User-Controlled Tunnel: Tunnels run via Cloudflare's quick tunnel service or local loopback. VerityMCP does not store your credentials on third-party servers.

4. Isolated Worktrees: When asking ChatGPT to make large architectural changes, use worktree_create to ensure work happens in an isolated Git worktree without touching your main working directory.

🧪 Testing & Verification

VerityMCP includes a rigorous test suite validating all verification mechanisms:

pnpm test

Test coverage includes:

• test/patcher.test.ts: Validates Codex patches, unified diffs, and guarantees prevention of false-success patch mutations.

• test/process_manager.test.ts: Verifies durable chunk buffering and cursor pagination under high stdout volume.

• test/browser.test.ts: Persistent Playwright browser automation, element refs, verified form inputs, and screenshot generation.

• test/todomvc.test.ts: 14-step automated TodoMVC scenario verifying accessibility snapshots, form fill, checkbox assertions, and console logs.

• test/server.test.ts: End-to-end HTTP MCP protocol handshake, OAuth metadata endpoints, and tool execution.

❓ Frequently Asked Questions (FAQ)

Can ChatGPT Web really edit files on my local Windows PC?

Yes. By using the Model Context Protocol (MCP) and a secure tunnel (such as Cloudflare or local reverse proxy), ChatGPT Web can call VerityMCP tools running on your machine to read files, write code, run build scripts, and verify tests.

How is VerityMCP different from standard MCP servers?

Standard MCP servers are fire-and-forget: they run a command and assume it succeeded. If a file edit doesn't apply cleanly or a test hangs, ChatGPT gets confused and hallucinates. VerityMCP enforces mathematical verification—reading back disk bytes via SHA-256 and testing live DOM states before confirming success.

Do I need to open firewall ports or have a public static IP?

No. start.bat launches an encrypted Cloudflare Tunnel (cloudflared) that establishes an outbound HTTPS tunnel. No port forwarding, DNS configuration, or firewall changes are required.

Does VerityMCP work on macOS and Linux?

Yes. VerityMCP runs on Node.js >= 20 across Windows, macOS, and Linux. On Windows, it includes specialized PowerShell/cmd/Git Bash detection and native GDI desktop tools.

📄 License

MIT © VerityMCP