chatgpt-mcp-codex

mcp Codex Author: JNSLayer2 ChatGPT mcp Codex is a local MCP hub that allows ChatGPT to dispatch tasks to a local Codex worker through MCP, and the results are returned to the review queue. ## Why Use ChatGPT mcp Codex The core logic of ChatGPT mcp Codex is to allow users to plan and discuss tasks in ChatGPT, confirm them, and then execute them directly in the same chat window using Codex. This approach significantly reduces Codex quota consumption and avoids the mental cost of switching between ChatGPT and Codex chat windows. It is recommended to set usage rules in the ChatGPT chat window, for example: ```text When starting codex mcp, invoking codex mcp requires my authorization, otherwise, it is considered a chat discussion. ``` This way, ChatGPT will not suddenly invoke MCP during discussions. For a complete explanation, see `docs/article.md`. ## Architecture Diagram ```text ChatGPT Web ↓ HTTPS tunnel ↓ User's local MCP Hub ↓ User's Codex worker ↓ review queue / audit / dashboard ``` ## 60-Second Quickstart / One-Click Local Installation After a fresh clone, run a command to create `.venv`, install dependencies, generate ignored `.env` / `.codex/config.toml`, initialize the local SQLite/demo repository, export schemas, run doctor and tests: ```bash git clone https://github.com/JNSlayer2/chatgpt-mcp-codex.git cd chatgpt-mcp-codex python3 -m scripts.install_local --smoke`--smoke` will temporarily start the Hub and run a fake-exec roundtrip, which does not require a Codex quota you only want to install without running smoke, you can omit `--smoke`. Daily startup still requires two Terminals for easy log viewing and stopping: Terminal 1: ```bash python3 -m ``` Terminal 2: ```bash python3 -m scripts.run_codex_worker --loop --fake-exec ``` Terminal 3 (optional, only needed to connect to ChatGPT Web): ```bash cloudflared tunnel --url <LOCAL_HUB_BASE_URL> ``` ## Local URLs Dashboard: ```text <LOCAL_HUB_BASE_URL>/ ``` Health: ```text <LOCAL_H_URL>/healthz ``` Local MCP URL: ```text <LOCAL_HUB_BASE_URL>/mcp ``` The actual local address can be viewed by running `python3 -m scripts.print_mcp_info` on your computer; the repository documentation only retains placeholders to avoid writing local details to GitHub. ## What to Fill in ChatGPT Connector Connector name: ```text ChatGPT mcp Codex ``` Description: ```text Local MCP Hub for task queue, Codex worker dispatch, review queue, approval, and audit. ``` MCP Server URL: ```text https://<YOUR_TUNNEL_URL>/mcp ``` Auth: ```text No auth / No authentication, only recommended for local dev/test. ``` You can also name the connector yourself, for example, `Home M4 Hub`, `Office iMac Hub`, `Personal MCP Hub`. ## HTTPS Scheme Options There are two options: - Free temporary URL: Use Cloudflare Quick Tunnel, fastest available, but URL may change after restarting the tunnel. - Fixed URL with your own domain: Use Cloudflare named tunnel + your own subdomain, ChatGPT connector usually only needs to be set once. If you have your own domain, it is recommended to use different subdomains for each computer, for example: ```text https://mcp-device.<YOUR_DOMAIN>/mcp https://mcp-home.<YOUR_DOMAIN>/mcp https://mcp-office.<YOUR_DOMAIN>/mcp ``` Do not put device names in URL paths, and do not use spaces. Device names are placed in ChatGPT connector names, and MCP Server URLs keep the `/mcp` suffix. For a complete explanation, see `docs/tunnel-options.md`. ## Key Points for Beginners - `127.0.0.1` is "your own computer". - Codex worker runs on "your own computer". - ChatGPT Web cannot directly connect to your localhost. - Therefore, ChatGPT Web needs to connect to your computer through an HTTPS tunnel. - The tunnel URL points to the computer currently running the tunnel. - If you log in to the same ChatGPT account on another computer, it will still connect to the tunnel behind the same host. - Do not share the tunnel URL with untrusted individuals. - The tunnel URL is equivalent to a temporary entrance; when the tunnel is open, anyone who knows the URL can call the public `GET /mcp` and `POST /mcp`. - Public `/mcp/*` subpaths are not open; legacy compatibility subpaths are only reserved for localhost. - Public `/mcp` verifies `Origin`: no `Origin` is allowed to pass; with `Origin`, only ChatGPT/OpenAI or the same-origin HTTPS is accepted, others will return `403`. - Public `/mcp` only exposes connector-safe allowlists: collaborative navigation, read-only handoff draft, simplified dry-run handoff, status recovery, and read-only workspace tools. Writing files, executing commands, worker claims/results, approval, and artifact/decision writing are only left for localhost. ## fake-exec and Real Codex It is recommended to use fake-exec first: ```bash python3 -m scripts.run_codex_worker --loop --fake-exec ``` fake-exec is a stable test path that does not consume Codex quota and will use the formal worker pipeline to complete task claims, worktree, heartbeat, execution, submit results, and review queues. Switch to real Codex worker: ```bash python3 -m scripts.run_codex_worker --loop ``` The real Codex worker will actually call the Codex CLI. If the real Codex CLI fails due to login, quota, Cloudflare challenge, network, or model output format, the Hub architecture may not be incorrect. Please use fake-exec to verify the overall process before real Codex. ## Frequently Asked Questions Q: WhyOS App find when Web ChatGPT works? A: MCP / Developer Mode currently mainly uses the Web version,OS App may not fully support it. Please use chatgpt.com Web first. Q I log in to on another computer, which will it use? A use the Codex by the connector URL is the MCP Hub that opened the tunnel, not the Code the currently logged-in device. Q: Can I run a set on each computer? A. Each computer runs its own Hub, worker, and and then builds different connector names in ChatGPT, such as Home M4 Hub, Office i. Q: Can I use it without a tunnel? You can test the Hub, worker, and dashboard locally ChatGPT Web cannot connect localhost. Q: slow down my computer? A: `cloudflared` is very lightweight; the main load Codex worker, git, and test execution Common Commands ```python3 -m scripts.install_local --smoke python3 -m scripts.doctor python3 -m scripts.print_mcp_info python3 scripts.smoke_local_round3 -m scripts.run_tests python3 -m scripts.release_check python3 -m scripts.github_publish ``` ## Pro × Codex Collaboration If the goal is to add ChatGPT Pro to daily multi-model collaboration, it is use ChatGPT Web/Pro to connect to the local Codex MCP Hub, let Pro plan, research, and disassemble, and Codex worker perform and reporting. This version adds three collaboration tools: - `collab_guide`: Let ChatGPT read the current collaboration rules, URL, and security boundaries. - `codex_handoff_draft`: read-only, does not modify the Hub DB; provides ChatGPT Pro with read/fetch mode to generate a complete handoff packet. - `codex_handoff_create`: organizes ChatGPT Pro's planning into plan/task/artifact refs and hands it over to the Codex worker. - `collab_pack_get`: uses `plan_id` to restore shared state and avoid information disconnection between ChatGPT and Codex. `codex_handoff_create` uses the `fake-codex` lane by default; public ChatGPT connectors also only allow this dry-run lane. For security verification workers, please run: ```bash python3 -m scripts.run_codex_worker --loop --fake-exec --lane fake-codex ``` For a detailed process, see `docs/chatgpt-pro-codex-collab.md`. ## v2 Workspace MCP Tools Status: v2 closed. v2.1 started for ChatGPT Pro × Codex collaboration glue; only allows handoff, context continuity, and connector safety-related changes. v2 has added workspace tools to the existing `/mcp` endpoint, allowing ChatGPT to safely read projects, search, view git status/diff, and request local approval before writing files or executing non-allowlisted commands within explicit allowed roots. Default security boundaries: - Without setting a workspace config, only the demo repository is allowed, and the entire computer is not exposed. - Real local projects use ignored `mcp-workspace.config.json` settings. - If you expose the exact `POST /mcp` to ChatGPT Web, read-only workspace tools in no-auth mode can still read allowed roots; including `list_dir`, `read_file`, `read_many`, `search_files`, `git_status`, `git_diff`, and `project://file`, `project://search`, `project://agents`. - `write_file`, `patch_file`, and non-allowlisted `run_command` require a one-time approval token displayed on the local dashboard. - Approval tokens only appear on the localhost dashboard and are not returned through MCP response/resource. ## Private GitHub Upload This repository uses the GitHub CLI's system keychain login state by default, eliminating the need for re-login on each push. Re-login is only required when logging in for the first time or when the token expires. Daily secure upload: ```bash python3 -m scripts.github_publish ``` If there are changes to be committed and pushed: ```bash python3 -m scripts.github_publish --commit-message "Update project" ``` This script confirms that the GitHub repository is private and runs `release_check` before pushing. For more details, see `docs/github-publish.md`. ## One-Click Prompt Words for Codex If Codex supports local skills, please use `$chatgpt-mcp-codex` first. This repository also provides a visible skill version in `skills/chatgpt-mcp-codex/`; real personal domains should only be placed in ignored `references/local-binding.private.md` and not submitted. ```text Please install and start ChatGPT mcp Codex in this repository. Please use the planning mode to ask me which ChatGPT HTTPS connection scheme to use: A. Free temporary URL: fastest available, but URL may change after restarting the tunnel. B. Fixed URL with your own domain: requires a Cloudflare-managed domain, but ChatGPT connector usually only needs to be set once. Please execute in sequence: python3 -m scripts.bootstrap_local python3 -m scripts.doctor If the Hub is not started, please tell me to run in Terminal A: python3 -m scripts.up Then please tell me to run in Terminal B: python3 -m scripts.run_codex_worker --loop --fake-exec Finally, please execute: python3 -m scripts.print_mcp_info And tell me in plain language: 1. Dashboard URL 2. Local MCP URL 3. HTTPS connector URL format required by ChatGPT 4. Differences between localhost and HTTPS tunnel 5. Is this computer the execution location of the Codex worker? 6. If I choose a fixed URL scheme, please tell me which hostname to provide. ``` ## More Documents - `docs/localhost-vs-https.md` - `docs/article.md` - `docs/chatgpt-setup.md` - `docs/tunnel-options.md` - `docs/workspace-tools-v2.md` - `docs/codex-agent-install.md` - `docs/github-release-checklist.md` - `docs/github-publish.md` - `docs/local-run.md` - `docs/security-model.md`